Inspiration## Inspiration

When a PayPal buyer opens a dispute, the seller gets a deadline and the money is often put on hold. To answer well, the seller has to find the order, the tracking, the buyer's messages and their own store policy, then work out which of the buyer's claims the evidence actually answers. For a small seller with no support team, that is an evening of work per case, and many either miss the deadline or refund just to make it go away.

Big sellers have dispute teams. Small sellers have a PayPal inbox. I wanted to give them an investigator: something that does the reading and cross-checking, tells them honestly whether a case is worth fighting, and drafts the response, while leaving the final decision with the seller.

What it does

Casefile connects to a seller's PayPal account and turns each dispute into a case file:

  • Prioritizes open disputes by deadline and money at risk, with the reasons shown, not a hidden score.
  • Investigates each case with Claude across six sources: the PayPal dispute, the order, shipping and tracking, buyer conversations, store policies, and documents the seller uploads.
  • Checks every buyer claim against the evidence and marks it supported, contradicted or unable to verify, quoting the source.
  • Recommends fight, refund or a partial offer, rates each piece of evidence, and lists what is missing.
  • Drafts the response and evidence packet, which the seller previews and approves before anything is sent to PayPal.

It is not built to always say "fight". In one of my live sandbox tests, the buyer opened the dispute 14 minutes after paying and the order had not shipped. Casefile recommended a refund, and quoted PayPal's exact disputed amount rather than the order total.

How we built it

Front end. Plain HTML, CSS and JavaScript with no framework, so it loads fast on a phone. The dashboard answers one question first: what needs a response, and how much money is at stake.

Back end. Serverless functions on Vercel (Node.js). API keys live only in environment variables, and an access code protects every route.

PayPal. The app calls the REST APIs directly:

  • OAuth 2.0
  • Disputes v1: list, show, provide evidence (multipart), accept claim, make offer, send message, escalate, and sandbox settlement for testing
  • Payments v2 captures and Orders v2 for order and tracking details
  • The PayPal JS SDK on a demo store, so judges can buy something in sandbox and open a real dispute against it

AI. Claude runs as a tool-using agent with eight strict tools: six gather evidence, one records findings and one submits the final case brief. Every tool is locked to the open case. To fit inside serverless time limits, each request runs one agent turn, and the conversation travels back to the browser with an HMAC signature, so the server stays stateless and the history can't be tampered with.

Code decides, not the model. The AI writes findings, but code computes each stage's status (completed, needs input, unable to check), so the model can't claim it verified something it never read.

Priority rules. For an open case with \( h \) hours left before the response deadline and \( s = a / a_{\max} \), its amount relative to the largest open case:

$$ \text{priority} = \begin{cases} \text{Critical} & h < 24 \ \text{High} & h < 72 \ \text{ or } \ (h < 168 \ \text{and} \ s \ge 0.5) \ \text{Medium} & \text{otherwise} \end{cases} $$

Cases already with PayPal or the buyer are Low. Within a level, cases sort by the tuple \( (\text{level},\ h,\ -a) \): soonest deadline first, larger amount breaks ties. Win rate only counts real outcomes:

$$ W = \frac{n_{\text{won}}}{n_{\text{resolved}}} $$

Challenges we ran into

  • PayPal's evidence rules. My first live submission failed with EVIDENCE_TYPE_IS_NOT_ALLOWED. PayPal accepts different evidence types for each dispute reason. For an item-not-received case, only proof of fulfillment or proof of refund. Casefile now reads the dispute's reason and packages the seller's approved evidence in a form PayPal accepts, and the preview the seller approves shows exactly that packet.
  • Statuses that change after you act. After accepting a claim, PayPal reports the case as under review while it processes the refund. My first version froze that in-between status. Real cases now always follow PayPal's live status.
  • Sandbox geography. My default sandbox accounts couldn't receive payments, so I had to set up separate US business and personal sandbox accounts before any test dispute could exist.
  • Sandbox decisions. PayPal only lets you simulate a ruling when a case is a claim under review and PayPal has opened it for a decision. Casefile now only offers that button when PayPal does.
  • Serverless time limits. A full investigation takes longer than one function call allows. Splitting it into signed, one-turn steps fixed this and made pause and resume possible.
  • Keeping the AI honest. The hard part wasn't getting good answers but stopping confident wrong ones. The agent must say "I couldn't check live carrier tracking" instead of guessing.

Accomplishments that we're proud of

  • Real disputes, end to end. In the PayPal sandbox I bought from the demo store, opened disputes, investigated them live with Claude, submitted evidence through the Disputes API, escalated a case to a claim, accepted a claim that Casefile advised refunding, and reached a simulated ruling in the seller's favor.
  • An AI that will tell you not to fight. Every finding is labeled supported, contradicted or unable to verify, and it recommends a refund when the buyer is probably right.
  • The seller stays in control. Nothing reaches PayPal until the seller has seen the exact evidence packet and approved it.
  • Built for a phone, where a lot of small sellers run their business.

What we learned

  • How PayPal disputes actually move: inquiry, claim, chargeback, the deadlines at each step, and which evidence PayPal accepts for each dispute reason.
  • That testing against your own assumptions isn't testing. Most of my real bugs only appeared against the live sandbox, so I now check PayPal's documentation before building each action.
  • That an AI feature is mostly about boundaries: strict tool schemas, tools scoped to one case and code that owns the status make the agent far more trustworthy than prompt wording alone.
  • That honest numbers matter in a money tool. The dashboard shows the actual money difference rather than inflated percentages.

What's next for Casefile

  • Seller accounts with Connect with PayPal, so any seller can sign in without API keys, and investigations follow them across devices.
  • An evidence vault that keeps receipts, policies and tracking and reuses them across cases.
  • Live carrier tracking, so delivery can be confirmed with the carrier directly.
  • Deadline alerts by email before a response is due.

Built With

  • ai-agents
  • anthropic
  • anthropic-sdk
  • claude
  • css3
  • html5
  • indexeddb
  • javascript
  • localstorage
  • node.js
  • oauth
  • paypal
  • paypal-disputes-api
  • paypal-javascript-sdk
  • paypal-orders-api
  • paypal-rest-api
  • rest-api
  • serverless
  • svg
  • tool-use
  • vercel
Share this project:

Updates

Submission history