Payment lifecycle

Every payment moves through a fixed set of states. The app shows exactly one of them at a time, because the difference between them is the difference between a promise and settled money.

States#

StateWhat has happenedHas money moved?
PreparedThe payment was created on the payer's deviceNo
SignedThe payer confirmed it, and the phone signed the voucherNo
RelayedThe voucher has been handed to nearby devices or reached the merchantNo
SubmittedA device with connectivity sent it to SolanaNo, not yet
ConfirmedThe settlement program verified and paid itYes
Failed / ExpiredIt was rejected, or it expired before reaching SolanaNo

On the website these are grouped into three states for clarity: Prepared, Awaiting network (signed, relayed or submitted) and Confirmed on-chain.

What "confirmed" means precisely#

When the program redeems a voucher, it emits a VoucherRedeemed event that splits the payout into three parts:

  • paid_from_balance: the normal case
  • paid_from_bond: the vault ran out, and the bond covered the rest
  • unpaid: neither the balance nor the bond could cover it

A confirmed voucher with a non-zero unpaid amount was settled but not paid in full. Apps should show that clearly rather than as a successful payment.

Why a voucher fails#

ReasonError
It expired before anyone submitted itExpired
It was already settledAlreadyRedeemed
The payer signed a different voucher with the same sequence numberDoubleSpend
Too many newer payments from the vault settled firstSequenceTooOld
It exceeds the vault's per-payment limitOverPaymentLimit
The signature isn't from the vault's signerInvalidSigner

The full list is in Settlement program errors.