Skip to content

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
Practice this question

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

AskWhy it mattersA 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.

The requirements menu

RequirementScopeWhy

Pay-in: take money from a buyer by card for one or more sellers

Core

The main flow. One checkout can carry several payment orders, one per seller, which is why the order, not the checkout, is the unit you make idempotent.

Pay-out: send money to sellers, for example monthly

Core

The other half of the money movement. It reads the wallet balance and writes the ledger the same way pay-in does, in the other direction.

Record every money movement in a ledger

Core

The ledger is the source of truth for money. Without it, a balance is a counter nobody can audit.

Keep each seller’s balance in a wallet

Core

Payouts and seller dashboards need a current balance without summing the whole ledger each time.

Show the status of a payment: pending, success or failed

Core

Slow payments make this necessary: the buyer's request returns before the provider has an answer, so there must be a status to read later.

Run a risk check before sending a payment to the provider

Optional

Worth a sentence: the payment service calls a risk provider before charging. Leave the details, since the check is a call to an outside service and doesn't change the rest of the design.

Email the buyer when a pending payment finishes

Optional

Cheap to add once payment results flow through a message queue: one more subscriber. Take it if you need a second consumer to motivate the queue.

A seller dashboard with balance and payout history

Optional

Reads the wallet and the ledger, so it costs little. Leave it unless the interviewer asks what sellers see.

Fail over to a second payment provider when the first is down

Out of scope

Real systems do this, but two providers means two idempotency schemes and two settlement files. Name it and park it.

Disputes and chargebacks

Out of scope

They arrive after the sale as a reversed movement in the settlement file. Say the ledger can record them as a new entry, then move on.

Storing card numbers: a payment provider holds them

Out of scope

Card data on your servers brings a compliance program with it. The provider's hosted page keeps it off your side.

Currency exchange

Out of scope

One currency keeps the ledger simple. Conversion would add rates and rounding rules to each entry.

Refunds and subscriptions

Out of scope

A refund reverses a finished payment, and a subscription schedules future charges; each brings its own states. Both would reuse the same ledger and provider integration, so skipping them loses little in this round.

Bank transfers and other payment methods

Out of scope

Other methods settle on other timelines. Cards are enough to show the slow and failed paths.

Non-functional requirements

RequirementWhat 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

QuantityWorkingResultWhat 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

EntityWhat 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

EndpointNotes

POST /v1/payments { checkout_id, buyer_info, payment_orders[] } with an idempotency-key header

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.

GET /v1/payments/{id} → status of one payment order

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.

POST /webhooks/psp { token, result } ← the payment provider’s callback

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

payeventkeyClientPayment servicePayments DBPayment executorPaymentprovider

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.

payeventkeywebhookdonesettlementClientPayment servicePayments DBPayment executorPaymentproviderMessage queueWalletLedgerReconciliation job
The whole design

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.

A concept that helps here: Idempotency keysA concept that helps here: Delivery semantics: at most, at least, exactly onceA concept that helps here: Transactions and isolation levels

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?

A concept that helps here: Retries and dead-letter queuesA concept that helps here: Queues and logsA concept that helps here: Job scheduling and delayed work

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: Event sourcing and ledgersA concept that helps here: Replication and read replicas

Concepts this guide uses

Sources

  1. Alex Xu, System Design Interview volume 2, chapter 27: Payment System (notes by Preslav Mihaylov)
  2. Stripe API reference: Idempotent requests
  3. Stripe documentation: Receive Stripe events in your webhook endpoint
  4. Stripe documentation: Authenticate with 3D Secure
  5. Stripe documentation: Payout reconciliation report
  6. Amazon SQS Developer Guide: Using dead-letter queues in Amazon SQS
  7. CockroachDB documentation: Transactions
  8. PostgreSQL documentation: Log-Shipping Standby Servers
  9. Wikipedia: Double-entry bookkeeping
Sign in to report a mistake