Inspiration

A freelancer who gets a PayPal dispute has one deadline, a rulebook they have never read, and whatever screenshots they kept. PayPal accepts different evidence for different reasons: for item not received it wants proof of fulfilment, for not as described it wants what was promised, and a refund ID only counts if PayPal itself issued it. Large merchants hand this to chargeback agencies that keep 20 to 25% of what they win back; a seller with six disputes a year is not worth their time, and answers by hand.

I wanted a tool that does the agency's discipline for that seller, without letting a model decide whether anyone should win.

The model reads. Code decides. A person approves.

What it does

  1. Keeps the proof when you are paid. Every PayPal payment gets an evidence locker: invoice, delivery log, the buyer's messages. Muse Spark reads them before any dispute exists.
  2. Notices the dispute by itself. ClaimPack polls PayPal's Disputes API (signed webhooks are also supported) and opens the case with PayPal's deadline, the buyer's words and the money PayPal is holding.
  3. Reads every document with its source words. Muse Spark 1.3 turns PDFs, photos and screenshots into typed facts, each carrying the exact quote it came from. A document that contains instructions aimed at an AI is set aside and the seller is shown why.
  4. Decides with PayPal's rules, in code. A tested rules engine applies PayPal's reasons-and-evidence table, the dispute's stage and the actions PayPal currently allows, and checks every fact against PayPal's own records: order number, buyer, amount, refunds PayPal really issued, deadline. Verdict: Ready to file, Something PayPal needs is missing (and what), The evidence contradicts itself, or Nothing here PayPal would accept.
  5. Says whether Seller Protection is likely to apply. Meeting the evidence rules and being covered are different tests; ClaimPack labels both, with reasons.
  6. Drafts the statement, then checks it word by word. Every sentence must cite a fact; numbers, dates, names, quotations and claim words such as confirmed or refunded must appear in what it cites; no accusations. At approval each sentence sits beside the exact words it cites.
  7. A named person approves, then it files. The server re-fetches the dispute, re-checks the pack and the statement, and only then calls provide-evidence with an evidence-summary PDF. It reads the dispute back from PayPal and logs who approved, what was sent, and each file's SHA-256.
  8. Or settles. When nothing would carry the claim, it offers PayPal's own options: make an offer or accept the claim, with the same approval.

How PayPal is used

  • Orders v2: the built-in test checkout creates and captures sandbox orders carrying the seller's invoice_id, so evidence links to the payment; tracking found in documents can be sent to the order (/track).
  • Disputes v1: list (with a start_time window, because PayPal's default list omits new disputes still under review), show, provide-evidence (multipart, file names in PayPal's accepted pattern, text sent as PDF), make-offer, accept-claim.
  • Payments / Orders read-back: refunds are counted only if PayPal links them to that exact capture.
  • Webhooks: trusted only after verify-webhook-signature.

Built with

TypeScript on Node 24, Hono, node:sqlite, pdf-lib and sharp on the server; React 19, Vite and AG Grid Community (disputes, payments and the fact grid) in the browser; Meta Muse Spark 1.3 through its OpenAI-compatible Responses API with strict JSON schemas.

Proof it works

On 7 November 2026 a fresh sandbox sale (invoice INV-2084), synthetic SPECIMEN documents and a buyer-opened dispute were filed end to end; the demo video is that run, uncut except for waiting. PayPal's own record, read back afterwards, holds the seller's PROOF_OF_FULFILLMENT, and the three files PayPal holds are byte-identical (SHA-256) to what ClaimPack logged sending. The redacted proof bundles are in docs/proof/.

What I measured, and what it does not mean

Thirty synthetic disputes across seven of PayPal's reasons, 39 documents (PDFs, delivery logs, tracking pages and chats as images), with planted traps: tracking for another order, a parcel delivered to someone else, a forged refund ID, hidden instructions to the AI, a missed deadline, dates without a year.

  • First run: 28 / 30 verdicts right. After fixes: 30 / 30, 0 dangerous errors (never a pack that is not ready, never a document that must not be sent), hidden instructions caught 2 / 2, drafted statements passing the guard 16 / 16.
  • The cases were written by me, and one expected answer was changed after a review, so the later score is not held out. These numbers measure PayPal's evidence rules, not dispute wins.

Before submitting, I gave the project to five independent reviewers (judges, an adversary trying to make it file something false, a PayPal disputes specialist, small sellers, a presentation critic). Their attacks became tests: 120 tests pass.

Challenges

  • PayPal's sandbox needed a buyer-side Resolution Center flow to open disputes, and a new dispute can sit under review for half an hour, invisible to the default list.
  • A drafted statement repeated the buyer's "Got the files, thanks!" without quotation marks; the guard split the sentence at the "!" and correctly blocked filing. The drafter now quotes people's words exactly.
  • Keeping the guard honest: it checks words, not meaning, so the approval screen shows every sentence beside its sources rather than claiming more than it can check.

Try it

  • No keys, two minutes: git clone https://github.com/bsjuilla/claimpack && cd claimpack && npm install && npm run demo, then open http://127.0.0.1:8790. All 30 evaluation disputes with their saved readings; filing goes to a simulated PayPal that checks requests like the real API. Nothing leaves your computer.
  • Against the PayPal sandbox: add a sandbox app's client ID and secret plus a Meta key to .env, run npm run app, make a test sale, open a dispute as the sandbox buyer, and file. Full steps in the README.

Built solo, started 5 November 2026. Sandbox and synthetic data only; not legal or financial advice.

Built With

Share this project:

Updates

Submission history