Inspiration

Priya asks her AI assistant for running shoes: size 8, under $120. A box arrives with size 9 inside. The store says the AI ordered the wrong size. The AI provider says the store shipped the wrong one. Priya opens a PayPal dispute, and nobody can show what the agent was actually told.

AI agents are starting to buy things for people, and the payments industry is building ways to authorize them. But when an agent's purchase goes wrong, today's dispute process was designed for a human who clicked "buy." It has no record of what the agent was told, what it considered, or why it chose. Liability for agent purchases is widely described as unresolved, and 93% of merchants say the AI or agent provider should bear the loss when an agent buys incorrectly. I wanted to build the missing piece: the dispute layer.

Who it's for

  • Merchants receiving agent-initiated orders: evidence to win fair disputes, and to refund unfair ones quickly.
  • Buyers delegating purchases: their confirmed limits are recorded, and a guard blocks overspending before payment.
  • Agent platforms: a clear record of when their agent broke the mandate, so responsibility lands where it belongs.
  • PayPal: a trust layer for agentic commerce built on its own Orders, Vault and Disputes APIs.

What it does

Prevent → record → resolve.

  1. The buyer confirms exact limits. Claude reads the request into concrete limits (category, size, maximum price), and the buyer confirms those exact limits. The backend refuses any purchase without a confirmed mandate, and each mandate buys once.
  2. A pre-payment guard. Before PayPal is called, the agent's choice is checked against the confirmed limits. An over-budget or wrong-size choice is blocked and logged, and nothing is charged.
  3. A receipt of intent before payment. The agent must log the confirmed limits and when they were confirmed, its recorded tool calls and the catalog results it saw, the shortlist and decision summary it reports, and a snapshot of the chosen listing. No receipt, no PayPal order. The hash shows none of this changed after purchase; the agent's own summary is treated as its account, not as fact.
  4. Tamper-evident and anchored in PayPal. Receipts and events are SHA-256 hash-chained in an append-only ledger. The receipt's hash is sent as the PayPal order's invoice_id, so PayPal holds an independent fingerprint from the moment of payment. When a dispute response is filed, the ledger and verdict hashes go into the note sent to PayPal too.
  5. AI adjudication of real PayPal disputes. When a buyer opens a PayPal dispute, the system finds the receipt from the dispute, checks it against PayPal's fingerprint, and assigns responsibility:
    • Agent error: the agent broke the mandate. Refund the buyer; the agent provider is identified as responsible for the breach.
    • Merchant error: the wrong item was delivered, or the listing manipulated the agent (prompt injection). The buyer is refunded.
    • Buyer remorse: the agent did exactly what was asked. The merchant submits evidence and should win.
  6. Evidence agent. It picks the next step from the actions PayPal currently allows (accept claim, escalate, provide evidence) and writes the response.
  7. Replay. A timeline replays every agent step with the deviation in red, next to a buyer view and a merchant verdict card that separates "Established by code" from "AI's ruling."

Proven end to end in the PayPal sandbox: an agent purchase, a buyer-opened PayPal dispute, the AI verdict, accept_claim filed through the Disputes API, and PayPal refunding the buyer $109.99.

Try it: on Give your agent a task, the real Claude shopping agent buys against limits you confirm. The Break the agent cards are controlled tests with scripted agent decisions and real sandbox orders: wrong size, over budget, a prompt-injected listing, buyer remorse, tampering with a receipt (the chain still verifies, but PayPal's fingerprint doesn't match), and the guard stopping an overspend before payment.

How I built it

I designed it around three decisions:

  1. PayPal as the independent witness. A hash chain alone can't stop someone who controls the database, so each receipt's hash is anchored in the PayPal order's invoice_id and every dispute is checked against it.
  2. Facts before AI. Code establishes the facts (mandate vs. purchase, integrity, whether an injected instruction caused the violation). Claude only rules among the outcomes those facts allow, and anything unverifiable goes to a human.
  3. The buyer confirms the exact limits that get recorded, and a guard enforces them before payment.
PayPal capability Used for
Orders v2 Agent purchases; receipt ID in custom_id, receipt hash in invoice_id; stable request IDs per receipt
Vault The buyer approves once; the agent then pays with no redirect
Payments (captures) The integrity check reads invoice_id and custom_id from the capture named in the dispute
Disputes v1 Read disputes; accept claim, escalate, provide evidence; settle in the sandbox
Webhooks CUSTOMER.DISPUTE.* events trigger adjudication, with signature verification
AI in the product How it's used
Claude API(claude-sonnet-5-5) Reads the request into limits to confirm; the shopping agent (tool-use loop over the catalog); the adjudicator (structured verdict limited by code-derived facts); the evidence agent (writes the PayPal dispute response). Prompt caching on system prompts and tools
Model Context Protocol The receipts ledger is an MCP server (log_intent, get_receipt, verify_chain), so any agent can record intent before buying
Retrieval BM25 search over 20 dispute, evidence, liability and return-policy rules; every verdict cites the rule it applied

Stack: Python 3.11, FastAPI, SQLite (append-only), Next.js + React, AG Grid for the merchant dispute queue, Render, GitHub Actions CI, Postman collection.

Development: built with AI-assisted development (Claude Code); the architecture, trust design and review decisions are my own, validated with 280+ automated tests, external technical reviews whose findings I triaged and fixed, and live sandbox runs.

Related work. The open-source Agent Receipts protocol (Obsigna) records signed, hash-chained logs of agent actions for audit. Mastercard Verifiable Intent and Google's AP2 mandates capture a person's authorization at payment time. Proof of Intent focuses on what those leave open: what happens when an agent's purchase is disputed.

Challenges I ran into

  • PayPal doesn't let a merchant app open disputes, so live disputes are opened by the sandbox buyer in PayPal's interface; the demo cards place real orders and simulate only the dispute.
  • Tamper-evidence that holds up: a full chain rewrite passes hash-chain verification, which led to anchoring the hash in PayPal.
  • Sandbox settlement timing: the backend acts on the actions PayPal currently offers on a dispute rather than on its status alone.
  • A real bug caught by testing live: PayPal can put the buyer's complaint in the item notes instead of the message thread. A throwaway dispute exposed it before the demo, and corrected verdicts now supersede old ones without erasing them.
  • Keeping AI verdicts trustworthy: prompt-injection blame had to be linked to the actual violation, and unverifiable cases had to fail closed to a human. The facts that limit a verdict come from the mandate, the agent's recorded choice, the listing snapshot and PayPal, never from the agent's own explanation.
  • Recovering from partial failures: stable PayPal request IDs make retries safe, webhook events are de-duplicated, and the dispute planner reads PayPal's own record of steps already taken, so a step is never filed twice even if a ledger write was lost.

Accomplishments that I'm proud of

  • A full real loop in the PayPal sandbox, ending in a PayPal refund.
  • A tamper demo where a fully rewritten ledger is still caught.
  • Prevention and resolution in one product: the guard blocks what it can see, and disputes cover what it can't.
  • 280+ automated tests and green CI.

What I learned

  • Authorization at payment time is only half of trust in agentic commerce; disputes need evidence of intent too.
  • A payment record held by a third party is a strong, simple anchor for tamper-evidence.
  • Keeping the model inside code-defined boundaries makes AI verdicts much easier to trust and test.

What's next for Proof of Intent

  • Accept signed authorizations such as AP2 mandates or Mastercard Verifiable Intent as evidence.
  • User accounts and ownership checks (today each authorization is protected by a per-mandate token, a capability rather than an identity).
  • Persistent multi-instance storage and live (non-sandbox) PayPal with a merchant partner.
  • A merchant view of agent-caused dispute trends.

Current scope: PayPal sandbox only; one sandbox merchant and a 20-product catalog; dispute rules written for this demo, not PayPal policy.

Built With

Share this project:

Updates

Submission history