How to design a payment system
The first sections are free. The deep dives, level expectations and quiz are part of Pro.
On this page
- The problem
- Clarifying questions
- The requirements menu
- Non-functional requirements
- Estimates
- Core entities
- The API
- The high-level design
- What breaks first
- The deep dives
- Entity fields
- Never charging twice
- Slow and failed payments
- Reconciliation and consistency
- Variants
- What each level is expected to show
- The 30-second answer
- Quiz
The problem
The payment system behind a store takes a buyer's card payment through an outside provider, records each money movement in a double-entry ledger, keeps a balance for each seller, and pays sellers out later. The volume is modest, about a million transactions a day, so the answer turns on correctness rather than throughput: a payment order id that is checked at each hop so a retry after a timeout doesn't charge twice, a pending status fed by the provider's callback, and a nightly check of your books against the provider's settlement file.
Clarifying questions
| Ask | Why it matters | A typical answer |
|---|---|---|
Do we process cards ourselves, or hand that to a payment provider? | Touching card numbers brings card-industry compliance work and a different design. With a provider, the design is about coordinating with it and keeping your own books right. | A payment provider handles the card. Card data stays off our servers, ideally through the provider's hosted payment page. |
How many payments a day, and in how many currencies? | It decides whether the database or the bookkeeping is the hard part, and whether currency conversion belongs in the ledger. | About a million transactions a day, roughly 10 a second, all in one currency. |
How quickly must a buyer learn the result, and can a payment stay pending for a while? | If some payments take hours, the buyer's request can't wait for the answer, and you need a pending state and a way for the final result to arrive later. | Most settle in seconds, but some take hours. Show pending and finish the payment when the provider reports back. |
How and when do sellers get paid? | Payouts need a running balance per seller and a second money movement, which shapes the wallet and the ledger. | Sellers are paid out on a schedule, for example monthly, from a balance the system keeps for them. |
Are refunds, subscriptions or other payment methods in scope? | Each adds a flow with its own states. Knowing they are out lets you keep the state machine small. | No. Card pay-in and seller pay-out are enough for this round. |
What does the business need from the books each morning? | It tells you whether reconciliation is a nice-to-have or a requirement, and who handles what it finds. | The ledger must agree with what the provider settled and with each seller's wallet, checked once a night, with a finance team handling what the checks can't fix. |
Non-functional requirements
| Requirement | What it forces |
|---|---|
Never charge a buyer twice for one order | An idempotency key from the client, a unique payment order id stored under a unique constraint before anything is sent, and that same id sent along to the provider so it refuses a repeat. A retry at any hop finds the earlier attempt instead of starting a new charge. |
Correctness over throughput: about 10 transactions a second in Alex Xu’s framing | One relational database with ACID transactions, status reads served by the primary, and no sharding. The design effort goes to states, retries and reconciliation, not to capacity. |
No payment data lost when a component fails | Write the payment event and each payment order durably before calling the provider, keep a synchronous standby replica of the database if a committed payment must survive losing the primary, and pass results between services through a durable queue so a ledger or wallet outage delays an update instead of dropping it. |
Mismatches with the payment provider found by a nightly reconciliation | A job that reads the provider's settlement file and compares it with your orders and ledger entries, plus a way to sort what it finds into rule-based fixes, hand fixes and open investigations. |
Estimates
| Quantity | Working | Result | What it sizes |
|---|---|---|---|
Transactions a second from the daily total | 1,000,000 transactions ÷ 86,400 seconds in a day ≈ 11.6 | About 10 a second, steady | The database load: low enough that one relational primary with a standby is the right call, and sharding is not. |
Ledger rows a year | A double-entry ledger writes 2 rows for 1 payment: 1,000,000 × 2 = 2,000,000 rows a day; × 365 = 730,000,000 rows a year | About 730 million ledger rows a year, on top of 365 million payment orders | How much the books grow in a year. Say the row size you assume out loud and multiply; it decides when old entries move to cheaper storage, not whether one database can take the writes. |
Payments left in flight after a day without webhooks | 1,000,000 transactions a day × 1 silent day = 1,000,000 orders with no final status | About a million pending orders to resolve | The work a status poller must do when the provider's callbacks stop: about 10 status calls a second to clear a day's backlog in a day. |
Alternative load for a processor serving many merchants | 10,000 peak transactions a second ÷ 10 a second for the store ≈ 1,000 | About a thousand times the store's rate | Why the same question for a processor rather than a store does need partitioning, and why this guide's single-database answer stops being right there. |
Core entities
| Entity | What it holds |
|---|---|
Payment event | One checkout. It groups the payment orders the buyer pays for in one go and records whether the whole thing is done. |
Payment order | One charge to one seller, and the unit that is made idempotent: its id is unique here and is the key the provider sees. |
Ledger entry | One side of a money movement. Each payment writes a matching pair, so the entries for any transaction sum to zero. |
Wallet | A seller's current balance, a cached view of their ledger entries that payouts read. |
Provider event | A webhook the provider delivered, kept so a second delivery of the same event is recognized and ignored. |
The API
| Endpoint | Notes |
|---|---|
| Creates the payment event and its orders. The key is a random UUID the client makes once per checkout attempt; a repeat with the same key gets the stored result, and a repeat with the same key but a different body is rejected with an error, the way the provider's own idempotency layer treats mismatched parameters. Each order's amount is a string or a count of minor units, not a float. Returns pending at once; the final result arrives later. |
| Reads the order's status from the primary database, not a replica, so a buyer who refreshes right after paying sees the write. Returns pending, success or failed. |
| Verify the provider's signature, then in one database transaction insert the event id into the provider-events table and update the order's status, so a duplicate insert means the event's effects were committed already. Answer with HTTP 200 quickly. Heavier work, such as the ledger and wallet updates, goes onto the queue rather than into this request. |
The high-level design
Step 1 of 3
The pay-in path, with the order id as the key
Start with the happy path. The client sends POST /v1/payments with an idempotency key. The payment service stores the payment event and each payment order in one relational database, with the order id as primary key. The payment executor picks up each order, marks it EXECUTING in that same database, and asks the provider to charge the card, passing the payment order id as the provider's idempotency key. About 10 transactions a second is, as Alex Xu's notes put it, not a high rate for a database, so nothing here is sharded; a standby replica covers failover. The weakness: the executor has no path for a result that arrives after the call returns, and the ledger and wallet don't exist yet.
What breaks first
The deep dives
Never charging twice. The buyer clicks pay twice, and separately your call to the provider times out with no answer. Walk one retried payment through the design and say where each duplicate is stopped, and what state the order is in at each step.
Slow and failed payments. Some payments take hours, because a review is pending or the bank wants an extra authentication step, and some fail outright. What does the buyer see, where does a failing order end up, and how does the ledger keep up when the result finally arrives?
Reconciliation and consistency. Each morning the books must show that your ledger agrees with what the provider settled and with each seller's wallet. How do you check that, what happens to a mismatch you can't fix automatically, and what does a buyer see who reads their status off a replica a moment after paying?
A concept that helps here: Reconciliation against an external system
A concept that helps here: Event sourcing and ledgersA concept that helps here: Replication and read replicasConcepts this guide uses
Sources
- Alex Xu, System Design Interview volume 2, chapter 27: Payment System (notes by Preslav Mihaylov)
- Stripe API reference: Idempotent requests
- Stripe documentation: Receive Stripe events in your webhook endpoint
- Stripe documentation: Authenticate with 3D Secure
- Stripe documentation: Payout reconciliation report
- Amazon SQS Developer Guide: Using dead-letter queues in Amazon SQS
- CockroachDB documentation: Transactions
- PostgreSQL documentation: Log-Shipping Standby Servers
- Wikipedia: Double-entry bookkeeping