Inspiration
Picture this: a customer says their package never arrived. The seller has tracking that proves it was delivered, but submits an order confirmation instead. They lose the dispute, not because they lacked evidence, but because they submitted the wrong kind.
When a buyer opens a PayPal dispute or card chargeback, the seller has limited time to respond, and the evidence that matters changes with the dispute reason.
Large retailers have dedicated dispute teams. Small sellers are often on their own, juggling orders, shipments, and customer messages while trying to understand PayPal's requirements.
I built DisputeDraft to give small merchants something they usually can't afford: a dispute specialist who investigates each case, finds the right evidence, and prepares a response.
What it does
DisputeDraft is an AI-powered dispute co-pilot for PayPal merchants. It takes a dispute from an overwhelming inbox item to an evidence-backed, ready-to-submit response.
- Inbox: Pulls open disputes from PayPal, showing the reason, amount, stage, and deadline in an AG Grid dashboard.
- Investigate: An AI agent pulls the dispute from PayPal using the PayPal Agent Toolkit, then cross-references the seller's store records (order, shipment tracking, buyer messages, and policies) through its own tools.
- Evaluate evidence: Builds a reason-specific checklist, marking each piece of evidence as found, weak, or missing.
- Recommend a strategy: Suggests whether to contest the dispute, offer a partial refund, or message the buyer, based on the available evidence and the actions PayPal currently permits.
- Draft a response: Generates a structured, factual response grounded in the merchant's records, without inventing claims or evidence.
- Approve and submit: The seller reviews and edits the response, then explicitly approves it. DisputeDraft submits through PayPal's Disputes API and refreshes the dispute state.
The agent investigates. The rules guide the recommendation. The human makes the final decision.
Unlike a generic chatbot that simply writes an appeal, DisputeDraft investigates the underlying transaction, explains what evidence is missing, and connects its recommendations to real PayPal actions.
How I built it
- Frontend: Next.js and React, with AG Grid for the dispute inbox.
- PayPal integration: PayPal Sandbox REST APIs for Orders and Disputes, with the PayPal Agent Toolkit (
get_dispute) integrated into the agent's tool-calling loop. - AI: Google Gemini through the Vercel AI SDK.
- Validation: Zod for structured, schema-validated AI output.
- Hosting: Render.
The AI workflow has three stages:
Stage 1 — Investigation: The agent calls tools to collect the dispute from PayPal and the matching store records.
Stage 2 — Strategy: A deterministic playbook evaluates the evidence against the dispute reason and the actions PayPal allows at the dispute's current stage.
Stage 3 — Drafting: Gemini writes the response from the verified case facts and the selected strategy.
The key architectural decision was simple: rules decide, AI writes.
Rather than letting the language model freely choose financial actions, the playbook keeps recommendations predictable and explainable. The model handles investigation and natural-language generation, while the seller keeps control over submission.
For the demo, I created Fernhill Goods, a fictional merchant with five real PayPal sandbox orders and five real disputes opened through the sandbox buyer account. Because sandbox has no real store behind it, the store records (shipments, listings, buyer messages, policies) are mock data written for each order.
The five cases cover distinct situations: an item still in transit, an item marked delivered, an unauthorized transaction at the chargeback stage, and two not-as-described disputes with different evidence strengths. Each one exercises a different checklist, recommendation, and PayPal action.
Challenges I ran into
1. Getting PayPal's evidence submission API to work
The API specification didn't clearly show the multipart format provide-evidence expects. I wrote sandbox probe scripts and tested request formats until I found the working structure: a form part named input containing JSON, with evidence classified as PROOF_OF_FULFILLMENT and the tracking information attached.
2. Dispute actions aren't available at every stage
A not-as-described dispute at the inquiry stage may not allow provide-evidence at all, so hardcoding one response action would fail.
DisputeDraft reads the HATEOAS links PayPal returns and only recommends actions the current dispute state supports: submitting evidence, making an offer, or messaging the buyer.
3. Submitting evidence is a one-way door
Once evidence is submitted, PayPal moves the dispute to a stage where the same response can't be sent again, which made end-to-end testing surprisingly hard.
I built a re-seeding script that creates fresh sandbox orders and walks through opening new disputes. The app also reads PayPal's own dispute record to decide whether a response has already been submitted, rather than relying on local flags.
4. Working around free-tier model limits
Each investigation takes about three model calls, and the free tier allows roughly 20 requests per model per day—only about six full analyses.
I built a fallback chain across three Gemini models for rate limits, service errors, and timeouts, and saved an analysis for each demo dispute. If live analysis is rate-limited, each dispute still shows its saved checklist, recommendation, draft, and agent trace.
Accomplishments that I'm proud of
Getting the complete flow working against real PayPal sandbox disputes: from retrieval and investigation to a human-approved submission that PayPal accepts and that changes the dispute's status.
What I learned
Integrating an AI agent into a financial workflow is about much more than prompting.
- Grounding matters: A convincing response is useless if its tracking numbers, dates, or claims are invented.
- API state matters: The right recommendation depends not only on the evidence, but on what PayPal permits at that stage.
- Human approval matters: AI can gather facts and prepare actions without needing authority to execute them.
- Observability matters: Showing the evidence checklist, the reasoning behind the recommendation, and the agent trace makes the system easier to inspect and trust.
Most importantly, building a useful AI product often means giving the model less control over critical decisions, not more.
What's next for DisputeDraft
- Merchant onboarding with secure PayPal account connections and real store integrations in place of mock records.
- Webhooks to detect new disputes and status changes automatically.
- Evidence attachments for receipts, product photos, shipping documents, and PDFs.
- Batch triage to investigate and prioritize a whole dispute inbox at once.
The goal is to make dispute handling less intimidating for small merchants, so that having the right evidence matters more than knowing how to navigate the dispute process.
Built With
- ag-grid
- github
- google-gemini
- javascript
- next.js
- node.js
- paypal
- paypal-agent-toolkit
- paypal-rest-api
- react
- render
- vercel-ai-sdk
- zod
