Design a Payment System Interview Guide: Idempotency Keys, Double-Entry Ledgers & Retries
A Staff-level walkthrough of payment processing interviews at Stripe, Amazon, Coinbase, and Uber: preventing double charges, state machines, and PSP webhook reconciliation.
- Network timeouts are ambiguous: the client cannot tell whether the server crashed before charging or after charging.
- Client-generated UUIDv4/v7 idempotency keys enforced by a database UNIQUE constraint turn at-least-once network retries into exactly-once business execution.
- Never store mutable account balances alone—use an immutable append-only double-entry ledger where sum(debits) == sum(credits) == 0.
- Run nightly asynchronous reconciliation between internal ledger entries and external PSP settlement files to catch dropped webhooks.
1. Why Retries Cause Double Charges Without Idempotency
When a mobile app calls POST /v1/payments and experiences a 5-second socket timeout, the HTTP request may have already succeeded at the Payment Service Provider (PSP). If the client blindly submits a fresh payment request, the customer is charged twice.
To guarantee exactly-once charge semantics over an unreliable network, the client generates an Idempotency-Key when rendering the checkout screen and reuses that exact key across every retry of the same purchase intent.
| Idempotency Table State | Incoming Retry Behavior | HTTP Response |
|---|---|---|
| No row exists | Insert row with status=IN_PROGRESS in ACID tx and dispatch PSP call | Proceed to execution |
| status = COMPLETED | Short-circuit immediately without calling PSP | 200 OK with stored response snapshot |
| status = IN_PROGRESS (fresh lease) | Concurrent duplicate in flight; do not launch second PSP call | 409 Conflict / Retry-After |
| status = FAILED (retryable PSP 5xx) | Acquire new lease version and retry PSP with same provider key | 200 OK or terminal error |
2. Immutable Double-Entry Ledger Schema
Updating UPDATE wallets SET balance = balance - 2400 loses auditability and hides silent corruption. Production fintech systems record every money movement as two balanced immutable ledger postings inside one serializable transaction: debit buyer_receivable (-2400 cents) and credit merchant_payable (+2400 cents).
Frequently Asked Questions
Combine push webhooks with a background polling worker for intents stuck in PROCESSING beyond N minutes, plus daily batch reconciliation against the PSP's settlement CSV/parquet report.
Related Video Courses & Python 3.14 Workspaces
Drill every problem and architecture diagram from this guide inside Crush the FAANG Interview: