Design Stripe / Payments
Reliable, double-entry payment ledger with strictly idempotent transaction processors and APIs.
1. System Requirements
- Accept customer payments and process them via third-party bank gateways.
- Maintain a transaction ledger tracking account balances.
- Support refund requests and payment status query checks.
- Strict transaction safety (ACID compliance).
- Strict idempotency (guaranteeing payments are never processed twice).
- High durability (zero financial transaction loss).
2. Scale & Resource Estimates
Throughput: 10 Million transactions/day = ~115 transactions/sec average. Peak load = 1,000 transactions/sec.
Storage & RAM: Double-entry ledger lines require ~100 GB database storage per year, highly secured.
3. System API Endpoints
POST /api/v1/payments/charge
Headers: { Idempotency-Key: "idemp-abc-9923" }
Request: { amount: 5000, currency: "USD", payment_method: "pm_card..." }
Response: { charge_id: "ch_9012", status: "succeeded" }4. Database Schema Design
Table: idempotency_keys (Redis / MySQL)
- idempotency_key (VARCHAR - Primary Key)
- response_payload (JSONB)
- expires_at (TIMESTAMP)
Table: accounts_ledger (PostgreSQL - ACID transactional ledger)
- entry_id (BIGINT - Primary Key)
- transaction_id (UUID)
- account_id (UUID)
- type (ENUM: debit, credit)
- amount (NUMERIC)5. Interactive High-Level Architecture
6. Scalability Deep Dive & Bottlenecks
Enforces double-entry bookkeeping and strict idempotency. If a request contains an `Idempotency-Key` that is already in Redis, the gateway returns the cached response instead of retrying the payment. Transactions write debits and credits as separate rows in PostgreSQL in a single database transaction. This prevents data updates (`UPDATE balance = balance - X`) and ensures mathematical reconciliation.
7. Production Scaling Strategies
Idempotency Layer: Every payment request requires an Idempotency-Key header. The key is stored in Redis with a 24-hour TTL. Duplicate requests return the cached response. This makes retries safe — critical when networks are unreliable.
Payment Processing Pipeline: Charges flow through: API gateway → fraud detection (ML model, <100ms) → payment processor (Visa/Mastercard network) → ledger write. Each stage is idempotent. Failed stages retry with exponential backoff (max 3 attempts).
Ledger Sharding: Shard the ledger database by merchant_id (hash mod 64). Each shard handles ~$1B in daily transaction volume. Use PostgreSQL with serializable isolation for ACID guarantees. Cross-shard transfers use distributed saga pattern.
Webhook Delivery: Payment events (charge.succeeded, refund.created) are delivered via webhooks. Retry with exponential backoff (1s, 5s, 30s, 5m, 1h) for failed deliveries. Store webhook events in Kafka for at-least-once delivery guarantee. Merchants can replay events.
Fraud Detection ML: Real-time scoring on every transaction using a gradient-boosted model. Features: transaction velocity, geo-distance from last purchase, device fingerprint, amount deviation from baseline. Scores >0.8 trigger 3D Secure challenge. Model retrained daily on labeled fraud data.
PCI Compliance Architecture: Cardholder data isolated in a PCI-scoped 'vault' service with hardware security modules (HSMs). Tokens replace card numbers in all other services. Vault has its own network segment, audit logs, and key rotation. Zero raw card data flows outside the vault.
8. Runnable Production Starter Code
Scaffold