System Design

Payment Processing

Design a payment processing system like Stripe.

Functional requirements

• Merchants can create a charge (amount, currency, payment method token) via an API and receive a payment intent with a status (pending, succeeded, failed).
• The system authorizes and captures funds by calling an external card network / bank processor (PSP) on the merchant's behalf.
• Merchants can retrieve the current status of any payment and receive asynchronous webhooks when a payment's status changes.
• The system maintains an internal ledger of all money movements (charges, fees, merchant balances) that supports merchant payouts and balance queries.
• Merchants can issue full or partial refunds against a succeeded payment.

Non-functional requirements

• Correctness over availability for money movement: no double charges, no lost payments, and the ledger must always balance. It is acceptable to reject/queue new charge requests during a partition rather than risk inconsistency.
• A customer must never be charged twice for a single logical purchase, even under client retries, network timeouts, or partial failures mid-request.
• p99 latency for charge creation is 2s or less (dominated by the external processor call); status reads 100ms or less.
• Payment and ledger records are durable for 7+ years (regulatory); no acknowledged write may ever be lost.
• All card data handling is PCI-DSS compliant: raw PANs are tokenized at the edge and never stored in the core payment or ledger services.

Scaling & constraints

• 500,000 active merchants; peak of ~10,000 charge attempts per second during sales events (e.g., Black Friday), ~1,000/sec average.
• Read:write ratio of roughly 20:1 (status polls, dashboard queries, balance lookups vs. charge/refund creation).
• Each payment record is ~2 KB; each ledger entry ~500 bytes; a typical charge produces 4-8 ledger entries.
• The external card processor has p50 latency of 300ms, p99 of 3s, an occasional timeout rate of ~0.5%, and its responses can be lost after it has actually captured funds.
• Payment and ledger data retained for 7 years; volume grows ~40% year over year.
• Webhook delivery to merchant endpoints must tolerate merchant downtime of hours.

Out of scope

• Fraud detection / risk scoring models.
• Currency conversion and FX rate management.
• Merchant onboarding, KYC, and compliance workflows.
• Checkout UI / client-side SDKs (assume card details are already tokenized at the edge).