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#
| State | What has happened | Has money moved? |
|---|---|---|
| Prepared | The payment was created on the payer's device | No |
| Signed | The payer confirmed it, and the phone signed the voucher | No |
| Relayed | The voucher has been handed to nearby devices or reached the merchant | No |
| Submitted | A device with connectivity sent it to Solana | No, not yet |
| Confirmed | The settlement program verified and paid it | Yes |
| Failed / Expired | It was rejected, or it expired before reaching Solana | No |
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 casepaid_from_bond: the vault ran out, and the bond covered the restunpaid: 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#
| Reason | Error |
|---|---|
| It expired before anyone submitted it | Expired |
| It was already settled | AlreadyRedeemed |
| The payer signed a different voucher with the same sequence number | DoubleSpend |
| Too many newer payments from the vault settled first | SequenceTooOld |
| It exceeds the vault's per-payment limit | OverPaymentLimit |
| The signature isn't from the vault's signer | InvalidSigner |
The full list is in Settlement program errors.