AI System Design

Design an Agent Payment Gateway

Step 1 / 9

Learn AI system design by building the platform that lets autonomous agents pay for things mid-task without draining an account.

In the interview room

How you’d open this design in an interview

Before any boxes: agree what it must do, pin the qualities that shape everything, then build — naming each trade-off as you make it. The walkthrough above is that exact order.

Functional requirements

What it must do — agree on these before drawing a single box.

  • Pay mid-task: let an autonomous agent settle a paywall (an API fee, a dataset charge) without a human checkout.
  • Scope authority: a signed mandate caps per-transaction and total spend, allowed merchants, and an expiry.
  • Cap spend: refuse any payment that would breach the per-transaction ceiling or the cumulative total.
  • Settle machine-natively: complete the x402 (HTTP 402) flow — pay, retry with proof, deliver.
  • Audit: append every payment decision, allow or deny, to an immutable record.

Non-functional requirements

The qualities that shape the whole design — each one names the mechanism that buys it.

The agent holds nothing worth stealing
Route every payment through one mediated gateway; the agent holds no spendable credential of its own.
A hijacked agent can’t assert broad spending power
The Mandate Verifier checks the mandate’s signature, scope and expiry against the issuer’s key before honoring it — authority is a signed artifact, not a claim.
A runaway loop is bounded to a number you chose
The Spend-Cap Enforcer checks each payment against the per-transaction ceiling and the cumulative total before settlement, refusing anything that would breach either.
Autonomous payment with no human in the loop
x402 settlement pays, retries with proof, and delivers the resource inside the HTTP request/response cycle — no human checkout.
Every incident is reconstructable
An append-only Audit Trail records every decision including refusals, so a compromised agent can’t erase its own tracks.

The trade-offs you say out loud

Senior signal isn’t the boxes — it’s naming what you gave up and why it was the right price.

A mediating gatewayover the agent paying merchants directly

A direct credential gives unlimited, unscoped spending power a bug or injection can drain. The gateway is the one place to verify, cap, and log before money moves.

A signed mandate, verifiedover trusting the agent’s claim

A prompt-injected agent will happily claim it can spend anything. Authority must come from a signature it can’t forge, checked for scope and expiry.

Cap checks before every settlementover a post-run overspend report

A cap checked after the fact doesn’t bound anything — the money already left. Enforce both the per-transaction and cumulative limits before each payment.

x402 machine-native settlementover a human purchase-order approval

Emailing a PO and waiting for a human defeats autonomous mid-task payment. x402 settles inside the request/response cycle, on the agent’s behalf.

Fail closed on the gatewayover failing open when it can’t verify

An unenforced payment is the exact risk the system exists to prevent. If a mandate or cap can’t be checked, refuse rather than allow.

What this teaches

Learn AI system design by building the platform that lets autonomous agents pay for things mid-task without draining an account. Not the human card rails (see Payment System and Digital Wallet for those) — this is the agent-rails layer: a gateway that verifies a signed spending mandate, enforces per-transaction and cumulative spend caps BEFORE any money moves, settles via the x402 (HTTP 402) machine-native checkout, and keeps an immutable audit trail — so a runaway or hijacked agent is stopped by the platform, not by someone noticing the bill.

Key takeaways

  • The agent holds no spendable credential — every payment flows through one mediated gateway.
  • A signed mandate scopes spending (per-txn, total, merchants, expiry); the gateway verifies signature/scope/expiry, never trusting the agent's claim.
  • Spend caps are enforced BEFORE every settlement, against both the per-transaction and cumulative limits — a runaway loop is bounded to the cap.
  • Settlement uses the x402 (HTTP 402) machine-native flow: pay, retry with proof, deliver — no human checkout, no credential in the agent's hands.
  • Every decision, allow or deny, is appended to an immutable audit trail so incidents can be reconstructed and a compromised agent can't erase its tracks.

Concepts covered

  • A gateway, not a corporate card
  • The agent pays the merchant directly
  • Route every payment through a gateway
  • Verify a signed mandate
  • Enforce spend caps before settlement
  • Pay via x402 and return proof
  • Log every decision, immutably

Design an Agent Payment Gateway — read the full walkthrough as text

the same steps, decisions & trade-offs, for reading, reference & search

The big idea

A gateway, not a corporate card

An autonomous agent will eventually hit a paywall mid-task — an API that costs a cent a call, a dataset behind a charge. Stopping to ask a human defeats the point of autonomy; handing the agent a shared API key or card defeats your bank balance. How do you let an agent pay without letting it — or whatever hijacks it — spend without limit?

We'll build the agent-rails layer: a gateway every payment flows through, a signed mandate that scopes what the agent may spend, spend caps enforced before any money moves, machine-native x402 settlement, and an immutable audit trail. This is not the human card-rails system — see Payment System and Digital Wallet for those; this is the layer built for an autonomous spender.

How to read this: Each step opens with a real design decision — make the call before I show you what ships. Watch the diagram grow, hover the boxes, and at the end let a runaway agent blow its budget and present a forged mandate to see the gateway refuse. Hit Begin.

Step 1 · The baseline

The agent pays the merchant directly

The naive starting point: give the agent an API key or card credential and let it call the merchant's pay endpoint itself. It works in the demo. What's the actual risk the moment this agent is autonomous and reads untrusted content?

Design decision: An autonomous agent holds a payment credential and pays merchants directly. What's the core risk?

The call: The agent holds unlimited spending power with no enforced ceiling, so a bug, an infinite loop, or a prompt injection can spend arbitrarily — and nobody can stop it without revoking the credential everywhere. — Exactly the problem: authority is ambient and unbounded. A runaway loop or a hijacked agent can drain the account, and the only blunt fix is killing a shared credential that other legitimate agents also depend on. There's no per-agent scope, no cap, and no record of why any payment happened.

A direct credential gives the agent unlimited, unscoped spending power. A looping bug or a prompt-injected instruction can spend arbitrarily, and there's no per-agent limit, no record of why a payment happened, and no way to stop one agent without revoking a credential others share.

Ambient authority is the bug: The root problem is that spending power is ambient — the agent can pay simply because it holds a credential. Everything below replaces "can pay because it has the key" with "can pay only this much, here, because a signed mandate says so."

Step 2 · The front door

Route every payment through a gateway

First move: the agent never touches a raw credential. Every payment request goes to a Payment Gateway API instead of the merchant. Why is a mediating front door the prerequisite for everything else?

Design decision: Why route all agent payments through a gateway instead of letting the agent pay merchants directly?

The call: A single mediated choke point is where you can verify the mandate, enforce caps, settle safely, and log every decision — none of which is possible if the agent pays merchants directly with its own credential. — The gateway is the enforcement point. By making every payment flow through one mediated API, you get one place to check "is this allowed?" before anything happens — and the agent holds no spendable credential of its own, so there's nothing to steal or misuse directly.

All payments flow through the gateway, and the agent holds no spendable credential of its own. This single mediated choke point is what makes every downstream control — mandate checks, spend caps, safe settlement, audit — possible; without it, there's nowhere to enforce policy before money moves.

One choke point to govern: Every real control that follows lives at the gateway. Centralizing payment through one mediated API is the architectural move that turns "hope the agent behaves" into "the platform decides, per payment."

Step 3 · Delegated authority

Verify a signed mandate

The gateway needs to know what THIS agent is actually allowed to spend. The answer is a mandate: a signed authorization scoping the agent's spending — a per-transaction ceiling, a total budget, allowed merchants, an expiry. What must the gateway do with it, and why can't it just trust the agent's request?

Design decision: The agent presents a mandate describing what it may spend. How should the gateway treat it?

The call: Verify the mandate's signature, scope, and expiry against the issuer's key before honoring it — authority comes from a signed artifact, not from the agent's claim. — Right: the mandate is like an OAuth token for money. The gateway checks it was validly signed by the issuer, hasn't expired, and actually covers this merchant — so a hijacked agent can't just assert broad spending power, because it can't forge a valid signature.

The Mandate Verifier checks the presented mandate's signature, scope, and expiry against the issuer's key before the gateway honors it. Authority is delegated by a signed artifact — an OAuth-scopes-for-money token — so a prompt-injected agent can't simply claim broad spending power it was never granted.

Signed, not asserted: This is the difference between "the agent says it may spend $10,000" (a claim) and "here is a mandate, signed by the treasury, capping this agent at $50 at these two vendors until Friday" (a verifiable grant). Only the second survives a hijacked agent.

Step 4 · The hard limit

Enforce spend caps before settlement

A valid mandate says the agent may spend up to a cap. Now the gateway has to actually enforce it on each payment. When should the cap be checked — and against what?

Design decision: The mandate allows up to $50 total, $20 per transaction. When and how should the cap be enforced?

The call: Before every settlement: check the amount against the per-transaction ceiling AND the running cumulative spend against the total — refuse if either would be breached. — Correct: the check must run before money moves, on every payment, against both the single-payment limit and the accumulated total. A looping agent that tries ten $20 payments is refused the moment cumulative spend would cross $50 — the cap bounds the damage no matter how many times it loops.

Before every settlement, the Spend-Cap Enforcer checks the amount against the per-transaction ceiling and the running cumulative spend against the mandate total, refusing anything that would breach either. Enforcement runs in the payment layer, before money moves — not as an after-the-fact report — so a runaway loop is bounded to the cap you chose.

Least privilege for money: This is the spending equivalent of a sandbox: the agent's effective power is the narrowest set of payments that still lets it do its job. Everything else is denied by default, checked continuously, enforced by the platform rather than trusted to the model.

Step 5 · Settlement

Pay via x402 and return proof

The mandate is valid and the payment is within cap. Now actually pay the merchant. The merchant speaks x402 — it responds to a request with HTTP 402 and payment terms. How does settlement work, and why is this a clean fit for an agent?

Design decision: The merchant returns HTTP 402 with a price. How does x402 settlement complete the payment?

The call: The gateway performs the payment (typically a small stablecoin transfer), retries the request carrying proof of payment, receives 200 + the resource, and hands it back to the agent. — Right: x402 revives the dormant HTTP 402 status as a machine-native checkout. Server says "402, here's the price," the gateway pays and retries with proof, gets the resource. Payment becomes just another part of the protocol — which is exactly what an autonomous agent needs.

On the merchant's 402 + price, the x402 Settlement service performs the payment, retries with proof, receives the resource, and returns it to the agent — all inside the request/response cycle, no human checkout. The agent never holds a credential; the gateway settles on its behalf, only after mandate and cap checks have passed.

Payment as protocol: x402 turns paying into a normal step of an HTTP exchange — 402, pay, retry with proof, 200. That machine-native flow is what makes autonomous payment possible at all; the gateway wraps it in the verification and caps that make it safe.

Step 6 · Accountability

Log every decision, immutably

Money moved. Whether a payment was allowed or refused, the platform needs a record of why. What has to be captured, and why is an append-only audit trail non-negotiable for a spending system?

Design decision: What should the audit trail record, and why does it matter for a payment gateway?

The call: Every payment decision — mandate checked, cap state, amount, merchant, allow or deny — appended immutably, so any incident can be reconstructed and no record can be quietly altered. — Right: a spending system you can't reconstruct after the fact is one you can't trust. An append-only log of every decision (including refusals) is what lets you audit spend, prove compliance, and investigate a compromised agent — and immutability means a hijacked agent can't erase its own tracks.

The Audit Trail appends every payment decision immutably — mandate checked, cap state, amount, merchant, allow or deny — including refusals. A spending system you can't reconstruct is one you can't trust; the immutable log is what makes spend auditable, incidents investigable, and a compromised agent's tracks impossible to erase.

If it moved money, it's on the record: Every decision the gateway makes is logged, allow or deny. That record is both the compliance artifact and the incident-response tool — and because it's append-only, it survives exactly the compromise it's meant to help investigate.

The payoff

A spender you can actually trust

Put it together: an agent can pay for what its task needs, autonomously — and a runaway loop, a bug, or a full hijack is bounded to a number you chose in advance, with a complete record of every decision.

That's the agent-payment gateway. Delegated, bounded, revocable authority, verified and capped before money moves, settled machine-natively, and logged immutably — the same least-privilege discipline that governs an agent's tools, applied to its wallet.

  • The agent holds no spendable credential — every payment flows through one mediated gateway.
  • A signed mandate scopes spending (per-txn, total, merchants, expiry); the gateway verifies signature/scope/expiry, never trusting the agent's claim.
  • Spend caps are enforced BEFORE every settlement, against both the per-transaction and cumulative limits — a runaway loop is bounded to the cap.
  • Settlement uses the x402 (HTTP 402) machine-native flow: pay, retry with proof, deliver — no human checkout, no credential in the agent's hands.
  • Every decision, allow or deny, is appended to an immutable audit trail so incidents can be reconstructed and a compromised agent can't erase its tracks.
built so a runaway agent is capped at the mandate, not at the credit limit — make the calls, forge a mandate, blow the budget, and watch the gateway refuse.
Finished this one? 0 / 61 AI System Designs done

Explore the topic

See this alongside everything else on the same subject — handbooks, system designs, challenges and tools, in one place.

More AI System Designs