Design an Idempotent Payment Processing & Financial Ledger (Stripe)
A resilient financial payments architecture guarantees strict consistency (CP system) using cryptographic idempotency reservation, double-entry balanced postings, and sharded balance locks.
Live Architecture Studio
Edit components, modify labels, add databases, or redraw connections directly on this canvas:
Loading Stripe Payments Ledger Blueprint...
Mounting vector diagram elements, nodes, and capacity metrics
Loading Stripe Payments Ledger Blueprint...
Mounting vector diagram elements, nodes, and capacity metrics
1. Problem & Challenge
When a mobile user clicks "Pay $50" and their connection drops mid-flight, retrying must never double-charge their credit card or credit the merchant twice. The system requires atomic idempotency checks and immutable accounting entries.
2. Core Building Blocks & Responsibilities
👉 Desliza la tabla para ver roles y responsabilidades| Component | Role | Plain-English Explanation |
|---|---|---|
| Idempotency Layer | Duplicate Charge Blocker | Inspects the Idempotency-Key header and computes SHA-256 payload hash. If already completed, returns cached result without re-executing. |
| Payment State Machine (Temporal) | Orchestrator | Manages step-by-step transaction state: Created -> Authorizing -> Authorized -> Capturing -> Settled with compensating rollback sagas. |
| Double-Entry Accounting Ledger | Immutable Financial Truth | Enforces mathematical invariant: Sum of Debits = Sum of Credits. Entries are append-only; updates and deletes are cryptographically revoked. |
| Sharded Balance Buckets | Contention Breaker | Splits high-volume merchant balances into 100 sub-accounts in PostgreSQL to prevent row-locking thrashing during sales bursts. |
| Transactional Outbox & CDC | Event Publisher | Writes outbox events in the same ACID transaction as the ledger, using Debezium CDC to stream verified events to Kafka. |
3. Step-by-Step Request Flow
POST with Idempotency Key
Client sends payment request with unique Idempotency-Key UUID in header.
Atomic DB Reservation
An atomic INSERT ... ON CONFLICT locks the key. If key exists and completed, cached response returns instantly.
Execute Banking Rail Call
Invokes card network asynchronously, tracking transaction state with a distributed saga.
Commit Balanced Ledger Entry
Writes balanced debit/credit lines into immutable ledger tables and updates outbox event table.
4. Architectural Trade-offs
Strict Consistency (CP) vs High Availability (AP)
Chosen: Strict CP System
Rationale: Financial ledgers can never run in eventually consistent AP mode. If network partitions occur, writes must fail rather than risk double spending or false balances.
In-Transaction Bank API Calls vs Async Decoupling
Chosen: Async Out-of-Transaction Bank Calls
Rationale: Holding an open database transaction lock while waiting 2 seconds for a credit card network response exhausts database connection pools and causes database collapse.
Interview Tip
Always mention Idempotency Payload Tampering: what happens if an attacker re-uses an existing key with a different charge amount? Validate that stored request hash matches incoming payload hash, returning HTTP 400 on mismatch.
Explore Related System Blueprints
TinyURL Shortener
A URL shortener converts a long link (like a 100-character article URL) into a compact 7-character key (like tinyurl.com/xyz123) and redirects visitors in under 15 milliseconds.
API Rate Limiter
A rate limiter acts as a digital bouncer at the door of your API, ensuring each client stays within their allowed request limits (e.g. 100 requests per minute) and blocking abusive traffic.
Video Streaming CDN
Streaming high-definition video to millions of smart TVs and mobile phones requires breaking large 10GB video files into tiny 5-second chunks, encoding each into 20 different resolutions, and caching them right inside local ISP networks.
Uber Dispatch Engine
A real-time geospatial dispatch system matches riders with the most optimal nearby drivers using 64-bit H3 hexagonal indexing and 2-second batch optimization, minimizing city-wide pickup ETA and driver idle time.
Figma Multiplayer Engine
A real-time multiplayer document engine uses stateful sticky session routing and server-authoritative operational ordering to sync 2D scene graphs across worldwide collaborators without locking.
Twitter Timeline & Feed
A timeline generation system balances high write amplification against fast sub-50ms reads by pushing tweets to followers of regular accounts, while pulling and merging celebrity tweets on-demand.