Inspiration

I spent a while reading seller threads about disputes. Most of them said some version of the same thing: they had proof and lost anyway.

One post on r/smallbusiness was titled "Lost a $2,400 chargeback after providing signed delivery receipts" (332 upvotes). On r/paypal, a seller described PayPal refunding the buyer $1,700, letting him keep the goods and still charging the seller a dispute fee (157 upvotes). Another seller "spent 4 hours writing a response... Lost anyway", because the evidence didn't match the reason code.

Some of these orders were never covered by Seller Protection to begin with. In others the proof was real but didn't fit the reason the buyer picked. Writing a good response takes hours, and the tools that do it for you keep a cut of whatever they recover (Chargeflow takes about 25%).

Then there's agent shopping. People are starting to buy things through AI agents. If a shopper later says "my AI bought it, not me", the seller has nothing that shows a person agreed to that purchase. Chargeback firms were already flagging this risk in 2026. PayPal already lets agents pay, so I built something for the seller on the other end of those purchases.

What it does

Seller Shield covers an order from checkout until any dispute on it is closed. Plenty of tools help a seller write a dispute reply. What I wanted was proof that exists before the dispute does, including proof that a human approved an AI agent's purchase.

  • Prevent. Every order is run against PayPal's US Seller Protection rules, which I built from the policy text last updated January 26, 2026. It checks that the ship-to address matches the PayPal transaction, that there's verifiable tracking and PayPal has it, and that the order shows "delivered" (needed for Item Not Received cover). It also applies the $10,000 cap and the rules for intangible goods. When something is missing, the seller gets one plain sentence on why it matters and a button that fixes it. "Push tracking to PayPal", for example, sends the tracking number through the Orders v2 tracking API.
  • Prove. Each order builds its own evidence folder: the PayPal order and capture, the shipment, messages, the protection check, and the purchase mandate if an agent made the purchase.
  • Defend. A dispute comes in by webhook, or by polling if a webhook gets missed. Seller Shield explains the claim in plain words and recommends fight, offer or accept, along with the dollars the seller can expect to keep. PayPal's Agent Toolkit pulls the PayPal-side facts and Gemini drafts the case, with a citation on every entry. The seller reviews a PDF evidence pack, and nothing goes to PayPal's Disputes API until they click confirm.

Agent purchases. The shopper signs a purchase mandate in the browser that says what the agent may buy, the maximum amount and when the mandate expires. The Gemini shopping agent signs its own request too. At checkout the shop verifies both signatures, refuses anything outside the mandate, lets each mandate be used only once, and writes the mandate hash into the PayPal order's custom_id. The human still approves the payment in PayPal, and the payer email has to match the mandate. At capture, the app reads custom_id back from PayPal and records whether it matches. If the purchase is disputed later, the signed mandate goes into the evidence folder as proof that a person authorized it.

Anything simulated in the demo, like carrier deliveries and demo disputes, is labeled "Simulated".

How we built it

I built this alone. I started the repo on November 3, and the hackathon closes on November 12.

The app runs on Next.js 15 (App Router) with TypeScript and Tailwind. AG Grid handles the orders grid and the disputes inbox. Data is stored in Postgres through Drizzle, on Neon in production and PGlite locally, and the app is hosted on Render. Evidence PDFs are made with pdf-lib.

AG Grid and Render. The seller's orders screen and the disputes inbox are both AG Grid (Community, v36). I wrote custom cell renderers for the protection badge, the agent badge, the evidence coverage bar and the dispute status, added the quick search and an "At risk only" toggle, and styled it with the Theming API so it matches the rest of the app. Clicking a row opens that order's evidence timeline. Render hosts the app from the repo's render.yaml, and migrations run on every boot because the free plan has no pre-deploy step.

PayPal. Orders v2 handles create, capture and get. custom_id carries the mandate hash, and the tracking endpoint pushes shipments to PayPal. From Disputes v1 I use list, get, provide-evidence, provide-supporting-info, make-offer, accept-claim and send-message, plus the sandbox-only require-evidence and adjudicate calls. Webhooks are verified with verify-webhook-signature and stored idempotently, with a throttled poll as a backup. Human checkout uses the JavaScript SDK buttons. From the Agent Toolkit (@paypal/agent-toolkit) I use three read-only tools: get_dispute, get_order and get_shipment_tracking.

AI. Everything AI in the app runs on Google Gemini through the Vercel AI SDK, used in two ways. Structured output (generateObject with zod schemas) writes the dispute case and the plain-language explanations of protection gaps. Tool calling (generateText with tools) runs the shopper agent and the Agent Toolkit investigator, which gathers PayPal's facts for a case. There are two model tiers. By default a "pro" model writes the case and a "flash" model does the rest. The hosted demo runs on Gemini's free tier, so there both tiers are pinned to flash, with flash-lite models as the fallback.

The part I'd defend hardest is the no-fabrication validator. Every timeline and argument entry must cite records from the evidence folder. If an entry has a date, amount or tracking number that isn't in the records it cites, the whole draft is rejected and the seller gets a template built only from the folder. The case summary and the notes sent to PayPal are built in code from the validated entries. They never come from the model's free text.

There's also a daily AI cap, counted in the database, and every AI feature has a fallback that doesn't need AI at all. The demo still works when the AI is off, capped or rate-limited.

Mandates are Ed25519 JWS, signed in the browser with WebCrypto over canonical JSON and hashed with SHA-256.

The repo has 416 automated tests in 43 files (Vitest, offline, against an in-memory Postgres). They cover the parts that would cost a seller money if they broke: the protection rules, mandate checks, the validator, webhook idempotency and the guards against submitting twice. I also ran the hosted app end to end on the PayPal sandbox and logged every step in scripts/e2e-sandbox.md. That run found real bugs. I fixed each one and re-ran the step on the redeployed app.

Challenges we ran into

Getting "the AI may not invent evidence" to hold up in code took longer than I expected. Dates, amounts and tracking numbers come in lots of formats, and the checker also can't be fooled by a ZIP code or a hash that happens to look like one of them.

My early notes on Seller Protection had an outdated signature rule. I went back to the current policy text and rebuilt the rules from it.

The Agent Toolkit (1.11) targets AI SDK v4, and I was on v7. I re-wrapped its three read-only tools as v7 tool() objects that still call the toolkit's own execute.

My first real sandbox dispute went into PayPal review in about three minutes. After that PayPal only allows provide_supporting_info, not provide_evidence. My submit button always called provide-evidence, so it would have failed for every judge who filed a real dispute, and I only caught it during the live run. Now the case page reads the dispute fresh from PayPal before submitting and uses whichever action PayPal allows. If neither is allowed, it refuses and sends nothing. The confirm dialog tells the seller which call is going out.

Gemini gave me two separate problems. First, the thinking models sometimes spent their whole output budget on reasoning and returned cut-off JSON. I lowered the thinking level and added model fallback, and left the validator as strict as it was. Second, during the live run every AI feature fell back to templates after about 20 calls, while the app still showed around 280 calls left. Gemini's free tier allows about 20 requests a day per model, and I had pinned both tiers to the same model. Now a model that gets refused for quota is skipped until its retry time, and the call moves on to the next model.

Accomplishments that we're proud of

The full defend loop works on the real PayPal sandbox. On November 10 a sandbox buyer filed an Item Not Received dispute in the Resolution Center (case PP-R-EPP-10197892). I pulled it into Seller Shield by its ID, and three dispute webhooks reached the hosted app over the life of the case. The Agent Toolkit pulled the dispute, order, capture, tracking and buyer message from PayPal, and Gemini wrote a case with a citation on every entry. Building the case took 25 seconds. After I confirmed as the seller, PayPal took the evidence pack (HTTP 200), and it showed up on the dispute as supporting info with source SUBMITTED_BY_SELLER and evidence.pdf attached. The claim stayed under PayPal review after that, which is how it should be. PayPal makes the call, not Seller Shield.

An AI agent also made a real purchase on the sandbox. The mandate hash read back from the PayPal order's custom_id matched the signed mandate, and the payer email matched the shopper's.

I made sure the UI never passes off anything as real when it isn't. The sandbox has no carriers, so "delivered" is simulated and labeled "Simulated". Simulated disputes carry the same label, and their PDF has a "SIMULATED DISPUTE" banner on the cover.

What we learned

Most of the lost disputes I read about were lost before the dispute even opened. The ship-to address didn't match the PayPal transaction, or the tracking never reached PayPal, or there was no "delivered" status. By the time a buyer files, those gaps are already there and nothing in the case can undo them. After seeing that, I treated the Prevent screen as at least as important as the case writer.

PayPal already lets agents pay, and that part works. The gap I kept running into came afterwards: showing that a person actually agreed to the purchase when the buyer says they didn't. The mandate is just a short signed JSON document plus one hash in an order field. A seller can attach it to a dispute, and today they have nothing to attach.

I don't trust a model to write dispute evidence unchecked. One wrong date in a response and the seller looks careless. Making every line cite a real record, and checking dates, amounts and tracking numbers in code, did more for the output than picking a better Gemini model. If the check fails, the seller gets the plain template. I'd rather lose some polish than send PayPal a wrong date.

The sandbox moved much faster than I planned for. I assumed a new dispute would sit and wait for the seller to respond. In my test it was in PayPal review within about three minutes and only took supporting info from then on. So now the app asks PayPal for the dispute's current state and allowed actions right before it submits, instead of assuming a fixed order of steps.

What's next

I want to let more than one merchant sign up, through PayPal's partner onboarding, and connect real carrier tracking so deliveries come from real events instead of being simulated. I'd also like to line the mandate format up with the agent payment standards that are starting to appear (AP2, verifiable intent) and with PayPal Agent Ready. Further out, I want dispute analytics that show which evidence wins for which reason code.

Built With

  • ag-grid
  • drizzle
  • google-gemini
  • jose
  • neon
  • nextjs
  • paypal-agent-toolkit
  • paypal-disputes-api
  • paypal-js-sdk
  • paypal-orders-api
  • paypal-webhooks
  • pdf-lib
  • postgresql
  • react
  • render
  • tailwindcss
  • typescript
  • vercel-ai-sdk
Share this project:

Updates

Submission history