Payment State Machine

A payment state machine is the part of a payment system that defines, precisely, which statuses a payment can be in and which changes from one status to another are allowed. At any moment a payment is in exactly one state, such as authorized or settled. It moves to another state only when a defined event occurs, such as a capture request or a decline from the bank, and only if the rules permit that move from its current state.

The idea comes from the finite-state machine of computer science. Payment companies use it because a payment is not a single action but a process spread across several systems and, often, several days, as described under payment lifecycle. Without an explicit model, different parts of a system can hold conflicting views of where a payment stands, and money can be sent twice or not at all.

A simplified card payment might have the following states: created, when the merchant has registered the intent to charge; requires action, while the cardholder completes authentication; authorized, once the issuer has approved; captured, when the merchant has confirmed the charge; settled, when funds have been received; and the terminal states failed, cancelled and refunded. The payment status shown to a merchant or customer is usually a simplified view of these internal states.

The transitions are as important as the states. An authorized payment can move to captured or be cancelled by a void transaction; it cannot jump to refunded, because nothing has been collected. A failed payment cannot become settled. A settled payment can be refunded but not voided. Writing these rules down as a table or diagram means that any request that does not correspond to a permitted transition is rejected instead of being processed with unpredictable results.

Each transition has side effects attached: posting entries to the double-entry ledger, sending a webhook notification to the merchant, releasing a hold, or starting a payout. Tying these actions to transitions ensures they happen once, at the right moment.

Payment systems receive information out of order, late and more than once. A network timeout may leave it unknown whether the acquirer approved a charge. A bank may report a payout as failed after having reported it as sent. A merchant may retry a capture request because the first response was lost. A state machine gives a consistent answer in each case.

Duplicates are handled by checking the current state: a second capture request for a payment already captured returns the existing result and changes nothing, which is the behaviour required for idempotency. Out-of-order events are either ignored, if they describe a state the payment has already passed, or parked until the missing event arrives. Uncertain outcomes are given a state of their own, commonly called unknown or processing, which triggers an enquiry to the downstream party instead of a guess. To prevent two processes from changing the same payment simultaneously, the update is made conditional on the state not having changed since it was read.

Card authorizations return an answer in seconds, but many methods do not. For an asynchronous payment such as a bank transfer, direct debit or cash voucher, the payment may remain in pending status for days before reaching settled status or failed status. Direct debits add a further complication: a payment reported as successful can later be returned, so the model needs a transition out of what looks like a final state.

Partial operations also need representing. A partial capture or partial refund leaves a payment partly in one condition and partly in another. Designs deal with this either by adding states such as partially refunded or, more robustly, by modelling captures, refunds and disputes as separate objects, each with its own small state machine, linked to the parent payment.

A well-built implementation never overwrites the state silently. Every transition is stored as a record with the previous state, the new state, the event that caused it, a timestamp and the actor, forming an audit trail from which the history of any payment can be reconstructed. This serves customer support, dispute handling, regulatory examination and debugging.

Operations teams monitor how long payments spend in each non-final state. A payment that has been authorized but not captured for a week, or a payout stuck in processing beyond the rail's normal time, signals a fault or a lost message, and automated jobs sweep for such cases and either resolve them by querying the counterparty or raise them for manual handling. A mismatch between the state machine and the ledger or the bank statement appears as a reconciliation break.

Too few states hide information: a single pending state that covers awaiting customer action, awaiting bank response and under fraud review is of little use to support staff. Too many make the model hard to reason about and to change, since integrations by merchants depend on the published states. Providers therefore tend to keep a small, stable set of public states and a finer internal set. In systems built on a message queue, the state machine is what turns a stream of loosely ordered events into a dependable record.