Statuses

An operation's life cycle, from click to settlement.

Status	Terminal	Meaning
initiated	no	Created; the payer has not acted yet
pending	no	The payer acted; awaiting the rail's confirmation
success	yes	Collected — the funds are credited to your balance
failed	yes	Refused or failed at the rail
cancelled	yes	Cancelled (by the payer or by you) before collection
expired	yes	The link or payment session expired with no action

Rules

• A terminal status never changes again. success does not become failed; a disputed collection produces a new resource (a refund, a dispute), never a rewrite of history.
• pending can last — some payers confirm their USSD code several minutes later. Never treat pending as a failure.
• The transition you care about arrives by webhook; the read (GET /v1/payments/{id}) is the safety net, not the main mechanism.

Do not derive your state from ours

A status describes our operation. What your order should become is your decision: a success does not mean "ship", it means "the funds are with you". Keep your own state machine and advance it on events, not the other way round.