Payment State Transition

Overview

Payment State Transition is the controlled operation that changes the authoritative status of a payment. A transition includes a source state, destination state, triggering event, validation conditions, timestamp, and any resulting business actions.

Examples include new to waiting after asset selection, waiting to paying after on-chain detection, paying to paid after confirmation, and paid to refunding after an approved refund request. Some events may create exception states such as underpaid or expired rather than following the main success path.

A valid event does not automatically permit every transition. A late waiting event should not overwrite a paid state, and a refund-complete event should be rejected if no refund was initiated. The Payment State Machine defines these guards and identifies terminal or reversible states.

Transitions can trigger financial side effects, so idempotency is essential. Reprocessing the same webhook must not issue another credit or shipment. Systems should write the transition and an outbox or equivalent side-effect record atomically where possible, then retry downstream delivery safely.

Each change should retain the previous state, event identity, source, actor, and reason. This supports Payment State Tracking and makes manual intervention reviewable. Directly replacing the current status without transition history hides failures and prevents reliable reconstruction.

Transition design should specify transactional boundaries. If the state changes to paid but the ledger credit fails, the system needs an explicit pending-side-effect or recovery state rather than silently retrying without visibility. This makes partial failures observable and prevents support staff from assuming every paid record completed all downstream actions.