Skip to content

Statut d'un paiement ​

Un paiement traverse plusieurs états entre sa création et son issue finale. Cette page liste tous les statuts possibles et la transition logique entre eux.

Statuts ​

StatutDescription
initiatedLe paiement a été créé et envoyé à l'agrégateur. En attente d'action client.
pendingL'agrégateur a accepté le paiement, le client a démarré le règlement (saisie OTP, scan, etc.).
successLe paiement a été confirmé par l'opérateur. C'est l'état final positif — vous pouvez livrer le service.
failedLe paiement a échoué. Le champ failure_reason détaille la cause.
cancelledLe paiement a été annulé par le client ou par expiration de la session de checkout.
refundedLe paiement a été remboursé (depuis le tableau de bord ou via l'API du dashboard).

Diagramme de transitions ​

initiated ──> pending ──> success ──> refunded
                   └────> failed
                   └────> cancelled

Un paiement ne revient jamais à un état antérieur. Une fois success, failed, cancelled ou refunded, il est immuable.

Statut refunded

Seul un paiement préalablement en success peut passer en refunded. Le webhook payment.refunded est émis à ce moment-là. Pour les transferts, le statut refunded n'existe pas — un transfert ne peut être que success, failed ou cancelled.

Causes d'échec courantes ​

Le champ failure_reason fournit un texte humain expliquant l'échec. Les motifs les plus fréquents :

MotifDescription
Insufficient fundsLe solde du wallet client est insuffisant
Invalid PINLe code de validation Mobile Money est incorrect
Operation timeoutLe client n'a pas validé dans le délai imparti (généralement 2-5 min)
Operator unavailableIndisponibilité temporaire du réseau de l'opérateur
Card declinedLa banque émettrice a refusé la transaction (cartes uniquement)
3DS failedÉchec de l'authentification 3D Secure (cartes internationales)

Bonnes pratiques ​

  • Ne livrez jamais le service sur un statut autre que success
  • Loggez failure_reason pour vos propres tableaux de bord et le support client
  • Écoutez le webhook payment.refunded pour synchroniser vos commandes côté boutique
  • Pour les paiements en pending au-delà de 15 minutes, considérez-les comme abandonnés et appelez GET /v1/payments/{id} pour confirmer le statut final

Documentation officielle de l'API Zayono