# 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.

- **Author:** Former Amazon Software Engineer (Crush the FAANG Interview)
- **Category:** Architecture Case Studies
- **Updated:** 2026-11-20
- **Canonical URL:** https://crushthefaanginterview.com/blog/design-a-payment-system-idempotency-double-entry-ledger

## Key Takeaways
- 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

### How do you handle dropped webhooks from Stripe or Adyen?

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 & Interactive Courses
- [Design a Payment System](https://crushthefaanginterview.com/course/sd-41-design-a-payment-system)
- [Unique ID Sequencer](https://crushthefaanginterview.com/course/sd-12-sequencer)
- [Distributed Messaging Queue](https://crushthefaanginterview.com/course/sd-17-distributed-messaging-queue)
- [Lessons from System Failures](https://crushthefaanginterview.com/course/sd-49-lessons-from-system-failures)
