System Design: Payment Processing System

System Design: Payment Processing System A capstone system design walkthrough — designing a payment processing system end to end — covering the core domain model, the ledger as the system's source of truth, idempotency and exactly-once-effect guarantees, integrating with external payment gateways and card networks, handling asynchronous webhooks, reconciliation, fraud and risk checks, and the specific correctness and compliance demands that make payments a uniquely unforgiving system design problem. Table of Contents Introduction Why Payment Systems Are a Different Kind of Hard The Core Domain Model The Ledger: Double-Entry Bookkeeping as the Source of Truth Idempotency: The Single Most Important Property Integrating with Payment Gateways and Card Networks The Payment State Machine Webhooks: Handling Asynchronous Gateway Callbacks The Saga: Coordinating Payment Across Multiple Services Reconciliation Fraud and Risk Checks Data Security and Compliance Consistency, Availability, and the CAP Trade-off for Money Scaling the System Observability for a Payment System Common Pitfalls Quick Reference Table Conclusion Introduction A payment processing system takes the general system design vocabulary covered in this series' System Design guide — databases, caching, queues, load balancing — and applies it to a domain where the ordinary consequences of a bug are dramatically higher: a double-charged customer, a lost payment, or a corrupted ledger isn't a degraded user experience, it's real money moved incorrectly, sometimes irreversibly. This guide walks through designing such a system end to end, drawing directly on this series' DDD, Event-Driven Architecture, Database Migrations, and Secret Management guides, each of which turns out to be load-bearing infrastructure for getting payments right rather than optional architectural polish. Client → Payment API → [validate, risk-check] → Payment Gateway (Stripe/Adyen/etc.) → Card Network → Bank ↓ ↓ (async webhook) Ledger (source o