Crypto Payment State Transition

Overview

What it means

A payment state transition is a controlled change from one named payment state to another when a defined event and guard conditions are satisfied. It is the active rule inside a payment state machine.

How it works

Each transition has a source state, triggering event, eligibility checks, target state and side effects. An application should commit the state update and a durable event record atomically where possible, then dispatch customer or fulfillment notifications without allowing duplicate effects. Versioned business rules help explain older orders.

Understanding the technical details

Developers should write transition tables showing source, event, guard, destination and allowed side effects. The transition from confirming to paid might require valid token, sufficient amount and finality proof simultaneously. Make the invoice version or row revision part of a concurrency-safe update so two workers cannot both fulfill the same order. For debugging, persist rejected transition attempts with reason codes rather than silently ignoring all unexpected events. For example, a refund-created event should not move an invoice into refunded status until the refund action has the evidence required by that state. Preserve both the requested refund and the executed transfer references.

Common failures and limitations

Out-of-order events require care: an earlier “pending” message arriving after “paid” should not roll the invoice backward. Reorgs may require a special investigation transition rather than erasing history and pretending finality never existed.

Related concepts

Payment Retry, Crypto Payment Status, Payment Finality Threshold.

Further reading

OxaPay — Developer documentation.