Loading…

The decisions that matter

Record money as balanced entries, written by one ledger service.Every balance can be explained, and money can’t appear from nowhere.
One key per payment, unique in the database.Retries and double taps get the first result instead of paying twice.
Check and debit a wallet in one conditional update.Two checkouts at once can’t both spend the same credit.
Write the payment before calling the PSP; a timeout means ask.A payment is never guessed when the PSP goes quiet, only looked up.
Match the ledger to the PSPs and the bank every day.Differences show up the next morning, with someone to fix them.

Architecture diagramThe final design at a glance

Checkout and a payment service in front of the PSPs, one ledger service that alone writes entries, daily payouts, and daily matching of our entries against the PSPs’ settlement reports and the bank’s statements. Dashed lines are asynchronous.

Diagram as text

Components: Buyer's app (Client); Checkout (Service); Payment service (Service); PSPs (External API); Ledger service (Service); Payout job (daily) (Worker); Ledger DB (Postgres) (SQL DB); Daily reconciliation (Worker); Bank (External API); Finance reporting (Analytics). Connections: Buyer's app → Checkout (pay for an order); Checkout → Payment service (create payment, key); Payment service → PSPs (authorise, capture, refund); PSPs → Payment service (notifications), asynchronous; Payment service → Ledger service (post entries); Ledger service → Ledger DB (Postgres) (balanced transactions); Payout job (daily) → Ledger service (record payouts first); Payout job (daily) → Bank (transfers, payout ids); Ledger DB (Postgres) → Daily reconciliation (our entries), asynchronous; Ledger DB (Postgres) → Finance reporting (change data capture), asynchronous; PSPs → Daily reconciliation, asynchronous; Bank → Daily reconciliation (statements), asynchronous.

Understanding the problem

A marketplace payment system takes buyers’ money by card or wallet, keeps a fee, and pays sellers the rest daily. The money passes through two PSPs and a bank, which keep their own books. So the design is about charging each payment once, accounting for every cent, and proving each balance years later.

The practice brief states the requirements up front; in an interview you would confirm them in the first few minutes. The core is the money path: pay, capture, refund, pay out, and prove it.

Functional requirements

CoreBuyers pay for an order by card, from their wallet credit, or both; the money is taken when the order ships.
CoreSellers can refund part or all of a payment, and disputes from buyers’ banks are handled.
CoreSellers see what they are owed and why, and are paid it daily to their bank account.
CoreFinance can explain every balance, and every cent the PSPs and the bank moved.
Below the lineSubscriptions and payment plans.
Below the lineBuyer-to-buyer transfers.
Below the lineInvoices and tax documents.
Below the lineFraud scoring and identity checks.Separate systems that decide whether to accept a payment, not how to record it.
Below the lineCross-border payouts with live exchange rates.A conversion is an ordinary transaction through exchange accounts; quoting rates is its own problem.

Non-functional requirements

ConsistencyA buyer is never charged twice for one payment, however often a request is repeated.
ConsistencyMoney is never created or lost, and any balance can be explained from its history.
ConsistencyA wallet never goes below zero, even when two purchases happen at the same moment.
LatencyThe ledger records a movement within about 50 ms (p99).
AvailabilityCheckout is 99.95% available; the ledger refuses a payment rather than record it wrongly.
SecurityThe platform handles card numbers as little as possible, and only the services that need to can move money.

Scale

From the briefNumbers here are given in the practice brief.

ScaleAbout 50M buyers and 2M sellers.
ScaleAbout 20M payments a day, peaking around 2,000 a second in sales events.
ScaleAbout 20,000 balance reads a second.
ScaleTwo PSPs; each deposits once a day, net of its fees, and reports the next day.
ScaleSeveral currencies; sellers are paid in their own.

Out of scope

Out of scopeFraud scoring.
Out of scopeIdentity checks (KYC).
Out of scopeThe card networks themselves.
Out of scopeTax calculation.

Check yourself

Fraud scoring is out of scope. Why is it safe to leave it out of this design?
Show answerHide answer
Fraud scoring decides whether to accept a payment. An accepted payment then takes the same path either way, so the keys, the ledger and the matching don’t change.

The numbers that shape the design

Illustrative exampleNumbers here are illustrative: round figures to reason with, not measurements.

Work out only the numbers the ledger depends on, with round figures. The surprise is how many entries one payment writes, and that the records are kept for years.

Back of the envelope at the peak

Quantity	Value	Working
Payments	About 2,000 a second	From the brief; the daily average is 20M ÷ 86,400, about 230 a second.
Ledger entries	About 8,000 a second	About 4 per captured sale (the PSP, its fee, the seller, our fee), before refunds and payouts.
Balance reads	About 20,000 a second	From the brief: wallet checks at checkout and seller pages.
Entries a day	About 100M	About 5 per payment over its life, times 20M payments.
Storage a year	About 7 TB	100M entries × about 200 bytes × 365, before copies and indexes.
Daily payout run	Up to 2M payouts	Every seller with money owed, once a day.

What the numbers tell you

The ledger’s write load is several times the payment rate, and every write must be durable before a payment succeeds.
Balance reads are the heaviest traffic, and the few that allow a spend must read the primary.
The payout run lands as one burst on the same ledger, so schedule and pace it.

Architecture diagramWhere the peak lands

Try it: The numbers that shape the designGuided practice · Payments ledger, Marketplace payments · Senior

Check yourself

Which number would you size the ledger database for?
Show answerHide answer
The entry write rate at the peak, several times the payment rate, plus headroom for the payout run. The payment count alone underestimates it.

Core entities: the ledger

Illustrative exampleNumbers here are illustrative: round figures to reason with, not measurements.

The ledger records money, not payments. Every movement is one transaction of entries, each with an account, a direction and an amount as an integer in the currency’s smallest unit, plus the currency. A transaction’s debits equal its credits in each currency, checked before it is written, and a mistake is fixed by a new transaction, not by editing an old one.

Money from outside moves through accounts of its own: what the PSP owes us, our bank account, fee revenue and PSP fee expense. Balances come from the entries: summed, or kept as a running total updated in the same atomic write and rebuildable from them, which makes a fast wallet check possible.

The entities and their key fields

Entity	Key fields	Why it exists
Account	`id`, owner, type, currency	A wallet, a seller’s payable, or one of the platform’s own accounts.
Transaction	`id`, kind, `payment_id`, `effective_at`	One movement of money: the unit that must balance.
Entry	`transaction_id`, `account_id`, direction, amount, currency	The record itself, left alone once written.
Balance	`account_id`, amount, `last_entry_id`, version	A running total written with its entries; rebuildable.
Payment	`id`, `order_id`, amounts, status	The card or wallet payment and its calls to the PSP.
Refund, dispute	`payment_id`, amount, status	Records of their own, so they can’t overwrite each other.

An illustrative $100.00 sale, in cents

Account	Debit	Credit
PSP receivable	9,700	–
PSP fee expense	300	–
Seller payable	–	8,500
Fee revenue	–	1,500
Total	10,000	10,000

Architecture diagramOne sale, one balanced transaction

Read:Learn: Data model design Learn: PostgreSQL

Try it: What the ledger recordsGuided practice · Payments ledger, Marketplace payments · Senior

Keep reading+1 min

Money as integers

Floating-point types can’t represent most decimal fractions exactly, so totals drift (PostgreSQL docs (opens in a new tab)). Store integers in each currency’s smallest unit, or an exact decimal type at the currency’s scale. Currencies differ in their minor unit, for example a hundredth or a thousandth (ISO 4217 (opens in a new tab)), so look the scale up per currency rather than assuming two decimals. Apply one rounding rule to the fee, once, and give the seller the rest, so the parts add up.

Check yourself

The API

Make the payment a resource you can look up at any time, because its outcome isn’t always known when the call returns. Taking the money and giving it back are their own calls, each with its own key, and amounts are integers with their currency everywhere.

From paying to a seller’s statement

Call	Request	Response	Errors
`POST /v1/payments`	`order_id`, amount, currency, funding (wallet and/or card token), key	`201` with the payment and its status	`402` declined; `422` not enough credit; `409` key reused with a different body
`GET /v1/payments/{id}`	None	The payment with its captures, refunds and disputes	`404`
`POST /v1/payments/{id}/capture`	amount, key	The capture and its status	`409` if it can no longer be captured
`POST /v1/payments/{id}/refunds`	amount, reason, key	The refund and its status	`422` if more than is refundable
`GET /v1/sellers/{id}/balance`	currency	Available, and on its way	None
`GET /v1/sellers/{id}/entries`	from, to, cursor	The statement that explains the balance	None

Read:Learn: API contract design Learn: Idempotency and retries

Try it: The APIGuided practice · Payments ledger, Marketplace payments · Senior

Check yourself

Why return 201 with a status, instead of waiting until the PSP answers?
Show answerHide answer
The PSP may take seconds or minutes. The app gets the payment’s id at once and can show "confirming", then read the status or be told when it changes.

High-level design

Build the design one flow at a time. Each step adds only what that flow needs; the deep dives then harden the parts an interviewer pushes on.

Pay at checkout

The card number goes from the buyer’s device straight to the PSP’s own form, so our servers see only a token. The payment is recorded before the PSP is called, and the card is authorised, not charged. Nothing reaches the ledger yet, because no money has moved.

The buyer types card details into the PSP’s hosted form; the app gets a token back.
The app places the order with the token, and checkout asks the payment service to pay for it.
The payment service records the payment, pending, with its key, then asks the PSP to authorise the card.
When the PSP confirms, checkout accepts the order. A wallet part, if any, is reserved in the same step.

Architecture diagramCheckout: check the card, accept the order

Card details go straight to the PSP, and the payment is written before the PSP is called.

Diagram as text

Components: Buyer's app (Client); Checkout (Service); Payment service (Service); Payments DB (Postgres) (SQL DB); PSP (hosted card form) (External API). Connections: Buyer's app → Checkout (place order + token); Checkout → Payment service (create payment); Payment service → Payments DB (Postgres) (payment + key, pending); Payment service → PSP (hosted card form) (authorise); Buyer's app → PSP (hosted card form) (card details).

Read:Learn: High-level architecture Learn: Auth and sessions

Try it: From checkout to the seller’s bankGuided practice · Payments ledger, Marketplace payments · Senior

Keep reading+1 min

What a hosted form does for card compliance

With the PSP’s hosted form, card numbers stay off your servers, which can shrink how much of the platform the card-security rules reach. Which self-assessment applies depends on the integration, and the acquirer confirms it: a page that embeds the form must still be protected from script attacks (PCI SSC (opens in a new tab)).

Check yourself

Take the money when it ships

Fulfilment tells the payment service an order shipped. Capture is its own PSP call with its own key, and only when the PSP confirms it does the sale reach the ledger, as one balanced transaction written by the ledger service and nothing else.

Orders marks the order shipped and asks the payment service to take the money.
The payment service records the capture, pending, and calls the PSP with the capture’s own id.
The PSP confirms, by reply or by notification.
The ledger service posts the sale: PSP receivable and PSP fee expense against seller payable and fee revenue.

Architecture diagramShipping: take the money, post the sale

Pay sellers every day

Once a day, the payout job pays each seller what the ledger says they are owed. Each payout is recorded before the file goes out and carries its own id to the bank, so a crash or a resent file can be checked rather than paying twice.

The job reads each seller’s available balance from the ledger.
For each seller, the ledger moves the amount from seller payable to payouts in transit, under a payout id.
The job sends the day’s transfers to the bank in one file, one line per recorded payout.
The bank confirms or rejects each transfer: confirmed ones leave the bank account, and rejected ones go back to the seller.

Architecture diagramPaying sellers every day

Design a payment system

The answer in two minutes

Also asked as

What interviewers look for

The decisions that matter

Understanding the problem

Functional requirements

Non-functional requirements

Scale

Out of scope

The numbers that shape the design

Core entities: the ledger

Money as integers

The API

High-level design

Pay at checkout

What a hosted form does for card compliance

Take the money when it ships

Pay sellers every day

Sign in with Google to read the rest

Practise this

The answer in two minutes

Also asked as

What interviewers look for

The decisions that matter

01Understanding the problem

Functional requirements

Non-functional requirements

Scale

Out of scope

02The numbers that shape the design

03Core entities: the ledger

Money as integers

04The API

05High-level design

Pay at checkout

What a hosted form does for card compliance

Take the money when it ships

Pay sellers every day

Sign in with Google to read the rest

12Practise this

Understanding the problem

The numbers that shape the design

Core entities: the ledger

The API

High-level design

Practise this