Why a state machine
A payment passes through distinct phases like pending, authorized, captured, and failed. Modeling these as an explicit state machine makes illegal transitions impossible and makes the current status unambiguous.
Legal transitions
Each state declares which next states are allowed. A payment can go from authorized to captured, but never from failed back to captured. The machine rejects any transition not in the table.
Handling async events
Processor callbacks arrive out of order and may repeat. The state machine treats each event against the current state, ignoring events that do not apply and applying only legal ones.
Operational guidance
- Store the current state and reject transitions outside the allowed set.
- Make transitions idempotent so a repeated callback does not double advance.
- Record every transition with a timestamp for the audit trail.
Key idea
A payment is a state machine where only declared transitions are legal, which blocks invalid status jumps.