Dispute Shield

AI agents that settle PayPal disputes for small sellers, negotiating directly with the buyer's own AI shopping agent, with every money move approved by the seller.

Comment

Inspiration

Small sellers on PayPal describe the same chain of problems: a buyer disputes a sale, the seller has about ten days to respond, fees apply even when they win, and a rising dispute ratio can lead to an account review with funds held for up to 180 days. Large merchants pay chargeback services to handle this. Small sellers handle it alone.

AI shopping agents are about to add a new kind of dispute. An agent buys the wrong size, misses a note in a listing, or misreads what its human wanted. Neither side has a clear record of what the person actually asked for. We wanted to build the dispute layer for that world.

What it does

DisputeShield has two AI agents and a seller console.

  • Buyer shopping agent. A person types "Buy me a blue hoodie in size M, under $40". The agent picks the item, creates a PayPal order, and stores a purchase-intent record: what the person asked for, their constraints, and why the agent chose this item. The person approves the payment in PayPal's own checkout window, so the agent never holds credentials.
  • Seller agent. When a PayPal dispute arrives, the agent investigates with tools that read the live dispute (reason, buyer notes, PayPal's own Seller Protection result, deadlines), the order and tracking, the listing the buyer saw, and the purchase-intent record. It recommends Fight, Settle or Accept, with a win probability, its reasoning, and drafted evidence or a suggested offer.
  • Agent-to-agent settlement. For disputes worth settling, the seller's agent and the buyer's agent negotiate in structured turns (offer, counter, accept, reject). In our test dispute, the seller agent opened at a $10 partial refund, the buyer agent admitted it had been warned that the hoodie runs small and countered at $19, and they agreed on $14.
  • The seller approves every money move. One click sends the agreed offer through the PayPal Disputes API (make-offer), with a summary of the negotiation as the note. The same panel can submit evidence (provide-evidence) or accept the claim (accept-claim). The buttons follow what PayPal currently allows on each dispute.
  • Seller console. An AG Grid table of disputes with the AI's recommendation, win chance, Seller Protection status and deadline, plus orders with one-click tracking upload to PayPal, account health (dispute ratio, open cases, fees avoided), the negotiation transcript and an activity log.

How we built it

  • PayPal (sandbox): Orders v2 (create, capture, get), Orders v2 tracking, the JavaScript SDK (PayPal Buttons), Disputes v1 (list, get, make-offer, provide-evidence, accept-claim, plus the sandbox require-evidence and adjudicate endpoints for demos), and Webhooks (CUSTOMER.DISPUTE.* with signature verification).
  • AI: Claude through the official Anthropic SDK, running claude-sonnet-5-5 with adaptive thinking. The seller agent is a tool-using agent built on the SDK's tool runner; its tools call PayPal and read the order, listing and intent record, and it ends by filing a structured assessment. The buyer agent and each negotiation turn also use tool calls, so every output is structured, not free text we have to parse.
  • App: Next.js 16 and TypeScript, AG Grid for the dispute and order tables, a custom soft-UI design system, hosted on Render from a render.yaml blueprint.
  • Guardrails: agents can read PayPal data but never move money. Every money-moving call runs only from one approval endpoint after the seller clicks. The seller agent has a refund ceiling, and the public demo caps agent runs per hour to limit cost.

Challenges we ran into

  • Disputes that didn't show up. Our first sandbox dispute existed in PayPal but our sync returned nothing. PayPal's dispute list omits disputes under review unless start_time is set, and it rejects a start of 180 days or more. We now send 179 days and read every page.
  • Messages that changed the dispute state. We first copied every negotiation turn into the PayPal dispute thread. Each seller message moved the case to "waiting for buyer", which blocks make-offer, and the buyer agent's turns were recorded as seller messages. We changed the design: the negotiation stays inside DisputeShield, and one make-offer carries the agreed terms plus a summary of the negotiation.
  • Sandbox accounts by country. Checkout failed until we switched to US sandbox accounts; payments between two India-registered sandbox accounts don't go through.

Accomplishments that we're proud of

  • The full loop runs on the real PayPal sandbox: an AI agent buys an item, the buyer files a dispute, the seller agent assesses it, the two agents agree on $14, the seller approves, and PayPal receives the offer.
  • The agents reason honestly. The buyer agent warned its human about the sizing note before checkout, then admitted it during the negotiation, which pushed the outcome toward a fair middle.
  • A clear human-in-the-loop design: the AI does the investigation and negotiation, and the seller makes the decision.

What we learned

  • Each PayPal dispute's links tell you which actions are allowed right now; designing the UI around them avoids a whole class of errors.
  • Purchase-intent records make agent disputes much easier to settle fairly: "what did the person actually ask for?" stops being a matter of opinion.
  • Agents work best with structured tool outputs and a single, explicit approval point.

What's next for DisputeShield

  • Open up the Agent Dispute Protocol so any shopping agent can share its purchase-intent record with any seller.
  • Prevention before disputes happen: flag risky orders and upload missing tracking automatically.
  • Multiple sellers, a real database, and learning from past outcomes to calibrate win probabilities.

Built With

  • ag-grid
  • anthropic
  • claude
  • next.js
  • paypal
  • paypal-disputes-api
  • paypal-javascript-sdk
  • paypal-orders-api
  • react
  • typescript
Share this project:

Updates

Submission history