-
-
when an AI agent buys the wrong thing, the merchant pays. We fix that on PayPal.
-
How it works: the shopper signs, the merchant checks before PayPal, PayPal carries the proof, disputes use the record, anyone can verify it.
-
Anyone can verify the proof package offline with pnpm proof:verify (real run on this dispute: 13 of 13 checks passed).
-
The agent proposes a red $95 jacket. It breaks both signed limits, so it is refused before any PayPal order exists. Nothing is charged.
-
The shopper signs what they want in the browser, with a key that never leaves it. The card shows exactly what the agent may do.
-
When an agent really did overreach, the record says so, and the copilot recommends refunding the shopper (seeded, read-only case).
-
With the shopper's signed permission and a wallet saved through Vault v3, the agent pays alone, only for a cart that fits.
-
Every agent order and checkout verdict in AG Grid: captured, blocked and sent back to the shopper.
-
The grey $74 jacket fits. The shopper approves it in PayPal (sandbox), and only then is it captured.
-
The same rules are replayed at capture time, so checkout and the dispute copilot can't disagree.
-
The shopper disputes the order. The copilot matches it to the signed intent, the cart and the PayPal capture.
-
For the selected dispute: what was signed against what was bought, the next permitted action, the deadline and the lifecycle.
-
An evidence package drafted from the signed record. A person reviews it and decides what is sent to PayPal.
-
Ask the AI reads the disputes and answers from their records. It cannot accept claims, submit evidence or change anything.
-
Dispute Studio on AG Studio: KPIs, dispute classes and the agent platforms that overreach (seeded demo data).
Inspiration
AI agents now shop for people inside ChatGPT, Copilot and Perplexity. When an agent misreads "a grey running jacket under \$80" and buys a red one for \$95, the shopper disputes the charge. The merchant, as merchant of record, takes the loss. Chargeback tools were built for a human clicking a button, so merchants have no record of what the agent was actually allowed to do. PayPal's Agent Ready protection covers unauthorized and item-not-received claims, which leaves wrong-item and misread-intent disputes open. We wanted to close that gap on PayPal's own rails.
What it does
Proof of Intent answers one question at two moments: did the agent do what the shopper actually asked?
- Before any money moves: the shopper signs what they want ("grey running jacket, at most \$80") with a key that never leaves their browser. When the agent proposes a cart, the merchant checks it against that signed intent before a PayPal order exists. A red \$95 jacket is refused with
AMOUNT_EXCEEDS_MAXandATTRIBUTE_MISMATCH, so no order is created and nothing is charged. The grey \$74 jacket passes, the shopper approves it in PayPal, and only then is it captured. A pointer to the signed intent rides on the PayPal order. - Paying alone: with the shopper's signed permission and a saved PayPal wallet, the agent can pay without the shopper present, but only for carts that pass the same checks. If the merchant isn't sure a cart fits the shopper's words, it holds the cart for the shopper to confirm and charges nothing.
- When a dispute arrives: the dispute copilot matches it to the signed record and replays the same rules at capture time. If the order complied, it drafts an evidence PDF. If the agent overreached, it recommends accepting the claim and refunding the shopper. A person approves every dispute action, and each click is written to the audit log before PayPal is called.
- Anyone can check the record: every disputed order exports a proof package (the three signed mandates, their public keys, the PayPal references and the policy version).
pnpm proof:verifychecks it offline, without trusting our server, and says what a valid package does not prove. - Dispute Studio: built on AG Grid and AG Studio. It has KPI tiles, a dispute-class donut that filters everything, agent-platform cards, a dispute grid, a mandate diff and an evidence preview. Its "Ask the AI" chat explains disputes but cannot act.
- The shopper stays in control: a card shows exactly what was authorized. A receipt shows what has been spent and what's left, and the shopper can revoke an intent at any time.
Who sends the mandates? Our demo shop signs the shopper's intent in the browser, and our buyer agent signs the payment mandate and proposes the cart. External agents can integrate through the documented checkout endpoint, using our AP2-style schemas and a registered agent key. Disputes on orders without a mandate take the standard PayPal evidence path, so installing Proof of Intent never mak
How we built it
- PayPal:
- Orders v2: authorize, then capture or void after the shopper approves the exact cart.
- Vault v3: a shopper-approved saved wallet for agent-alone payments
- Webhooks: verified, stored once, and used as the worker's inbox.
- Disputes API: provide evidence, send message, escalate.
- Agent Toolkit:
get_disputeandlist_disputesfeed the copilot.accept_dispute_claimandcreate_shipment_trackingrun only on an audited operator click.
- Signed mandates: Intent, Cart and Payment mandates modeled on APmodeled on Mastercard Verifiable Intent. They're canonicalized with RFC8785 and signed as ES256 JWS. The shopper's key is a non-extractable P-256 WebCrypto key kept in IndexedDB.
- Deterministic policy engine: pure TypeScript with no I/O and no h stable reason codes, covering amount, currency, merchant, attributes,quantity, address, expiry, budget, order count and replay. Spending authority is reserved atomically in Postgres, so two carts at once can't both fit under a limit only one fits.
- AI with a short leash: the Vercel AI SDK with NVIDIA Nemotron 3.5 Lightning (Groq as a backup). The model checks semantic fit, explains disputes and drafts text, but it can only make a verdict stricter, never looser, and it never tot answer, the shopper is asked to confirm rather than the cart beingapproved. Replay mode serves recorded answers, so the demo needs no API key and gives the same result every take.
- Stack: TypeScript, Node.js, Fastify, Next.js, React, PostgreSQL,io, and React PDF for the evidence attestation. Deployed with DockerCompose on Dokploy behind Cloudflare, with GitHub Actions for CI, release checks and uptime monitoring.
How the checks work
The signed record. Every mandate $m$ is canonicalized with RFC 8785 (JCS) and hashed, and the PayPal order carries a pointer to the intent:
$$ h(m) = \mathrm{SHA\text{-}256}\big(\mathrm{JCS}(m)\big), \qquad \texttt{custom_id} = \texttt{poi:}\,\mathrm{id}(I)\,\texttt{:}\,h(I)_{[0,16)} $$
Hard rules. For an intent $I$, a cart $C$ with lines $\ell$, the t$ of what the intent has already spent or set aside, the engine returnsthe set of failed rules $R(I, C, t, L)$. The cart passes only if that set is empty:
$$ \mathrm{pass}(I, C, t, L) \iff R(I, C, t, L) = \varnothing $$
The limits it checks include:
$$ \begin{aligned} &\text{per purchase:} && \textstyle\sum_{\ell \in C} p_\ell\, q_\ell \le a_{\max} \ &\text{budget:} && \mathrm{spent}(L) + \mathrm{held}(L) + \mathrm{tota &\text{order count:} && \big|{\, s \in L : t - w < s \le t \,}\big| + 1 \le n_{\max} \ &\text{freshness:} && t_{\text{from}} \le t < t_{\text{expiry}} \end{aligned} $$
An intent that signs neither a budget nor an order count allows exactlalways in integer cents, never floats.
The model can only add caution. Order the outcomes $\mathrm{REJECT \prec \mathrm{APPROVE}$. The final verdict is the stricter of the rules and the semantic check:
$$ v = \min\big(v_{\text{rules}},\; v_{\text{model}}\big) $$
With fit $f$ and the model's confidence $c$:
$$ v_{\text{model}} = \begin{cases} \mathrm{APPROVE} & f = \text{match},\ c \ge 0.8 \ \mathrm{STEP_UP} & f = \text{partial}, \text{ or } 0.5 \le c < 0.8, \text{ or no answer} \ \mathrm{REJECT} & f = \text{mismatch}, \text{ or } c < 0.5 \end{cases} $$
So the model can never turn a failed rule into an approval, and a modeds to the shopper confirming, never to a charge.
What's left of an intent. The shopper's receipt reports, by the sa
$$ \text{budget left} = \max\big(0,\; B - \mathrm{spent} - \mathrm{held}\big), \qquad \text{next purchase} \le \min\big(a_{\max},\ \text{budget left}\big) $$
Challenges we ran into
- The sandbox dispute lifecycle: a new dispute opens at the inquiry stage, where PayPal won't accept evidence. We had to escalate to a claim first, which took 1 to
3 minutes, and read the allowed actions from PayPal's links instead ofispute webhooks also arrived 4 to 5 minutes after filing, so we added a
list_disputescatch-up for any webhook that never arrives. - Models that won't fetch facts: Nemotron with thinking on spent isoning and returned nothing. With thinking off, it often wouldn't call a lookup tool on its own and invented an answer. So every fact a shopper sees is retrieved by code first, and the model only phrases it.
- Money edge cases: a lost PayPal answer on an unattended charge,
PENDING, and two checkouts racing under one budget. Each needed itsown handling, so nothing is ever shown as paid, or charged twice, when we don't know for sure. - Deploys: a hosting tool rewrote our Compose networks and left thtgres twice, while the basic health check stayed green. We now checkdatabase readiness, the dispute worker and backups before a release counts as done.
Accomplishments that we're proud of
- Every journey works end to end on the PayPal sandbox, run twice: a human-present purchase, an agent refused and then paying alone, a dispute defended with evidence, and one fairly conceded.
- The agent paid alone from a saved wallet on the hosted sandbox shop, with no shopper present.
- A real sandbox dispute's proof package verified offline, 13 of 13 ch
- On our fixed evaluation sets (Nov 10), the semantic check scored 20/20 with no mismatch approved, dispute explanations 12/12, and every model answer was schema-valid (31/31).
- Over 900 automated tests, including the race conditions, against real Postgres.
What we learned
- Deterministic rules decide money; a language model is most useful when it can only add caution.
- A signature proves what was signed, not who holds the key. Being honoof package and the pitch) made the design better.
- Agentic commerce needs prevention before capture and a fair concession after, not just a better evidence bot.
What's next for Proof of Intent
- Working with PayPal so mandates can inform Seller Protection decisions. PayPal's production systems do not read our mandates today.
- A direct AP2 mapping, so AP2-speaking agents can send their mandates
- Shared, persistent AI budgets across services, and multi-merchant support.
- Passkeys for the shopper's signing key.
Built With
- ag-grid
- ag-studio
- cloudflare
- docker
- dokploy
- fastify
- github-actions
- groq
- indexeddb
- next.js
- nvidia-nemotron
- paypal-agent-toolkit
- paypal-disputes-api
- paypal-order-api
- paypal-vault
- paypal-webhooks
- playwright
- pnpm
- postgresql
- react
- react-pdf
- typescript
- vercel-ai-sdk
- vitset
- web-crypto-api