Important: what is real and what is not
Everything runs on PayPal sandbox. No real money moves, and every sample document is fake. The video narration is AI-generated. The repository was created on Oct 30, 2026, after the hackathon started on Oct 1.
Inspiration
Small and mid-sized exporters trade on relationships that last decades. When an order is large, that trust is the only protection they have, and it fails more often than anyone admits: a buyer pays late, short, or not at all, or goods come back and nobody agreed who pays. Letters of credit solve it but are slow and expensive, so small traders skip them. We wanted the safety of escrow with the ease of a handshake.
What it does
EscrowPilot is milestone escrow for importers and exporters, built on PayPal and Gemini AI.
- Buyers and sellers propose payment terms inside the app: milestones, inspection window, and what happens if delivery fails (refund percent, return shipping, proof of return). Both sign the same version; any edit voids the signatures.
- The seller puts down a refundable 5% security deposit through PayPal first, so both sides have something to lose.
- The buyer pays each stage into escrow through PayPal just before it starts. Money moves per stage only when the seller's documents (PDF, photo or text) match the signed terms.
- Gemini reads the documents and extracts fields. Plain code compares them to the contract. A mismatch goes to a review queue with the exact reason. The AI never decides who gets paid.
- A dispute plus proof that the goods were sent back unlocks a refund of exactly the signed percent, but only after the seller has checked the returned goods.
- Every step is written to a hash-chained audit log, and payouts use idempotency keys so nothing is paid twice.
Fairness by design: a fault ruling waits 48 hours, either side can appeal once to a different reviewer whose decision is final, documents are cross-checked against earlier stages, a reused file is flagged, and the reviewer sees a facts-only AI evidence summary that never recommends a verdict. If the seller is ruled at fault, the buyer gets a full refund plus 2% and we keep 3% of the deposit. If the buyer is at fault, they lose 5% (2% to the seller, 3% to us). Revenue: a 2% fee on each released milestone.
How we built it
FastAPI and SQLAlchemy backend, React and Vite frontend, PostgreSQL (Neon) in production. PayPal Orders and Payouts APIs in sandbox, behind a small funds-holder interface so a licensed partner can replace it. Gemini extracts document fields as JSON; the document is treated as untrusted text and the model has no tools. A deterministic rules engine owns every payment decision. 60 automated tests cover the full flow, mismatches, disputes, refunds, idempotency, permissions and uploads. Frontend on Vercel, API on Render.
Challenges we ran into
Deciding where AI belongs. Letting a model approve payments is a security hole, so it only extracts facts and code decides. PayPal authorisation holds expire after 29 days, so we capture up front and pay out per milestone. Designing failure terms that are signed in advance without becoming a legal contract engine.
Accomplishments that we're proud of
A complete flow from signed terms to settled or refunded, with the failure path as carefully built as the happy path, and a test suite that proves money cannot move twice or without a verified milestone.
What we learned
In trade, the hard part is not moving money, it is agreeing in advance on what counts as done and what happens when it is not.
What's next
Pilots with real exporters, first in shadow mode (their orders, documents and terms in EscrowPilot while money moves as today), then funded escrow through a licensed partner. After that, financing offered by partner lenders against verified, funded orders, and a trust score from deal history.
Try it
Live demo: https://escrowpilot-app.vercel.app (the free server may take about 30 seconds to wake on the first request). Code: https://github.com/Shalmankursheeth/escrowpilot-hackathon. Sample PDFs are in the sample_docs folder of the repo.
Built With
- fastapi
- gemini
- google-gemini
- jwt
- neon
- paypal
- paypal-payouts
- postgresql
- pypdf
- python
- react
- render
- sqlalchemy
- vercel
- vite
