FairHold

Refundable deposits resolved fairly: PayPal holds the deposit, AI drafts an evidence-quoted proposal, and the owner decides what to capture.

Comment

Inspiration

Lending a tent, camera, or tool is easy until it comes back damaged and both people must agree on a deposit deduction. FairHold gives the renter a PayPal authorization hold and gives the owner an AI-drafted, evidence-quoted starting point for a fair conversation. The owner makes the payment decision.

What it does

  1. The owner records the item's baseline condition and a deposit amount. FairHold issues separate owner and renter access keys.
  2. The renter approves a PayPal sandbox authorization. This is a hold, not an immediate charge.
  3. At return, either party submits a condition report. The AI proposes itemized deductions with verbatim quotes from that report. The server verifies each quote, recomputes the total, and caps it at the authorized amount. The proposal is advisory: it cannot prove damage or establish repair costs.
  4. The owner can adjust the amount and confirm a final partial capture, or release the entire hold. The receipt shows PayPal's actual capture and authorization statuses, plus an event timeline. Pending captures go to reconciliation rather than being reported as completed.

How I built it

The frontend uses React, TypeScript, Vite, Tailwind CSS, and the PayPal JavaScript SDK with intent=authorize. The Node/Express backend uses PayPal Orders v2 and Payments v2 for authorize, capture, void, and reconciliation. An OpenAI-compatible model produces structured JSON proposals, which are validated with Zod and checked against the submitted report. Amounts are kept as integer cents. Payment mutations use per-rental role keys, idempotency IDs, application replay protection, and state-machine rules. The earlier verified sandbox run used Replit with PostgreSQL transactions and rental locks; the current judging demo runs on Render’s free web service with a Neon free PostgreSQL database.

Challenges and lessons

PayPal authorization, capture acceptance, and completed capture are distinct states. The app only resolves a rental after PayPal reports a completed capture. I also learned that AI around money needs bounds, quote verification, and a human decision gate. AI has no payment tools or provider secrets.

Verified demo and how to try it

A real hosted sandbox run verified a $60 authorization, a live-model $35 two-item proposal with both evidence quotes present, an owner-selected $18.50 completed partial capture, idempotent retry, and a separate $40 void. The video shows this recorded evidence and the app workflow. See VERIFICATION_HOSTED.md in the repository for transaction IDs and limits.

The hosted judging demo is https://fairhold-demo.onrender.com/. It is protected by a judge login; the password will be provided in Devpost’s judge-only testing instructions. The free Render service may take around a minute to wake after inactivity. The current deployment uses clearly labeled PayPal simulation and AI fixture modes, so no real money moves and no external API keys are needed. Alternatively, run the functional local demo: install Node.js 22.12+, then run npm ci and npm run dev. Open http://localhost:3000 and select Fill sample scenario. With no credentials, PayPal and AI run in clearly labeled simulation/fixture modes; the full workflow remains usable. Configure your own PayPal sandbox and compatible AI credentials only if you want to reproduce external calls. README.md has the steps. No payment or paid account is required to test the local demo.

Next steps

This is a sandbox prototype with demo-grade role keys and a shared workspace. Production would need user accounts, tenant isolation, verified webhooks, dispute messaging, and richer condition evidence.

Built With

Share this project:

Updates

Submission history