Payment state machine

A Velarum payment is a state machine, not a single API call. Its lifecycle is defined by ADR-NC-004 and is the authoritative PaymentStatus enum.

The eight states

The status of a payment is exactly one of: intent_created, intent_expired, intent_abandoned, chain_pending, chain_included, settled, reverted, orphaned. These names are the canonical enum — the SDK exposes them as velarum.PaymentStatus.

State diagram

Who can advance state

Every non-terminal transition is driven by either a user-signed receipt or the worker observing a public on-chain event. A Velarum API call may register the initial intent_created, but it must never push any later transition directly. After chain_pending, the entire history is reconstructible from on-chain data — the Velarum database is an index, not the source of truth.

Terminal states & refunds

intent_expired, intent_abandoned, settled, reverted, and orphaned are terminal. A terminal payment is never revived; you create a new intent (a fresh payment_id). Velarum has no “cancel”, “freeze”, or “refund” button — a refund is simply a new reverse payment (refund type with parent_payment_id) that you authorize and sign.

Human-in-the-Loop (HC-NC-5)

An over-threshold agent intent does not enter the state machine at all: it is rejected synchronously with HC_NC_5_HITL_REQUIRED and no payment_id is created. AWAITING_USER_CONFIRMATION is therefore expressed as an error to re-confirm and resubmit as a human-initiated payment, keeping a human in the loop by default (HC-NC-5).