Dispute Copilot
An AI copilot for small PayPal sellers. It pulls every open dispute from the PayPal Disputes API, ranks them by deadline and money at risk, and for each one recommends fight with evidence, offer a partial refund, or accept — with the score broken down, the evidence PayPal asks for, and a drafted response. Nothing reaches PayPal until the seller previews the exact request and clicks Approve & send.
Live demo: https://dispute-copilot-7vbm.onrender.com (Render free tier: first request after idle can take ~50 s)
Honest status: the live demo runs in mock mode (five sample disputes from fixtures/disputes.json) until PayPal sandbox credentials are connected. AI drafting (Gemini 2.5 Flash) is on only when the deploy has LLM_API_KEY; check /api/health — "drafter":"llm" means AI drafts, "template" means the deterministic fallback, and the header badge says which. The public demo is read-only: Preview works, Approve returns 403 because no ADMIN_TOKEN is set there. The real-API code paths (OAuth, pagination, order/tracking facts, multipart evidence upload, read retries) are unit-tested against mocked PayPal responses, not yet against the live sandbox.
Built for the PayPal AI Hackathon (2026). Sandbox only: the client refuses any non-sandbox PayPal URL.
Run it (no keys needed)
npm install
npm start # builds, then serves http://localhost:3000
npm test # vitest
Without keys the app runs on fixtures/disputes.json (five sample disputes) and a template drafter; badges at the top say so.
Use your PayPal sandbox and an LLM
Copy .env.example to .env (or set the variables in your shell):
| Variable | Purpose |
|---|
PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET | Sandbox REST app from developer.paypal.com → Apps & Credentials → Sandbox |
PAYPAL_BASE_URL | Must be https://api-m.sandbox.paypal.com |
LLM_API_KEY, LLM_BASE_URL, LLM_MODEL | Any OpenAI-compatible chat endpoint. Default: Gemini 2.5 Flash (free tier) |
MODE | mock forces the sample disputes even when PayPal keys are set (the public demo runs this way) |
ADMIN_TOKEN | Required for Approve & send (header x-admin-token; the UI has an Unlock field that keeps it in memory only). Unset = the server refuses every write with 403 |
How it decides
- Evidence plan — maps the dispute
reason to PayPal evidence_type values and marks which ones the order facts already cover.
- Win score (0–100) — a transparent rule score; every point is a labelled factor.
- LLM writes, code decides — Gemini gets the code-chosen action, the score factors, the evidence plan and the facts (buyer messages fenced as untrusted data; prompt in
buildPrompt, server/src/drafter.ts). It returns a one-paragraph assessment for the seller and the draft PayPal will receive, and may suggest a score nudge of at most ±15 with a reason; code clamps it and re-runs the thresholds. Successful drafts are cached per dispute state so reloads do not spend the free quota. Any model failure (HTTP error, timeout, malformed JSON) falls back to the deterministic template.
- Action — FIGHT ≥ 60, OFFER 30–59 (half the amount), ACCEPT < 30 or amount under 15.
- Missing facts never become a silent refund — if the order, capture or tracking cannot be read, the case is marked insufficient facts and routed to FIGHT-review by a human.
- What PayPal allows —
status, allowed_response_options and the dispute's action links decide which of the three actions can be sent; the others are disabled in the UI and refused by the server.
- Human gate — preview → approve →
provide-evidence / make-offer / accept-claim. If the model's score nudge changed the action the rules picked, the UI shows a red AI changed recommendation — confirm notice and Approve needs an explicit checkbox (confirmed: true). Approve sends exactly the last previewed request (single-use previewId, 10 min) and never re-runs the LLM; without a current preview it answers 409 Preview first.
Safety
- Writes need
ADMIN_TOKEN; without it the server is read-only. Per-IP rate limit on /api: 30 reads/min, 5 writes/min.
- PayPal calls: 15 s timeout. Reads (GET) get one retry with backoff on 429/5xx. Writes (make-offer, provide-evidence, accept-claim) are sent exactly once and never retried: on a timeout or 5xx the server answers 502 "Status unknown — verify in PayPal Resolution Center", because PayPal may already have applied it. Errors surface as
{status, reason} with only PayPal's name, message and details[].issue.
Cache-Control: no-store on the API; CSP (self only, plus data: for the grid's icon font), X-Frame-Options: DENY, nosniff, Referrer-Policy: no-referrer.- Sandbox only: the client refuses any non-sandbox PayPal URL. The mock demo resets approvals every 10 minutes.
PayPal APIs used
POST /v1/oauth2/token, GET /v1/customer/disputes (paginated), GET /v1/customer/disputes/{id}, GET /v2/payments/captures/{id}, GET /v2/checkout/orders/{id}, GET /v1/shipping/trackers/{id}, POST /v1/customer/disputes/{id}/provide-evidence, POST /v1/customer/disputes/{id}/make-offer, POST /v1/customer/disputes/{id}/accept-claim.
Stack
TypeScript, Express, AG Grid Community (dispute queue), esbuild, vitest.
License
MIT
