Inspiration
Every PayPal dispute comes down to one person's word against another's.
Picture a small block-print studio in Jaipur that ships a hoodie to a buyer in Ohio. The buyer says the seam came apart. The seller says it left the table perfect. Neither side can prove anything. "Item not as described" claims fall outside PayPal Seller Protection, and for a small exporter one dispute fee can wipe out the profit on several orders.
The buyer has a problem too. They are paying a foreign store they have never heard of, with no reliable way to know whether it delivers.
We realised that both sides are missing the same thing: a witness. One side's proof could become the other side's trust. That idea became Fairfold.
What it does
Fairfold is a neutral witness for both sides of a PayPal payment. It never touches the money, and PayPal still decides every dispute.
- Before the buyer pays: a Store Report shows the store's fulfilment record, reviews from verified payments and verifiable facts, with a source behind every claim.
- Before the merchant ships: a Buyer Signal (green, yellow, red, or grey for any new buyer) comes with its reasons and a recommended action. It is never a fraud verdict, and the advice is never "cancel".
- At the packing table: the Pack Station uses AI to read the photographed item, size label and batch tag. Code checks them against the PayPal order, seals the evidence in a SHA-256 hash chain and queues tracking for PayPal.
- When complaints pile up: Shared Cause Detection tests whether repeated complaints share a production batch, courier, listing or packer. It compares complaint rates per day each order has been out, so an older batch isn't blamed just for being older, and it corrects for testing many explanations at once. Then it proposes holding unshipped orders, an inspection step and honest messages to the affected buyers.
- When a dispute opens: the Dispute Room joins the PayPal capture to the order's proof and builds the evidence pack. If the merchant's own batch is at fault, it recommends a fair remedy instead of fighting a case the merchant shouldn't win.
- For AI shopping agents: the same Store Report is exposed as an MCP tool. A shopping agent checks the store, asks its human, and only then pays through PayPal.
AI describes. Code decides. Humans approve. Nothing is submitted, held, sent or refunded without the merchant's explicit approval.
How we built it
- PayPal (sandbox only): JavaScript SDK v6 checkout, Orders v2 (create, capture, tracking), Payments v2 refunds, Customer Disputes v1 and verified webhooks with a reconciliation poll. We also used the PayPal Agent Toolkit, with
context.sandbox = trueset explicitly. Every PayPal call goes through one package,packages/paypal. The Toolkit can list disputes but cannot attach evidence, so we added aprovide_dispute_evidencetool in the same style. - AI: every model call goes through one gateway,
packages/ai, built on the Vercel AI SDK. The gateway enforces structured output, timeouts and fixed fallbacks. Text from buyers and reviewers is passed in as untrusted, quoted data, and those calls get no payment tools. Models only see, read, draft and explain. - Deterministic code: buyer bands, match decisions, recommendations and statistics are small, tested, pure functions with reason codes. Shared Cause uses an exact conditional test for two Poisson rates, Benjamini–Hochberg correction and Wilson intervals.
- Evidence ledger: each entry's hash is
SHA256(previous_hash + canonical_JSON(entry)), so changing a single stored byte breaks the chain. - Approvals as data: an approval and its job are written in the same database transaction. A background worker re-fetches the dispute from PayPal and checks it is still allowed before doing anything.
- Stack: TypeScript, Fastify (REST, OpenAPI and MCP on one origin), PostgreSQL 16 with pg-boss jobs, and a separate worker. The website, API, worker and private database are deployed on Render.
Challenges we ran into
- The data we first imagined doesn't exist legally. Shopping histories and social complaints aren't available, and a buyer score pooled across merchants raises consumer-reporting questions. We rebuilt both scores on PayPal data, the merchant's own history, reviews from verified payments and verifiable site facts. Buyers can see and contest their own band. Cross-merchant data appears only as a clearly labelled simulation.
- Small numbers lie. A handful of complaints can look like a pattern by chance. We measure exposure in order-days, require a minimum number of complaints and a corrected significance level, and show the merchant the confounders (couriers, packers, ship weeks) next to the result.
- Webhooks are unforgiving. Signature verification needs the original raw bytes, so we keep them and store every event durably. We never process a message that hasn't been verified, even when the simulator's test postbacks fail.
- Getting it hosted. Our first Render deployment hit capacity and billing roadblocks. We kept the same topology (website + API, worker, private PostgreSQL) and deployed it service by service instead of redesigning.
- Building as two people in parallel. One of us owned the PayPal and platform side and the other owned the AI and intelligence packages. We agreed shared contracts up front and integrated carefully without rewriting each other's work.
Accomplishments that we're proud of
- A live, working website on Render, with 393 synthetic orders, 85 reviews and 16 complaints across three stores, and no sign-up needed to explore the merchant console.
- On our synthetic demo store, Shared Cause Detection singled out batch B17 from 13 candidate explanations: 5 of 39 orders against 1 of 200 from every other batch, a rate ratio of 25.6 after multiple-testing correction. It also listed the 18 unshipped orders to hold.
- The Buyer Signal gives the expected band for 30 of 30 synthetic buyer profiles, including grey (never red) for a buyer with no history. Dispute recommendations match our decision table in 8 of 8 scripted cases.
- Prompt injection can't move a score. Code computes bands and scores, and a narrative that invents a number or date is rejected and replaced with a template.
- An honest product. When the AI provider isn't configured, Shared Cause shows a truthful empty state instead of inventing a hypothesis. Every synthetic record and sandbox action is labelled.
- All 42 numbered API contracts from our architecture appear in the generated OpenAPI, and nearly a thousand automated tests pass.
What we learned
- Trust is two-sided. The evidence that protects an honest merchant also reassures the next buyer. When the merchant is at fault, the same evidence tells them early enough to make it right.
- The line between AI and code is the product. Letting models describe while code decides made the system explainable, testable and resistant to prompt injection.
- Human approval has to be real. It has to be a durable record that is checked again just before anything changes, not a button label.
- Honest labels build more confidence than polished fakes. An empty state that tells the truth beats a convincing mock.
What's next for Fairfold
- Finish full end-to-end runs in the PayPal sandbox: a real purchase, a dispute and an approved evidence response.
- Measure photo checks and complaint clustering against live model providers.
- Add Content Credentials to packing photos so the evidence carries its own provenance.
- Design a PayPal-run network tier with consent and dispute rights built in.
- Pilot with small Indian exporters selling overseas through PayPal.
Built With
- docker
- drizzle-orm
- esbuild
- fastify
- model-context-protocol
- node.js
- openapi
- paypal-agent-toolkit
- paypal-disputes-api
- paypal-javascript-sdk
- paypal-orders-api
- paypal-payments-api
- paypal-webhooks
- pdf-lib
- pg-boss
- pnpm
- postgresql
- render
- sharp
- swagger
- typescript
- vercel-ai-sdk
- vitest
- zod