Stripe processes hundreds of billions of dollars in payments per year by being the calmest API in the middle of one of the messiest systems ever built: the four-party card payment network. Understanding how Stripe works is less about moving money and more about keeping a perfectly honest ledger while talking to dozens of slow, unreliable downstream systems without ever losing track of a cent.
The problem at scale
A card payment isn’t one transaction. It’s a multi-day conversation between five parties: the customer, the merchant, Stripe, the card network (Visa/Mastercard), and the issuing bank. Each step can fail independently, the network’s responses can arrive out of order, and retries are a fact of life. Stripe has to make this look like a single synchronous API call to the merchant while actually orchestrating an asynchronous, fault-tolerant, regulator-audited workflow. And the canonical state of any charge (what the merchant actually sees) has to be correct even when the network lies, times out, or settles the wrong amount.
The hard constraint: the merchant must never see a state that didn’t really happen. A “succeeded” status that the network later rejects is a support nightmare. A “failed” status for a charge that actually succeeded is a lost customer.
How Stripe Works: The Core Architecture
A merchant’s server calls Stripe’s API Gateway with an idempotency key on every charge. The gateway does TLS, authentication, and rate-limiting, then forwards to the Charge Service, which runs the two-phase payment flow: authorize (ask the issuing bank to reserve the funds) and capture (ask the bank to actually move them). Before submitting to the network, every charge passes through Radar, Stripe’s fraud-scoring ML model, which can block the charge pre-emptively if the risk is too high. The result of every step (request, response, settlement, refund, fee, payout) is appended as an immutable row to the Ledger, which is the canonical source of truth. Money state is computed by reading the ledger; the ledger itself is never updated, only appended to.
The ledger is the architecture
Most payment systems keep “current balance” as a mutable field in a database row, and update it on every transaction. Stripe explicitly doesn’t. The ledger is an append-only log of events; a merchant’s available balance, pending payouts, and reserve holds are all computed by aggregating ledger entries within a time window. This is more compute at query time, but it eliminates the entire class of bugs where a failed update corrupts the canonical state. If a downstream system goes wrong, you replay the ledger from the start and you get back to exactly correct. This is the same bet Bitcoin’s UTXO model and banks’ actual core systems make: the truth is the log.
Regulators love this. Auditors can ask “what was the state of this account on March 14th at 3:47pm” and the answer is a deterministic computation over the ledger, not a database restore.
Idempotency keys are not optional
Every Stripe charge request includes an idempotency key, a merchant-generated UUID that uniquely identifies the intent. If the merchant retries (because their own code timed out, or the network flaked, or whatever), the retry hits Stripe with the same key, and Stripe returns the result of the original request instead of creating a second charge. This is the API contract that makes safe retries possible. Without it, every network blip would risk double-charging the customer, and merchants would have to build elaborate reconciliation logic on their side. Stripe moved the burden to its own infrastructure.
The pattern is so load-bearing that Stripe’s API design has influenced almost every payment and idempotency-sensitive API since: Twilio, Square, Shopify, and modern bank APIs all use idempotency keys the same way.
The one non-obvious insight
Radar (the fraud model) runs before the network call, not after. The decision to block a charge because it looks fraudulent happens at Stripe, not at Visa. This means Stripe is taking on the cost of false positives (blocking legitimate customers) in exchange for keeping the downstream clean, and the issuing banks reward high-cleanliness payment processors with lower interchange fees. The fraud model is, indirectly, the profit center.
Stripe is a calm API over a four-party asynchronous network, backed by an append-only ledger that makes the system auditable, replayable, and correct under failure. The lesson every API designer should study: idempotency keys, immutable logs, and pushing complexity inward are how you make a hard system feel simple.
Continue learning: