Motifs d'échec

Un 4xx signifie que la requête a été refusée. Cette page traite de l'autre type d'échec : une requête qui a réussi, a créé une ressource, puis a échoué plus tard chez l'opérateur. L'objet et son webhook portent deux champs qui l'expliquent.

Où il apparaît

Cette même paire est livrée dans les webhooks payment.failed, transfer.failed et refund.failed, puisque ces payloads sont la ressource elle-même.

Codes émis par Wajub

Ces codes sont stables et la liste est exhaustive.

Transferts

Les trois derniers accompagnent un payout cancelled.

Remboursements

Un remboursement échoué porte toujours l'un de ces codes, en live comme en sandbox. failure_message garde la phrase du fournisseur quand il en a envoyé une.

Un remboursement peut rester pending ou processing un moment ; failed est définitif. Une nouvelle tentative est un nouveau remboursement.

Paiements échoués

Un paiement échoué porte la raison de sa dernière tentative échouée, sur le paiement et dans le webhook payment.failed :

Les paiements échoués plus anciens peuvent ne porter aucun de ces deux champs.

Le status distingue toujours les trois cas qui changent la suite :

Pour chaque tentative, pas seulement la dernière, ouvrez le paiement dans Konsole : sa chronologie montre chaque tentative, le prestataire concerné et la réponse brute de la passerelle.

Codes émis par l'opérateur

Tout ce qui ne figure pas dans les tableaux ci-dessus est le code d'erreur propre au prestataire, transmis sans modification. Les opérateurs ne partagent aucun vocabulaire : MTN, Orange, Wave et un acquéreur de cartes nomment chacun différemment la même erreur du client, et un nouveau code peut apparaître à tout moment.

const RETRY_NEVER = new Set([
'team_restricted',
'admin_rejected',
'merchant_rejected',
'invalid_recipient',
]);

function onTransferFailed(transfer) {
const reason = transfer.failure_reason;

if (RETRY_NEVER.has(reason)) {
  return escalateToSupport(transfer);
}

if (reason === 'no_provider') {
  return scheduleRetry(transfer, { in: '15m' });
}

return notifyMerchant(transfer.failure_message);
}

La sandbox est déterministe

La sandbox n'appelle aucun opérateur : le numéro, le compte ou l'adresse de test que vous utilisez décide du résultat, ce qui permet d'exercer volontairement chaque branche de votre handler avant de passer en live. Les tables des numéros de test se trouvent dans Scénarios de test.

Transferts. Les six derniers chiffres d'un numéro de test Mobile Money (et le suffixe d'un compte bancaire ou d'une adresse crypto de test) choisissent le résultat. Un transfert qui échoue porte l'une de ces trois raisons :

Un numéro qui n'est pas un numéro de test est refusé par un 422 qui liste ceux à utiliser.

Remboursements. Le moyen de paiement du paiement remboursé décide : un paiement Mobile Money réglé avec un numéro finissant par 000000 est remboursé, un numéro finissant par 000001 à 000004 ou par 000009 échoue ; la carte 4000 0000 0000 5423 est débitée mais ses remboursements échouent toujours ; les paiements par banque et crypto sont toujours remboursés. Seul un paiement sans moyen de paiement rattaché n'a pas d'issue fixée. Le failure_reason d'un remboursement sandbox échoué est tiré de la même liste qu'en live, dans Remboursements.

Paiements. Les six derniers chiffres du numéro de test décident du statut : 000002 se termine en failed, 000003 en expired, 000004 en cancelled. 000001 est refusé aussitôt par un 402 avec error_code: insufficient_funds, comme un refus en live, et le paiement reste pending. Un paiement sandbox qui échoue en donne la raison avec une paire fixe, choisie par le numéro ou la carte de test utilisé :