MandatePay

Let an AI shop for you, and keep proof of what you asked.

AI agents are starting to buy things for people. When one buys the wrong thing, nobody can prove what the buyer actually allowed, so honest buyers and honest stores both lose disputes. MandatePay makes the buyer's intent a signed record that travels with the payment: the buyer signs their limits, every cart is checked against them before PayPal is called, and if the payment is disputed an AI analyst reads the signed record and recommends a fair response. A person approves everything that goes to PayPal.

Built for the "Build What's Next with PayPal and AI" hackathon. PayPal sandbox only; no real money moves.

Live app	https://mandate-pay.vercel.app
Demo video (3 min)	https://youtu.be/q6SA3VV74ao
For judges	docs/JUDGES.md: a five-minute test path, how it meets the requirements, honest limits
How it works	docs/ARCHITECTURE.md: the flow, every PayPal API we use, every AI feature, the trust model
Agent access (MCP)	docs/MCP.md: any AI agent can shop for a buyer inside their signed mandate
API reference	contracts/api.md: every route, with its schema in contracts/schemas.ts
Submission text	docs/DEVPOST.md

Contents

1. How it works
2. Features
3. PayPal and AI: what is used where
4. Trust model and safety
5. Tech stack
6. Quick start
7. Demo data
8. Configuration
9. Scripts
10. Testing and analyst accuracy
11. Deploying
12. Project layout
13. Team · Credits · License

How it works

 Buyer says what they want          "white running trainers, size 10, under 110 USD, within two weeks"
        │
        ▼
 AI drafts structured limits        budget, product type, size and colour, delivery deadline
        │
        ▼
 Buyer SIGNS the mandate            Ed25519 JWS, with the buyer's own key (encrypted at rest)
        │
        ▼
 Agent shops the real catalog       the in-app agent, or any outside agent over MCP
        │
        ▼
 Cart guard checks the cart         hard limits are plain code; AI only settles the unsure matches
        │  (blocked carts never reach PayPal)
        ▼
 PayPal checkout                    PayPal account or card (3-D Secure); a receipt hash ties
        │                           mandate, cart and payment together
        ▼
 Something goes wrong?              buyer reports a problem → store replies or refunds
        │                           still unhappy → a real PayPal dispute arrives (webhook or poll)
        ▼
 AI analyst + code guardrails       reads the signed mandate, cart and payment; recommends a
        │                           response and cites the records it used
        ▼
 A person approves                  message with the evidence PDF, an offer, a refund, or accepting the claim

Features

For the buyer

• Mandates: the request becomes limits (budget, items, size and colour, deadline), signed with the buyer's own key. Mandates can be revoked.
• Voice or text input: a full-screen Listening view for speech, and rotating "thinking" text while the AI works.
• Shopping: an AI agent shops the real catalog within the mandate, or the buyer browses (25 products from five seller brands in the demo store). Prices and details always come from the catalog, never from the model.
• Payment: PayPal Smart Buttons and Card Fields with 3-D Secure. The payer is checked against the buyer's linked PayPal account.
• After the purchase: order history with "Sold by" brands, and a Report a problem button that goes to the store before any PayPal dispute.
• Agent access: the buyer can create keys so an outside AI agent (over MCP) shops inside their signed mandates. Keys can be revoked.

For the store (staff, admin, owner)

• Disputes: PayPal disputes arrive by verified webhook and polling. Each has an AI recommendation, the evidence it relied on, a Mandate vs cart comparison, guardrail notes, and a downloadable PDF evidence pack.
• Buyer reports: a summary of what the records say, with one-click reply or refund.
• Orders and refunds: full or partial refunds. Refunds are re-read from PayPal first, so none is paid twice, including refunds made in the PayPal dashboard.
• Products: catalog with pictures, stock, delivery days, attributes and an optional seller brand.
• Running the store: roles (buyer, staff, owner, admin), team, settings and rules, audit log (append-only), CSV exports, and a Results page with the analyst's measured accuracy.

For other AI agents

• An MCP server (/api/mcp, JSON-RPC 2.0 over HTTP) with tools to list products, check a cart against the guard, and create a PayPal order. It can never sign a mandate, set a price, or pay: the buyer approves in PayPal.

PayPal and AI: what is used where

PayPal (sandbox)

This is the beginning of the README. Read the rest at the original. Read the full README ↗