Dispute Defender

An AI agent that answers every PayPal dispute in minutes: it fights the ones a seller can win and refunds the ones they can't.

Comment

Inspiration

When a buyer opens a PayPal dispute, the seller has a few days to answer with the right evidence. Large merchants have teams for this. A one-person shop usually doesn't: they answer late, send the wrong thing, or fight a case they should have refunded and pay a dispute fee on top. We wanted to give small sellers the dispute team they can't afford.

What it does

Dispute Defender watches a seller's PayPal account. When a dispute opens, an AI agent:

  1. Investigates: reads the dispute from PayPal, the payment and its Seller Protection status, the seller's own order record (tracking scans, delivery signature, digital access logs, support emails, warehouse notes) and the store's refund policy.
  2. Decides: fight, negotiate, settle or refund, with a win probability and the money maths behind it. It is built to concede quickly when the seller is in the wrong.
  3. Acts through PayPal: messages the buyer, makes an offer, escalates, submits evidence or supporting information with a generated PDF packet, or refunds the payment.

The seller approves each plan with one click, can edit any draft first, or turns on autopilot with a refund limit.

We tested it end to end on the real PayPal sandbox: a "not received" claim on signed-for headphones, where the agent fought and PayPal ruled for the seller, and a claim on mugs the carrier destroyed, where the agent refunded the buyer and PayPal settled the case.

How we built it

  • PayPal: Disputes API (list, show, send-message, make-offer, escalate, accept-claim, provide-evidence, provide-supporting-info, plus the sandbox require-evidence and adjudicate endpoints), Orders API v2 for the demo shop's checkout and shipment tracking, and Payments API v2 for capture details and refunds. Checkout, tracking, supporting info, refunds and adjudication were all exercised against the real sandbox; the inquiry-stage actions (message, offer, escalate, accept) run against a built-in simulator that mirrors the Disputes API, because sandbox disputes went straight to PayPal's review. A webhook endpoint with PayPal signature verification is included for instant pickup; the demo polls PayPal instead.
  • AI: an agent loop on Amazon Nova Pro through Amazon Bedrock's Converse API, with five read tools, seven "stage an action" tools and a structured assessment tool. The model provider is pluggable; Claude is supported as an alternative.
  • Guardrails in code, not in the prompt: the agent must commit to a strategy before it is offered any action, and then sees only the actions that fit that strategy and that PayPal currently allows. Only approved code calls PayPal. Every action is re-checked against the live dispute at send time, offers can't exceed the disputed amount, and autopilot refunds are capped.
  • Money maths in code: the model only estimates the win probability \( p \). With disputed amount \( A \) and dispute fee \( F \), the expected value of fighting is computed as $$ EV_{\text{fight}} = p \cdot A - (1 - p) \cdot F $$ and compared with the cost of refunding, so the figures the seller sees always add up.
  • AG Grid powers the dispute inbox: custom cell renderers, filters, live row updates while the agent works, a totals row and CSV export.
  • Next.js and TypeScript for the app, pdf-lib for evidence packets, and the built-in PayPal simulator so the app runs without any credentials.

Challenges we ran into

  • Real disputes don't follow the textbook flow. Disputes filed in the sandbox skipped the buyer-seller conversation stage and went straight to PayPal's review, where the only seller action is "provide supporting info". We added that action, and a refund through the Payments API so the agent can still concede at that stage.
  • Keeping the agent honest. At first the model chose to fight the destroyed-parcel case because a fighting tool was the one on offer, and once claimed a carrier claim had been filed when it hadn't. Making it decide before acting, stating delivery proof plainly in the data, and moving all arithmetic into code fixed both.
  • Sandbox setup: payments between two Indian sandbox accounts fail with a generic error, so we used a US seller account.

Accomplishments that we're proud of

  • A complete real-sandbox loop: checkout, dispute, agent decision, PayPal action, PayPal ruling.
  • An agent that tells the seller when not to fight.
  • Money limits that hold no matter what the model, or a buyer's message, says.

What we learned

PayPal's HATEOAS links are the best source of truth for what an agent may do next, far more reliable than reasoning about dispute states. And for an agent that moves money, the model should decide while code enforces.

What's next for Dispute Defender

  • Pull order and tracking data from real stores (Shopify, WooCommerce) and carrier APIs instead of the simulated order system.
  • Learn from outcomes: compare predicted win chances with PayPal's actual rulings.
  • Dispute prevention: flag risky orders and nudge sellers to add tracking before a dispute ever opens.

Note on what is simulated

The seller's order system (tracking events, delivery signatures, access logs) is generated by the app, so each product exercises a different decision. PayPal itself is real: the disputes, payments, refunds and rulings shown in the demo come from the PayPal sandbox.

Built With

Share this project:

Updates

Submission history