Design a payment system
Process payments reliably: charge customers, record every money movement, and never lose money or charge twice.
Why interviewers ask it
It tests correctness under failure — retries, timeouts, idempotency, transactions and audit trails — where a small bug means real money.
Functional requirements
- Accept a payment for an order through a payment provider (PSP) that talks to the card networks.
- Record every money movement in a ledger.
- Refunds; reconciliation with the provider's reports.
Non-functional requirements
- Correctness over speed: no double charges, no lost money.
- Strong consistency and a full audit trail.
- Secure (PCI DSS rules for card data) and highly available.
From version 1 to the final design
- Version 1: call the payment provider and mark the order 'paid'.
- Version 2: a payments table with statuses and idempotency keys.
- Version 3: a double-entry ledger, written in the same transaction as the status change.
- Version 4: webhooks, an outbox, reconciliation, and handling results that are unknown.
The design, step by step
- The payment service receives the request with an idempotency key; a unique constraint in the database blocks duplicates.
- It creates a PENDING payment record, then calls the payment provider. The provider handles the card details, so you never store raw card numbers.
- The provider's result (response or webhook) updates the status, and balanced double-entry ledger rows are written in the same transaction.
- The order service is told through an outbox event.
- A nightly reconciliation job compares the ledger with the provider's settlement files.
Deep dives
- Idempotency keys plus unique constraints make every retry safe.
- Double-entry ledger: every movement is a debit and an equal credit; balances are sums; entries are never edited, only added (corrections are new entries).
- Provider timeout: the result is unknown, so retry with the same idempotency key or ask the provider for the status before doing anything else.
- Store money as whole minor units (pence) together with the currency.
Common mistakes
- Retrying a timed-out charge with a brand-new request.
- Storing money as floats: 0.1 + 0.2 is not exactly 0.3, so totals drift. Use whole pence (integers).
- Updating balances in place, with no ledger history.
Not true: When a charge times out, the safe move is to send a brand-new charge request.
In fact: The first charge may have gone through, so a new request could charge the customer twice. Retry with the same idempotency key, or ask the provider for the status.
In the interview
Correctness first. Every payment request carries an idempotency key enforced by a unique constraint. The payment service records a pending payment, then calls the payment provider. The provider holds the card data, so we never store card numbers. On the result, the service writes balanced double-entry ledger rows in one ACID transaction. Events go out through an outbox, and daily reconciliation against the provider catches any mismatch.
Part of Unit 8: High-level design questions in the free System Design course.