Statuts

Le cycle de vie d'une opération, du clic au règlement.

Statut	Terminal	Signification
initiated	non	Créée ; le payeur n'a pas encore agi
pending	non	Le payeur a agi ; confirmation du rail en attente
success	oui	Encaissée — les fonds sont crédités sur votre solde
failed	oui	Refusée ou échouée chez le rail
cancelled	oui	Annulée (par le payeur ou par vous) avant encaissement
expired	oui	Le lien ou la session de paiement a expiré sans action

Règles

• Un statut terminal ne change plus jamais. success ne devient pas failed ; un encaissement contesté produit une nouvelle ressource (remboursement, litige), jamais une réécriture de l'historique.
• pending peut durer — certains payeurs valident leur code USSD plusieurs minutes après. Ne traitez jamais pending comme un échec.
• La transition qui vous intéresse arrive en webhook ; la lecture (GET /v1/payments/{id}) est le filet de sécurité, pas le mécanisme principal.

Ne dérivez pas votre état du nôtre

Un statut décrit notre opération. Ce que votre commande doit devenir est votre décision : un success ne veut pas dire « expédier », il veut dire « les fonds sont chez vous ». Gardez votre propre machine à états et faites-la avancer sur les événements, pas l'inverse.