Agent Checkout Steward

Policy-bound AI checkout on PayPal sandbox Orders v2

Comment

Inspiration

Agentic commerce is arriving faster than the guardrails. An LLM that can call a payment API is useful, and dangerous, if the only thing standing between a cart and a capture is a prompt. I wanted a checkout agent that treats the model as a planner, not the authority: the human sets a hard mandate, the model proposes a policy in JSON, code validates and enforces it, and only then does PayPal sandbox create and capture an order. AI drafts, code decides, PayPal settles.

What it does

Agent Checkout Steward is a local checkout desk (CLI + browser UI) that runs a policy-bound purchase against the PayPal sandbox Orders v2 API.

  1. The operator picks a purchase (demo: Harbor & Co sensor, USD 86.00).
  2. The planner (Vercel AI Gateway with google/gemini-2.5-flash, or a deterministic fallback) drafts a spending policy as JSON: budget cap, merchant allowlist, one-time purchase, and re-approval if the amount or merchant changes.
  3. validateProposal accepts that JSON only when it fits a fixed operator mandate (USD 150 cap; Harbor & Co and Northline Supply only; one-time; re-approval on change). A bad draft is discarded.
  4. The human confirms the policy.
  5. The desk creates a PayPal Orders v2 order (intent CAPTURE) on the sandbox.
  6. The sandbox buyer approves on PayPal.
  7. The desk captures; status becomes COMPLETED.
  8. An audit log records POLICY_DRAFTED, POLICY_CONFIRMED, ORDER_CREATED, BUYER_APPROVED and CAPTURED next to the policy snapshot and order id.

Code refuses (PayPal is never called): over-cap carts (e.g. USD 240), merchants not on the allowlist, amount or merchant changes after confirmation without a new approval, and subscriptions.

Mock mode needs no keys; sandbox mode switches on when PayPal sandbox credentials are set, and live hosts are rejected. With no model key, a deterministic planner runs so judges can try the desk without an AI account.

Live sandbox proof (2026-10-31): order 1T34005765161664K captured as 2UG70064PG1875509, COMPLETED, with Gemini planning (the run shown in the video).

How we built it

TypeScript on Node.js 22, a local HTTP desk and CLI. PayPal REST: OAuth client credentials, Create Order, approval via the payer-action link and return URL, then Capture (Orders v2), with PayPal-Request-Id idempotency and retries on 429/5xx. The planner uses Vercel AI Gateway through the AI SDK (OpenAI-compatible and Anthropic optional). Policy validation and enforcement live in application code; the audit trail is append-only JSONL. 35 automated tests cover the validator, enforcer, planners, Orders v2 request shape, mock session, return handling and desk API without hitting the live sandbox.

Challenges we ran into

Prompt vs mandate: early drafts treated the model as the policy; we flipped it so the mandate is fixed in code and the model may only propose JSON the validator accepts. The sandbox return flow needed care so orders created on the CLI or the desk are both adopted on return. And keeping credentials out of the repo, logs, screenshots and video shaped how env loading and logging work.

Accomplishments that we're proud of

A real end-to-end sandbox checkout on the desk where Gemini drafted the policy, code enforced it, and PayPal captured it as COMPLETED; enforcement the model cannot bypass; a zero-key mock path for judges; 35 passing tests; MIT-licensed public repo.

What we learned

For agentic payments the interesting boundary isn't whether the model can call create-order, it's what is allowed to call it. Treating the LLM as proposer and narrator, with TypeScript as the authority, made a cleaner product and a clearer demo.

What's next

An optional hosted demo, richer mandates (multi-currency, per-merchant caps, time-bounded approvals) still enforced in code, and better handling of expired sessions and declined captures. Sandbox only.

Built With

Share this project:

Updates

Submission history