-
-
Cleared: check every sale before PayPal does, keep the proof, and answer disputes with evidence.
-
Before the invoice, Cleared AI finds what causes disputes. Each fix writes the missing terms into the PayPal invoice.
-
The client opens a private delivery link and confirms with one click. Cleared records when, as proof.
-
A $250 dispute arrives. The agent plans, reads the case with read-only tools, and drafts a reply where every claim cites proof.
-
The buyer's message hid an instruction to the AI. The agent flags it and refuses; code checks every claim.
-
After the seller approves, Cleared sends the evidence through PayPal's Disputes API. PayPal closed it in her favor.
-
Ask Cleared answers from her sales and cases, files proof from outside Cleared, and keeps every conversation.
-
How it's built: what the AI can't do. Read-only tools, code checks, a person's approval, verified PayPal webhooks.
Inspiration
A freelance illustrator sends a PayPal invoice for an album cover. The client pays, then opens a dispute: "I never received the files." PayPal Seller Protection covers shipped goods, not digital work or services, so her only defense is proof, and she has about 10 days to send it. Most freelancers don't have that proof organized, and a lost dispute costs the payment.
Dispute tools act after a buyer files, and typically take 20–35% of what they win. We wanted the proof to exist before anyone disputes anything.
What it does
Cleared follows a freelancer's sale from start to finish:
- Before the invoice. Cleared AI checks the sale for what causes disputes: a price far above her usual, no delivery date, vague deliverables, no refund terms. Each fix writes the missing terms into a real PayPal invoice, so they're on record.
- At delivery. She sends the client a private delivery link. The client sees the files and confirms with one click; Cleared records the time and device. The sale shows a proof checklist: terms on the invoice, files delivered, client confirmed.
- When a dispute arrives. Cleared's agent takes the case on its own: it writes a plan, then opens the dispute, the sale, the invoice and every file with read-only tools, and checks PayPal's rules. It drafts a reply where every claim cites an exhibit. Code checks each claim against its exhibit, and the agent refuses instructions hidden in the buyer's message. Nothing goes to PayPal until she approves; then Cleared submits the evidence through PayPal's Disputes API.
- PayPal decides. In the sandbox, Cleared escalates the case to a PayPal claim, re-sends her approved evidence when the claim asks, and once PayPal has reviewed it, asks PayPal to decide.
- Ask Cleared, any time. A chat that answers from her sales and cases, keeps every conversation, and files proof from outside Cleared (a client's approval screenshot, an email) on the right sale.
Every model call is in an AI audit log with its model, tokens and cost, and every PayPal webhook is signature-checked.
How we built it
- PayPal (sandbox):
- Invoicing v2: create, send and track payment.
- Disputes v1: list, get,
provide-evidence(multipart PDF and files),escalate, and the sandboxadjudicate. - Orders v2 and Payments v2 (Add Tracking for shipped goods), through the PayPal TypeScript SDK from APIMatic's PayPal Context Plugin.
- Webhooks, verified with PayPal's certificate check on the raw bytes; a cron job also polls Disputes every 30 minutes.
- AI: the OpenAI Responses API with
gpt-5.4-mini(disputes of $500 or more go togpt-5.4).- A forced plan step, strict structured outputs and read-only tools: the agent has no tool that can send, refund or change anything.
- A deterministic claim checker (citations, dates, amounts, file names) and a prompt-injection guard that keeps a flag only if the quote really appears in the case.
- Infrastructure: Render (web service, a Workflow that runs the agent with retries, two cron jobs), Neon Postgres with Drizzle, Cloudflare R2.
- App: Next.js 16, React 19, Tailwind CSS 4, shadcn/ui, Motion.
- APIMatic: we installed the plugin in Claude Code on 22 Oct, partway through the build, rebuilt the tracking code with its skills and wrote its contract sheet (
paypal-plan.md). That review caught a real bug: our code re-sent "add tracking" after a timeout. Now it re-reads the order, so a buyer never gets the same tracking number twice.
Challenges we ran into
- Getting PayPal to decide a sandbox dispute. Evidence on an inquiry hands it back to the buyer, and PayPal only offers
adjudicateon a claim under review. The working sequence: escalate the inquiry, send the evidence again when the claim asks, wait about 30 minutes for PayPal's review, then adjudicate.adjudicatealso rejected our requests while we sentPrefer: return=representation. - Disputes need a real buyer. Only a sandbox buyer can open one, on PayPal's site, so judge mode keeps a stock of real sandbox disputes opened by hand. If it runs out, a clearly labelled test dispute (with the same hidden instruction) is used and nothing is sent to PayPal.
- A write that timed out may have succeeded. Every PayPal write is claimed in the database first, and an unanswered write is settled by re-reading PayPal, never by guessing "failed".
- Webhook signatures only verify on the exact raw bytes PayPal sent.
Accomplishments that we're proud of
- A real dispute, end to end, on the live site: a sandbox buyer's dispute → the agent's cited reply → the seller's approval →
provide-evidence→ escalated to a claim → PayPal's decision: closed in the seller's favor. - The agent's eval suite: 13 scenarios, each run 3 times against the real model, covering strong and weak cases, goods and services, three prompt injections and failing tools. With
gpt-5.4-mini: the right recommendation 39/39 times, prompt injections resisted 9/9, about 7.5 s and $0.006 per case. - Code checks every claim, so the seller never sends a date, amount or file name that isn't in her evidence.
What we learned
The AI is the easy part. Trust comes from what surrounds it: read-only tools, code that checks the model's claims, a person's approval before anything is sent, and an audit log of every call and its cost.
What's next for Cleared
- Multi-merchant onboarding through PayPal Partner Referrals, so any seller can connect their own account.
- Live (non-sandbox) mode, with the same approval step.
- Sending the delivery link from Cleared by email, so the client's confirmation needs no copy and paste.
Built With
- apimatic
- cloudflare-r2
- drizzle
- neon
- nextjs
- openai
- paypal
- paypal-disputes
- postgresql
- react
- render
- shadcn-ui
- tailwindcss
- typescript
- vitest