Payment Systems & Financial Consistency

Payment systems have a unique constraint that sets them apart from every other distributed system you will design: correctness above all else. A double charge erodes customer trust. A missed refund creates legal liability. An inconsistent ledger fails an audit. While most systems optimize for availability or performance and tolerate occasional inconsistency, financial systems must be exactly right -- every transaction must be accounted for, every state transition must be valid, and every failure must be handled without losing or duplicating money.

Let us walk through the core patterns that make this possible.

The Payment Flow#

Before diving into the safeguards, it helps to see the happy path. When a customer clicks "Pay," the request travels through several services before money actually moves.

The Client sends a payment request to your Payment Service, which validates the request and records it in the ledger database. It then forwards the authorization request to a Payment Gateway (Stripe, Adyen, etc.), which communicates with the customer's Bank. Confirmations flow back through each layer until the client receives a receipt.

The critical detail here is that every step is recorded. If the gateway times out after sending the charge to the bank, your system knows the payment is in an authorized state and can query the gateway later to find out what happened. Nothing is lost in the void.

The Payment State Machine#

A payment is not just "paid" or "not paid." It moves through a well-defined set of states, and only specific transitions are allowed. This is the backbone of correctness in any payment system.

The happy path is Created to Authorized to Captured to Settled. But from any pre-settlement state, the payment can transition to Failed (the bank declines it). And from Captured or Settled, it can transition to Refunded (the merchant returns the money).

The state machine prevents invalid transitions -- you cannot refund a payment that was never captured, and you cannot capture a payment that was never authorized. Every transition is recorded as an immutable event, creating a complete audit trail of the payment's lifecycle.

Why separate authorization from capture? Because many businesses need the gap. A hotel authorizes your card at check-in (reserving the funds) but only captures the final amount at checkout. An e-commerce site authorizes at order time but captures only when the item ships. This two-phase approach is not just a nice-to-have -- it is how the card networks actually work.