ShopVoice Pay

A voice-first purchasing agent for independent grocers. It reorders from suppliers and pays them through PayPal, but only within spending rules the owner sets, and it pays only for what actually arrived.

Status: M4 complete for the PayPal AI Hackathon (Oct–Nov 2026). The money path, Claude brain, invoice 3-way match, simulated Cart API suppliers, Agent Toolkit integration and threat model are built and tested in CI. Hosted demo: https://shopvoice-console.onrender.com · Demo video (2:51): https://youtu.be/fEyA5FxntFQ

The 30-second pitch

Corner-store owners run on thin margins and late nights: stock-outs, supplier calls, paper invoices, and payments squeezed in after closing. An AI agent that "can pay" sounds like help, until it hallucinates an order or pays twice. That is real money.

ShopVoice Pay makes agentic payments trustworthy with three rules:

1. The model cannot break the rules. Spending policy (per-order limits, budgets, allow-listed suppliers, price-jump checks, duplicate detection) is enforced in deterministic server code. The LLM can only propose a payment.

2. Money is held, not sent, until delivery is verified. Orders use PayPal intent: AUTHORIZE. On delivery the agent compares PO, delivery count and invoice (a 3-way match), captures only what arrived, and voids the rest.

3. A human approves exactly where the risk is. Routine, in-policy orders auto-pay from the owner's vaulted PayPal account. Anything unusual (a new supplier, a 31% price jump, triple the usual quantity) steps up to a one-tap or spoken "yes".

Meet Maria (fictional), who runs a corner store in Queens. While closing up, she says "Reorder milk and eggs." The milk order ($84, allow-listed supplier) is authorized automatically: held, not charged. Eggs went up 31%, so the agent asks first. The next morning 10 of 12 crates arrive. Maria snaps the invoice, and the agent charges for 10 and releases the rest. Every authorization, capture, void and refund appears in a ledger, with the reason the agent took that action.

Related MCP server: safe-cart-ai

Try it

Hosted demo: https://shopvoice-console.onrender.com (Render, PayPal sandbox, Claude Sonnet 5.5; see docs/paypal/DEPLOY.md).

1. Click Try the demo. You get a private sample shop; Reset demo starts it over.

2. Optional, for auto-pay from a saved PayPal: Rules & PayPal → Connect PayPal and log in with a PayPal sandbox buyer account (judges: credentials are in the Devpost testing instructions). Without it, each order asks you to approve it in PayPal.

3. In Talk, hold the mic button (Chrome or Edge) or type: "Reorder milk and eggs" → "Yes, confirm" → "Yes, approve it" → "Only 8 crates of milk came" → "Two crates of milk were spoiled, refund them" → "Yes". Watch the Ledger tab.

No real money moves: everything runs in the PayPal sandbox.

Locally (about 2 minutes, Node 20+, no accounts needed):

git clone https://github.com/vansyson1308/shopvoice-pay && cd shopvoice-pay
npm ci
npm test            # build + 284 unit tests, with PayPal mocked
npm run demo:e2e    # voice flow against the in-memory demo store
npm run evals       # 25 safety + 17 quality agent cases

Open the console in your browser (two terminals, after npm test has built the project):

# terminal 1: MCP server with the in-memory demo shop and simulated PayPal
MCP_DATA_BACKEND=memory DEMO_PROVISION_SECRET=local-demo-secret-0123456789abcdef npm run start:mcp
# terminal 2: console
DEMO_PROVISION_SECRET=local-demo-secret-0123456789abcdef npm run start:console

Then open http://localhost:8091, click Try the demo, and say or type "Reorder milk and eggs". Use Chrome or Edge for push-to-talk speech recognition. This runs the offline rules brain. To use Claude, also set BRAIN=claude-api and ANTHROPIC_API_KEY in terminal 2 (see AI used).

PAYPAL_MODE=mock (the default) runs an in-process fake of the PayPal endpoints we use, so nothing leaves your machine. Its behaviour was calibrated against the real sandbox (SPIKE.md). To run against the real PayPal sandbox, copy .env.example to .env, set PAYPAL_MODE=sandbox with sandbox REST app credentials, and run npm run spike and npm run test:sandbox.

Architecture

flowchart LR
  owner([Store owner<br/>voice / chat]) --> console[Console<br/>push-to-talk, approvals,<br/>AG Grid ledger]
  console -->|MCP tool calls| mcp[ShopVoice MCP server]
  subgraph server [ShopVoice MCP server]
    tools[Tools] --> policy[Policy engine<br/>deterministic]
    policy --> payments[Payments client<br/>idempotent, retries]
    policy --> ledger[(Ledger + audit log<br/>Postgres, RLS)]
    payments --> ledger
  end
  mcp --- server
  payments -->|Orders v2, Payments v2,<br/>Vault v3, Payouts, Webhooks| paypal[(PayPal sandbox)]
  console -.LLM proposes, never pays.-> llm[LLM brain]
  mcp <-->|Cart API shape<br/>simulated| supplier[Supplier agent]

Details: docs/paypal/ARCHITECTURE.md. Day-1 sandbox spike: docs/paypal/SPIKE.md. Decisions: docs/paypal/DECISIONS.md. Threat model, with the tests that prove each mitigation: SECURITY.md.

PayPal APIs used

Every POST carries a PayPal-Request-Id idempotency key. Retries only ever replay the same key.

Demo settlement vs. production. The demo charges the shop into a ShopVoice platform sandbox account and pays suppliers out with Payouts. We chose that because the sandbox spike showed the direct routes are closed to a self-serve app:

• a vaulted payment to a supplier payee is rejected (BILLING_AGREEMENT_NOT_FOUND);

• the platform cannot release a hold it is not the payee of (403 PERMISSION_DENIED).

In production, ShopVoice would use PayPal's multiparty partner onboarding, so suppliers are onboarded payees and ShopVoice never holds third-party funds. See DECISIONS.md → Production path.

AI used, and what is simulated

• Claude brain: Claude Sonnet 5.5 by default, or Claude Haiku 4.5 as the fast option (CLAUDE_MODEL=sonnet|haiku), called through Claude in Amazon Bedrock (BRAIN=claude-bedrock) or the Anthropic API (BRAIN=claude-api). It understands spoken requests, calls the MCP tools, summarises spend and explains decisions. Opus is refused for the voice loop to keep turns fast. If Claude is unreachable, the console falls back to the offline rules brain and says so. The rules brain also runs the tests.

• Invoice vision: Claude reads a photo of a supplier invoice into line items for the 3-way match. The photo is treated as untrusted: it can only lower or hold a charge, and its text never reaches the voice brain (SECURITY.md).

• It never decides whether money moves. The deterministic rules engine does, and spoken approvals are matched by code, not by the model. Agent evals check this: 25 safety cases, including a scripted adversarial model, gated at 100% in CI.

• Simulated: the supplier's seller agent implements PayPal's Cart API merchant spec. In production, PayPal Store Sync would connect real suppliers. Anything simulated is labelled as such in the UI.

• All store, supplier and product data is fictional. Products have generic names ("Whole milk, 1 gal").

Repository layout

apps/mcp-server   MCP server, OAuth 2.1, REST for the console, payments client (src/payments)
apps/console      push-to-talk voice + chat console (MCP client), Claude brain, invoice reader
apps/supplier-agent  simulated supplier agents on PayPal's Cart API spec
packages/common   logging, Postgres/RLS helpers, rate limiting, crypto
db/migrations     Postgres schema with forced row-level security
scripts/paypal    sandbox spike runners
tests/            unit (PayPal mocked), db (Postgres), e2e (browser), sandbox (real sandbox, opt-in)
evals/            agent safety and quality cases
docs/paypal       spike, architecture, decisions, build log

Credits and license

ShopVoice Pay is built on parts of GroceryClaw (MIT), imported at commit 0fb3af4. GroceryClaw's production ingestion pipeline (Telegram/Zalo gateway, worker, KiotViet POS sync) stays in that repository and is not part of this demo. See NOTICE and BUILT_DURING_PAYPAL.md.

MIT License, see LICENSE. PayPal is a trademark of PayPal, Inc. This project is not affiliated with PayPal.