Design a payment system: ledgers, webhooks, and idempotency
Payment
Guided ModeStep 1 β The Naive Design (And Why It Fails)
Request Flow
Client sends charge request
The client POSTs to the API Server with amount, currency, and a payment method token (e.g., a Stripe card token). The API validates the request, then synchronously writes to the database.
Network timeout between API and DB
The API writes the charge to the database. The database commits β but the TCP ACK is lost in transit. The API times out assuming failure and returns a 500 to the client.
Client retries β duplicate charge
The client sees a 500 and retries the request. The API inserts another charge record. Now the user has been charged twice. This is the most common payment bug in naive systems.
Why We Need This
This is not a theoretical edge case. On typical mobile networks, 1β3% of requests experience a network interruption at the worst possible moment. At 10,000 transactions/day, that's 100β300 potential duplicate charges daily.
Key Insight
A naive insert-on-POST design cannot distinguish a retry from a new request. Fix: every charge request must carry a client-generated idempotency key.
Step 1 of 7
