Inspiration
Small online sellers on PayPal often lose "Item Not Received" disputes even though they shipped the order. The proof exists, but it's spread across the store, the carrier, PayPal and the seller's inbox. It has to be found, matched up and submitted before a short deadline. Most small merchants don't have a team for that, so they either scramble or give up the sale.
We asked: what if the evidence were already assembled and checked before the dispute ever arrived? We also didn't want an AI that could make up evidence and file it on a merchant's behalf. Disputed needed to be useful and impossible to fool at the same time.
What it does
Disputed is a dispute-prep agent for PayPal merchants, starting with Item Not Received cases for physical goods.
- A separate Verifier agent checks every claim against the original documents, including the drafted reply. It marks each one assupported or missing, and rejects claims the evidence doesn't back.
- A Submission Guard sends evidence to PayPal's provide-evidence API only when the evidence holds up, the dispute state allows it, and the merchant approves. This check is ordinary code with fixed rules, not AI.
- Everything is audited. An append-only activity log records every agent step, result, error, duration and token count.
How we built it
- Backend: NestJS 11 modular monolith inTypeScript. It's split into nine modules: Merchants, Event Ingestion, Transactions,Evidence Vault, Investigator, Verifier, Disputes, Submissions and Monitoring.
- Data: PostgreSQL on Supabase with Prisma, and private Supabase Storage for evidencefiles.
- PayPal: OAuth, signature-verified webhooks,Orders v2 enrichment, dispute events and buyer messages, and provide-evidence behindthe Submission Guard. All of it runs against PayPal Sandbox.
- AI: NVIDIA Nemotron 3.5 Super VL (a vision-language model). We also built aswappable OpenAI Responses adapter. The agents follow a small JSON protocol(READ_EVIDENCE / FINISH) with strict schemas. Every model output is validatedwith Zod before anything runs, and the prompts are versioned.
- Frontend: React 19 + Vite, Tailwind/shadcn-style components, SupabaseAuth.
- Shared contracts: Zod schemas in a pnpmmonorepo package, used by both API and web.
- Infra: API and worker on Render
Challenges we ran into
- Keeping the AI honest. An agent that sounds confident but invents a tracking number is worse than no agent. That's why a second agent verifies every claim, model output is schema-validated, the provider never switches silently, and the system returns an error instead of a made-up result.
- Sandbox limits. Some dispute flows in PayPal Sandbox are hard to trigger on demand, so we had to plan the demo around what Sandboxcould actually do.
- Integrity of evidence. Records get refreshed, re-ingested and rebuilt into new versions. We had to make sure every refresh was idempotent and could never silently overwrite an original.
- Deployment details. We hit Supabase URL/SSL mismatches and auth redirect configuration
Accomplishments that we're proud of
- A real end-to-end flow.
- Two agents that check each other, plus a deterministic guard. The AI can't submit anything on its own.
- A reply to the buyer drafted from evidence,so the merchant can answer within seconds.
- 212 automated unit and HTTP tests, plustests against a real PostgreSQL database, all running in CI.
- A complete audit trail of what each agent did, how long it took and what it cost intokens.
What we learned
- In high-stakes workflows, verification matters more than generation. The most valuable thing our AI did was say "this isn't good enough to submit."
- Tackling disputes before they happen changes the problem. Most of the work can be done while there's no deadline.
What's next for Disputed
- Further store and carrier integrations (Shopify, WooCommerce, major carriers)
- Outcome tracking to learn which evidence actually wins cases.
Built With
- javascript
- next.js
- react
- typescript