Statuts de paiement

Ce guide explique les états par lesquels passe un paiement sur SOAMTAR.

Cycle de vie d'un paiement

               (code PIN non saisi à temps)
                  ┌──────────► échec
                  │
initié ──► en attente ──► succès ──► partiellement remboursé ──► remboursé
                  │           │
                  │           └──► litige ──► succès / remboursé
                  ├──────────► annulé
                  └──────────► expiré

Cycle de vie simplifié

Ce diagramme montre le chemin d'un paiement, du moment où le client appuie sur « Payer » jusqu'à la réception de l'argent.

Signification des statuts

Statut	Signification
initiated	Créé sur SOAMTAR, pas encore envoyé à Orange Money (page de paiement hébergée).
pending	En attente : la demande de paiement a été envoyée sur le téléphone du client ; il ne l'a pas encore confirmée avec son code PIN.
processing	Une action du payeur est encore attendue.
success	Succès : Orange Money Sierra Leone a confirmé le paiement. Vous pouvez livrer.
failed	Échec : le paiement a été refusé (solde insuffisant, code PIN erroné, demande non confirmée à temps, erreur technique…).
cancelled	Annulé : le client a annulé la demande ou fermé la page.
expired	Expiré : le paiement n'a pas été finalisé dans la fenêtre de paiement (2 heures par défaut).
partially_refunded	Une partie d'un paiement success a été remboursée ; d'autres remboursements partiels restent possibles.
refunded	Les remboursements atteignent le montant du paiement.

La demande Orange Money elle-même laisse environ 5 minutes au client pour saisir son code PIN ; au-delà, Orange Money signale la demande comme échouée.

Statuts d'un remboursement

Un remboursement (POST/v1/refunds) a son propre statut, distinct de celui du paiement :

Statut	Signification
pending	Créé, pas encore soumis à Orange Money.
processing	Soumis : le crédit sur le portefeuille Orange Money du payeur attend sa confirmation.
success	Le payeur a été crédité. Vous recevez refund.success, ainsi que payment.refunded ou payment.partially_refunded.
failed	Le crédit a été refusé (voir failure_reason) ; le montant reste sur votre solde. Vous recevez refund.failed.

Voir Remboursements.

Règles d'or

• Un succès est définitif : un paiement success ne revient jamais en arrière.
• Le webhook fait foi : ne livrez jamais sur la foi du navigateur. Attendez toujours la confirmation (IPN) envoyée à votre serveur.
• Audit complet : chaque changement de statut est enregistré et consultable dans votre dashboard.

Invariants

• Les statuts finaux ne reculent pas : un success ne peut pas redevenir pending. Les transitions interdites sont rejetées par la base de données.
• Audit immuable : chaque changement de statut écrit une ligne dans un historique en ajout seul.
• Suppression logique uniquement : les données sont conservées selon les exigences réglementaires applicables.