Payment System Architecture
Payment system flow through durable events, idempotent execution, ledgers, and settlement.
A payment system does much more than call a payment service provider and wait for success. It has to preserve a trustworthy internal record while talking to external systems that respond asynchronously, fail intermittently, and settle money on a different timeline from the user interface.
A typical flow begins when the customer clicks Buy. The application creates a payment event and stores it durably before contacting any external provider. That first write matters because retries, timeouts, and webhook callbacks are normal in payments. If the system cannot prove what it attempted, it cannot reconcile later.
Many checkouts contain more than one payment order. A marketplace basket might include several sellers, shipping fees, platform fees, or split payment methods. The payment service therefore decomposes the customer action into one or more executable orders. A payment executor then handles each order's interaction with the external PSP, card processor, or bank-facing API.
That executor layer needs strong idempotency. External calls may succeed while the network response is lost, or the PSP may retry a callback. The internal system must be able to answer, "have we already processed this payment order?" without double-charging or double-crediting anyone. This is why payment systems usually rely on immutable event records, unique payment identifiers, and careful state machines rather than simple boolean success flags.
Once an external payment is authorised or captured, the internal money model still is not complete. The platform needs a wallet or balance service to track how much value belongs to each seller, merchant, or internal account. This balance is often product-visible before bank settlement is final, which is why reserve policies and pending states exist.
A separate ledger service is equally important. Wallet balances are mutable summaries. Ledgers are append-only records of why balances changed. In finance systems, you want both. The balance tells you the current state. The ledger lets you reconstruct history, audit disputes, and verify that every debit has a corresponding credit according to the platform's accounting rules.
Settlement usually happens later through files or reports from PSPs and banks. These reports confirm what actually moved at the banking layer during the day. Reconciliation jobs compare those records against internal payment orders, wallet updates, and ledger entries. If anything disagrees, the system needs a controlled path for investigation and repair.
The most important design insight is that a payment system has several truths operating at once: the customer-facing checkout state, the PSP state, the platform wallet state, the internal ledger state, and the final bank settlement state. Building for reliability means accepting that these truths converge asynchronously. Good payment architecture is therefore about durable intent, idempotent execution, clear accounting, and relentless reconciliation.