Design Case Studies · Lesson 12

Design: Payments API

Money is the discipline case for API correctness. A payment cannot be applied twice, cannot be lost mid-flight, and cannot be silently wrong. Every design pattern in this lesson exists to defend one rule: charge exactly once, no matter what the network does.

1 — Requirements

Payments is a narrow domain with unusually strict correctness requirements. Start by being precise about what the system must do — and must never do.

Functional requirements

• Create a charge: debit a payment method for an amount in a specified currency. Return a charge ID the caller can use to track settlement.
• Never double-charge: if the caller retries (due to network timeout, server error, or client crash), the charge must be created at most once. This is the primary correctness requirement.
• Async settlement: a charge transitions through states (pending → processing → succeeded / failed). Settlement is handled by card networks that respond on their own schedule — sometimes milliseconds, sometimes hours. The API must not block waiting for it.
• Webhooks for events: callers need to know when a charge succeeds or fails. Polling is error-prone at scale; push events via webhook are the standard answer.
• Refunds: a succeeded charge can be refunded in full or partially. A refund creates a new ledger entry; it does not mutate the original charge.
• Audit trail: every money movement must be traceable — when it happened, who initiated it, what amount, what state. This is a legal and compliance requirement, not just engineering hygiene.

Non-functional requirements

• Strong consistency for writes: a charge must be durably written to the ledger before the API returns 201. No eventual consistency on the money path.
• Idempotent charge creation: mandatory, not optional — a payment processor that permits double charges has a product defect.
• Secure card data handling: the API never stores raw PAN (primary account number). Tokenisation offloads PCI scope to a vault.
• Webhook reliability: events must be delivered at least once, with retries on non-200 responses. Webhook consumers must handle duplicates.

2 — Design decisions

Decision 1: Idempotency keys are mandatory, not optional

Every POST /v1/charges call must include an Idempotency-Key header. This is the most important design decision in the entire API. Here is why it is mandatory and not merely recommended.

Imagine a client sends a charge request. The server processes the charge, debits the card, and then — before sending the HTTP response — the network drops the connection. From the client's perspective, the request timed out. Did the charge go through? The client cannot know. If it retries without an idempotency key, and the server processes the second request fresh, the customer is charged twice.

An idempotency key is a client-generated unique string (typically a UUID) that the server stores alongside the result. On a duplicate request with the same key, the server returns the stored result from the first attempt — not the result of a new operation. The key converts a non-idempotent write into an effectively idempotent one. See Lesson rel-02 for the theory and Lesson dbg-05 for debugging failures in real implementations.

Decision 2: Async settlement with an explicit state machine

Card networks do not respond synchronously. The issuing bank may take 200 ms or 30 seconds. The API must return before settlement is confirmed. The solution is an explicit charge state machine that both the API and the caller understand:

The API returns a pending charge immediately. Settlement transitions happen asynchronously and are communicated by webhook.

Decision 3: Webhooks for settlement events

Callers who need to know when a charge settles have two options: poll GET /v1/charges/:id or register a webhook URL and receive a push. Polling is reliable but wastes calls on charges that are still pending; at scale (millions of charges per day), constant polling creates significant load. Webhooks push the event to the caller when it happens, with no polling overhead.

The key webhook reliability requirements are: (1) deliver at least once (retry on non-200), (2) sign every delivery so the recipient can verify authenticity, (3) make the event envelope stable so old consumers can ignore new fields. See Lesson dbg-04 for patterns and failure modes.

Decision 4: Append-only ledger, never mutate amounts

The ledger records every money movement as an immutable row. A refund does not update the original charge row — it inserts a new refund row that references the charge. This design has three properties that matter for compliance and debugging: (1) any state can be reconstructed by replaying the ledger; (2) a bug that corrupts one row does not destroy the historical record; (3) auditors can verify that the sum of ledger entries equals the expected balance without trusting any computed field.

Decision 5: Strong consistency for all writes, and why

Payments is one of the few domains where eventual consistency is unacceptable on the write path. If a charge is written to a replica that then diverges from the primary, a subsequent GET might return stale state — "your $500 charge is pending" when the issuer has already declined it. The consequences (shipping goods before payment clears, double-applying a refund) are real financial harm. The charge creation path must write to the primary durably and read its own writes before returning 201.

3 — The API model

Create a charge

POST /v1/charges
Authorization: Bearer <secret-key>
Idempotency-Key: idem_7f3a2c89-0e14-4b8f-a9d1-c3b4e5f60712
Content-Type: application/json

{
  "amount":      4999,         // cents — never floats for money
  "currency":    "usd",
  "payment_method": "pm_1Nz8kG...", // tokenised; no raw card data
  "description": "Annual subscription — Pro plan",
  "metadata": {
    "order_id": "ord_8821",
    "user_id":  "usr_2209"
  }
}

# First request — charge created
HTTP/1.1 201 Created
{
  "id":         "ch_9pXwL4",
  "status":     "pending",
  "amount":     4999,
  "currency":   "usd",
  "created_at": "2025-09-01T10:04:22Z",
  "livemode":   true
}

# Retry with the same Idempotency-Key (e.g. after a network timeout)
HTTP/1.1 201 Created          // same status code
{
  "id":     "ch_9pXwL4",   // same charge id — no new charge created
  "status": "pending"
}
# Replay-Response: true header may be included to signal dedup path was taken

Retrieve a charge

GET /v1/charges/ch_9pXwL4
Authorization: Bearer <secret-key>

HTTP/1.1 200 OK
{
  "id":          "ch_9pXwL4",
  "status":      "succeeded",
  "amount":      4999,
  "amount_refunded": 0,
  "currency":    "usd",
  "description": "Annual subscription — Pro plan",
  "created_at":  "2025-09-01T10:04:22Z",
  "succeeded_at": "2025-09-01T10:04:24Z",
  "payment_method": { "id": "pm_1Nz8kG...", "last4": "4242", "brand": "visa" },
  "metadata":    { "order_id": "ord_8821" }
}

Webhook event — charge settled

# Stripe-style: Payments API POSTs to the caller's registered URL
POST https://yourapp.example.com/webhooks/payments
Stripe-Signature: t=1693562662,v1=abc123...,v0=oldsig...
Content-Type: application/json

{
  "id":         "evt_1OBj3k",
  "type":       "charge.succeeded",
  "created":    1693562662,
  "data": {
    "object": {
      "id":      "ch_9pXwL4",
      "status":  "succeeded",
      "amount":  4999,
      "currency": "usd"
    }
  }
}

# Your handler must: (1) verify the signature, (2) respond 200 quickly,
# (3) process idempotently — the same event may be delivered more than once.

4 — Evaluation & consistency analysis

Idempotency + consistency: why both are required

Idempotency prevents double-charges on retry. Strong consistency prevents a different class of bug: a read that returns stale state after a write. If a charge succeeds but a subsequent GET (from a replica that hasn't caught up) returns "status": "pending", the caller might send a second charge attempt with a fresh idempotency key — logically, they think the first one didn't go through. These are different failure modes that require different defences:

Latency budget for a charge

The append-only ledger as audit record

A compliant payment system must be able to answer: "what exactly happened to charge ch_9pXwL4, in what order, and at what time?" An append-only ledger makes this straightforward. Every event — creation, authorisation, capture, refund, dispute — is a new immutable row. To reconstruct the balance for any account at any point in time, sum the relevant rows. No row is ever updated or deleted. This is not just good engineering; it is what regulators and card network rules require.

Under the hood: the core mechanism

Three internal mechanisms are what make a payments API trustworthy at scale: the idempotency-key store that prevents double charges, the append-only ledger that makes every money movement auditable, and the charge state machine that sequences authorization from capture and settlement. Seeing how they interact makes the design constraints — strong consistency, integer amounts, write-before-charge ordering — feel inevitable rather than arbitrary.

The idempotency-key store

The key store is a separate table (or Redis hash with TTL) keyed on the idempotency key string. It stores the key, the associated charge ID, the HTTP status code, and the serialized response body from the first successful request:

idempotency_keys table:
  key        TEXT PRIMARY KEY          -- client-supplied UUID
  charge_id  TEXT                      -- references charges.id
  status     INT                       -- HTTP status from first attempt (201, 400, 402...)
  response   JSONB                     -- serialized response body
  created_at TIMESTAMPTZ DEFAULT now()
  expires_at TIMESTAMPTZ               -- typically now() + 24 h; after this a fresh charge is allowed

The critical constraint — enforced by the DB, not by application code:
  UNIQUE (key)  -- concurrent retries both INSERT; one wins, one gets a unique violation → returns stored result

The write-before-charge ordering is non-negotiable. The correct sequence:

Step 1 — Write key + pending state to ledger (durable, in one transaction)
  BEGIN;
    INSERT INTO idempotency_keys (key, status) VALUES ($key, 0);   -- 0 = in-flight
    INSERT INTO ledger (type, charge_id, amount, status)
      VALUES ('charge', $charge_id, $amount, 'pending');
  COMMIT;                                                            -- crash-safe from here

Step 2 — Send authorisation to card network (can take 100–500 ms)
  result = card_network.authorize(payment_method, amount, currency)

Step 3 — Update key + ledger with final result
  BEGIN;
    UPDATE idempotency_keys SET status=201, response=$body WHERE key=$key;
    UPDATE ledger SET status=$result.status WHERE charge_id=$charge_id;
  COMMIT;

If the process crashes between step 1 and step 2, the key row exists with status=0. A retry sees the key, finds status 0 (in-flight), and can either wait briefly and retry the lookup or treat it as "a charge may already be in progress — do not initiate another." If the process crashes between step 2 and step 3, the card was charged but the key status is still 0 — a reconciliation job scans for in-flight keys older than N minutes and resolves them by querying the card network for their status.

The append-only ledger

The ledger is a single table where every money movement is an immutable insert. No row is ever updated or deleted after it is committed. A refund, a dispute chargeback, and a settlement confirmation are all new rows:

ledger table (simplified):
  id         BIGSERIAL PRIMARY KEY
  type       TEXT      -- 'charge' | 'capture' | 'refund' | 'refund_settled' | 'dispute' | 'dispute_won'
  charge_id  TEXT      -- references the originating charge
  amount     INT       -- cents; positive = debit, negative = credit
  currency   CHAR(3)
  status     TEXT
  occurred_at TIMESTAMPTZ DEFAULT now()
  metadata   JSONB

To compute the current balance for account acc_123: SELECT SUM(amount) FROM ledger WHERE account_id = 'acc_123'. To reconstruct what the balance was on September 1st at noon: add AND occurred_at <= '2025-09-01T12:00:00Z'. No snapshot, no cached field needed — the ledger is the truth.

The charge state machine

A charge does not go directly from "created" to "money moved." Card networks use a two-step model: authorization (a hold on funds) followed by capture (actual movement of money). For most e-commerce flows these happen together in milliseconds, but understanding them separately is essential for partial captures, split shipments, and pre-authorization patterns:

Worked trace: a charge with one network retry

The client's server times out waiting for the 201 and retries once. Watch what the idempotency store prevents:

T=0 ms    Client sends POST /v1/charges
           Idempotency-Key: idem_7f3a2c89
           { amount:4999, currency:"usd", payment_method:"pm_1Nz8kG..." }

T=5 ms    Payments API: idempotency key NOT found → write key (status=0) + pending ledger row
           idempotency_keys: { key:"idem_7f3a2c89", status:0 }
           ledger:           { type:"charge", charge_id:"ch_9pXwL4", amount:4999, status:"pending" }

T=8 ms    API sends authorisation to card network (Visa/Mastercard acquirer)

T=310 ms  Card network responds: approved  (issuer: Chase, card ending 4242)

T=315 ms  API updates ledger + idempotency key
           ledger:           { type:"capture", charge_id:"ch_9pXwL4", amount:4999, status:"succeeded" }
           idempotency_keys: { key:"idem_7f3a2c89", status:201, response:'{"id":"ch_9pXwL4","status":"pending"}' }

T=316 ms  API enqueues charge.succeeded webhook

T=316 ms  ← network drop occurs before response reaches client →

T=5316 ms Client times out (5 s), retries POST /v1/charges with same Idempotency-Key

T=5320 ms Payments API: idempotency key FOUND (status=201)
           Returns stored response: 201 { id:"ch_9pXwL4", status:"pending" }
           Card network is NOT called.
           Ledger has exactly ONE charge entry.

T=5600 ms Webhook delivery: POST client-webhook-url
           { event:"charge.succeeded", data:{ id:"ch_9pXwL4", amount:4999, status:"succeeded" } }
           Client sees 201 on retry AND then receives the webhook → exactly one charge.

One charge, one ledger entry, one webhook — regardless of how many times the client retried. The idempotency key is the single mechanism that makes this guarantee hold across network failures.

Operating & debugging it

Payment failures fall into three buckets: card declines (the issuer said no — nothing wrong with the API), integration errors (the API returned 4xx — the caller sent something invalid), and infrastructure failures (the API returned 5xx, or the webhook never arrived). Triaging which bucket you're in is step zero.

Inspecting a charge

Symptom → cause → fix

In production: how the real Stripe API does it

Every design decision in this case study maps directly to a documented Stripe behaviour. The table below is a reality check: the patterns here are not hypothetical — they are the patterns Stripe has been running at scale for over a decade.

Why a payments API needs all of these at once

Each mechanism above is individually defensible, but the real insight is that they form a mutually reinforcing system. Removing any one of them creates a gap that the others cannot fill:

• Idempotency without strong auth is useless: an attacker who can forge or replay requests will collide on existing keys or bypass them with fresh ones.
• Webhooks without signature verification let anyone on the internet trigger settlement logic in your application by posting a plausible-looking payload to your endpoint.
• Versioning without auth means a caller who injects a different Stripe-Version header could force your integration into a compatibility mode you haven't tested.
• Rate limiting without idempotency means that when a client gets a 429 and retries, each retry risks creating a duplicate charge — the rate limiter slows the requests but doesn't prevent duplication.
• Cursor pagination without strong consistency means the has_more flag can reflect a stale view of the list, causing the caller to miss newly-settled charges between pages.

A payments API is correct only when all of these properties hold simultaneously: idempotency ensures money moves exactly once, auth ensures only authorised parties can move it, webhook signatures ensure settlement events can be trusted, versioning ensures the contract never breaks unexpectedly under the caller's feet, rate limiting ensures the charge path stays healthy under load, and pagination ensures full audit visibility without missed or duplicated records.

POST /v1/charges/ch_9pXwL4/refunds
Authorization: Bearer <secret-key>
Idempotency-Key: ref-idem-9d23e7a1
Content-Type: application/json

{
  "amount": 4999,     // partial refund — omit for full refund
  "reason": "customer_request"
}

HTTP/1.1 201 Created
{
  "id":         "re_3xNpQ2",
  "charge":     "ch_9pXwL4",
  "amount":     4999,
  "currency":   "usd",
  "status":     "pending",
  "created_at": "2025-09-08T09:12:01Z"
}

Sources & further reading

• Stripe — Idempotent Requests
• Stripe — Webhooks documentation
• Stripe API Reference — Charges object
• Stripe — Error handling and retries
• Mastercard — Payment transaction flow overview
• AWS Builders' Library — Making retries safe with idempotent APIs
• Martin Fowler — Idempotent Receiver pattern