DisputeGuard

AI agent that protects small businesses’ money in PayPal disputes

Comment

Inspiration

For a small online seller, a PayPal dispute is a stressful chore: read the claim, dig up the payment, check tracking, decide whether to fight or refund, write a reply — all before a deadline. Miss the deadline and the money is gone. Big merchants have teams and tools for this; a one-person store has an inbox. We wanted to give small sellers an assistant that does the legwork and can be trusted with real money.

What it does

DisputeGuard connects to a seller's PayPal account and handles every dispute end to end:

  1. A new dispute arrives — PayPal pushes it to DisputeGuard by webhook (or it's picked up on sync).
  2. The AI agent investigates. Claude reads the dispute, looks up the payment, checks shipment tracking and the buyer's dispute history through PayPal APIs, and produces a structured assessment: fight, refund or ask the seller, a confidence score, the key facts with their sources, available and missing evidence, and a ready-to-send response.
  3. Code decides, not the AI. A deterministic policy engine checks the recommendation against the seller's rules and hard guardrails: amount limit, currency, dispute stage, minimum confidence per action, and delivery verified against PayPal tracker records.
  4. It acts — or asks. If everything passes, DisputeGuard executes in PayPal right away: accepts the claim (refund), submits evidence, or messages the buyer, choosing only actions PayPal currently allows for that dispute. Otherwise the case lands in "Needs your approval" with the draft response and the exact reason it needs a human.

Sellers write rules in their own words — "If the buyer was charged twice, refund right away" — and the AI turns them into structured conditions shown back as chips before saving. Every step is visible: a live investigation timeline, the facts the agent found, the checks the rules ran, and what was sent to PayPal.

How we built it

  • PayPal (sandbox): OAuth 2.0, Disputes API (list, details, accept-claim, provide-evidence as multipart, send-message), Transaction Search, Shipment Tracking, and Webhooks (CUSTOMER.DISPUTE.*) with signature verification via PayPal's verify-webhook-signature API. Execution follows the HATEOAS links on each dispute, so the agent never attempts an action PayPal won't accept.
  • AI: Claude via the Vercel AI SDK. The investigation is a tool-calling agent (get_dispute, get_transaction, get_shipment_tracking, list_disputes) that must finish with a Zod-validated submit_assessment; invalid submissions are returned with fix hints so the agent corrects itself. Plain-English rules are parsed with structured output into typed conditions.
  • Policy engine: a pure TypeScript function with unit tests — the part that decides whether money moves.
  • App: Next.js 15 (App Router, server actions), TypeScript, Tailwind CSS, AG Grid for the disputes table, Drizzle ORM on Neon Postgres, deployed on Render. CI on GitHub Actions runs typecheck and tests.

Challenges we ran into

  • Sandbox realities. Transaction Search lags hours behind new payments, so the agent learned to rely on the dispute record itself (including PayPal's extensions, where duplicate-charge disputes reference the original transaction) and treat "not found yet" as an indexing delay, not missing evidence.
  • "Allowed" depends on the dispute's state. Submitting evidence while PayPal was reviewing a case returned HTTP 422. We switched to reading the dispute's available actions before executing and show a clear "PayPal is reviewing" state instead of a failure.
  • Model output discipline. The model sometimes sent arrays as JSON strings. A normalizer, a stop condition that only accepts a valid submission, and fix hints in the tool result made investigations reliable.
  • Moving money safely. Webhooks, auto-sync and a seller's clicks can race. Decision state changes are atomic, and at most one PayPal action can ever run per dispute.

Accomplishments that we're proud of

  • A fully autonomous refund on the live demo: a duplicate-charge dispute arrived by webhook, the agent investigated it, the rules allowed it, and PayPal accepted the claim — with no human click.
  • The AI never gets the final say on money. Even "delivered" is re-checked against PayPal's tracker records before a rule can use it.
  • Rules a non-technical seller can write and read.

What we learned

Agents are most useful when their authority is explicit. Splitting the job — the model investigates and explains, deterministic code decides and enforces limits — made the system both more capable and easier to trust. We also learned to design around the payment platform's state machine instead of fighting it.

What's next

  • Evidence uploads (invoices, delivery photos) and carrier-scan lookups
  • Multi-seller accounts with sign-in and per-store rules
  • Notifications (email/Slack) for cases that need approval
  • Weekly reports: money protected, time saved, dispute patterns by product
  • Live PayPal environment after a security review

Built With

  • ag-grid
  • anthropic
  • claude
  • drizzle-orm
  • github-actions
  • neon
  • next.js
  • paypal
  • paypal-disputes-api
  • paypal-webhooks
  • postgresql
  • react
  • render
  • tailwindcss
  • typescript
  • vercel-ai-sdk
  • zod
Share this project:

Updates

Submission history