Skip to content
Devgo

Stripe

Payments with idempotency, strong consistency, and double-entry ledgers

Stripe exposes payments as an API with strong consistency, keys, and a double-entry ledger per merchant. Every charge is durable and replayable; notify merchants. Correctness and auditability dominate over raw throughput.

Product constraints

  • Money must never be lost or double-counted — strong consistency required.
  • Idempotent retries so network failures don't double-charge.
  • Full auditability and a ledger per merchant.
  • to notify merchants of async state changes (refunds, disputes).

High-level diagram

Stripe architectureA block diagram of the Stripe system's main components and request flow.MerchantAPIidempotencyLedgerdouble-entryCard networkWebhook
Illustrative block diagram of Stripe. Not to scale; see the request path below for flow.

Request path

  1. Charge. Merchant POSTs a charge with an -Key; the API validates and writes to a strongly-consistent ledger.
  2. Ledger. A double-entry ledger records the movement of money (merchant balance, fees, card network) transactionally.
  3. Card network. The charge is sent to the card network asynchronously; the result updates the charge state.
  4. Webhook. On state change (succeeded/failed/refunded), Stripe POSTs a signed webhook to the merchant; retries until 2xx.

Data model

Charges, customers, and balances in a strongly-consistent relational DB. A double-entry ledger records every money movement. keys dedupe retries. Events (for ) stored and delivered at-least-once.

Storage / cache / queue choices

Storage

Strongly-consistent relational DB (sharded by merchant); double-entry ledger.

Cache

Minimal on the write path (correctness > speed); caches for read-heavy lookups.

Queue

Internal queues for card-network calls and webhook delivery (at-least-once).

Scaling levers

  • Shard by merchant so a merchant's data is co-located and consistent.
  • keys make retries safe.
  • Double-entry ledger gives auditability and correctness.
  • Async card-network calls + decouple slow external systems.

Copy vs skip (for a smaller team)

Copy
  • Idempotency keys on all mutating endpoints.
  • Double-entry ledger for money movement.
  • Shard by merchant for co-located consistency.
  • Signed, retried webhooks for state changes.
Skip
  • Eventual consistency for money (use strong/transactional).
  • Caching the write path (correctness first).
  • Single global ledger (shard by merchant).

, , , ,

Sources