Payment State Machine

Overview

Payment State Machine turns payment processing into a controlled set of states and transitions. Instead of letting any event overwrite a status field, the system checks whether the event is valid for the current state and whether it has already been applied.

A typical flow can begin with a created or new state, move to waiting when the payer selects an asset, then to paying when a transfer is detected, and finally to paid after the confirmation policy is satisfied. Alternative paths can represent underpayment, expiration, refunding, refund completion, or manual acceptance.

Blockchain payments are asynchronous, so events can arrive late, repeat, or appear out of order. The state machine must use idempotent event identifiers and preserve evidence. A duplicate paid webhook should not trigger fulfillment twice, and a delayed pending event should not move a completed payment backward.

Reorganizations and conflicting transactions require explicit reversal or exception handling. The application may distinguish observed, confirmed, credited, and fulfilled states instead of collapsing them into one label. This separation lets operators pause fulfillment while retaining a record of what the network previously reported.

The machine should be documented alongside Payment State Transition rules and tested for every permitted and prohibited path. Dashboards, APIs, webhooks, accounting, and customer messages should derive from the same model. Otherwise, different components can disagree about whether funds are payable, refundable, or settled. Production use also requires Payment State Management and complete Payment State Tracking around the formal transition model.

Design reviews should identify terminal states, reversible states, timeout behavior, and transitions that require human approval. Property-based and scenario testing can then generate duplicate, delayed, and conflicting events to prove that the machine never creates an extra credit, refund, or fulfillment action.