Suivre un remboursement
Ses webhooks, pourquoi un remboursement échoue, un échec dans la sandbox, et la liste des remboursements.
Webhooks
Six événements suivent un remboursement. Abonnez-vous à chacun par son nom : un abonnement ne
reconnaît que des noms exacts, et refund.* ne correspond à rien.
| Événement | Déclenché quand |
|---|---|
refund.created | Le remboursement a été accepté et enregistré |
refund.processing | Le remboursement a atteint le prestataire. En live uniquement |
refund.succeeded | Fonds restitués. C'est sur celui-ci qu'il faut faire le rapprochement |
refund.failed | Le prestataire l'a refusé ou n'a pas pu le finaliser, lisez failure_reason |
refund.cancelled | Wajub a arrêté un remboursement live avant de l'envoyer, avec cancelled_by_wajub : rien n'a quitté votre solde. Envoyé une fois la version d'API 2026-10-12 devenue courante, en refund.failed jusque-là |
refund.updated | Un remboursement live a changé de voie : execution_mode ou manual_reason a changé. Live uniquement |
refund.processing n'arrive jamais en sandbox
En live, un remboursement passe de pending à processing quand il atteint le prestataire, et
refund.processing est envoyé. En sandbox, un remboursement est créé directement en processing :
cet événement n'arrive donc jamais. Utilisez refund.created si vous avez besoin d'un signal au
démarrage dans les deux environnements.
refund.succeededévénementDédupliquez sur X-Wajub-Delivery-Id comme partout ailleurs. L'enregistrement et la vérification de
signature sont dans Webhooks.
Tester un remboursement en échec dans la sandbox
Les résultats en sandbox sont déterministes, et ils dépendent du moyen de paiement du paiement d'origine, pas de ce que vous envoyez sur le remboursement. Payez avec le bon numéro, remboursez ensuite, et vous obtenez le résultat voulu.
Pour un paiement fait par Mobile Money, ce sont les six derniers chiffres du numéro de téléphone qui décident.
| Suffixe sur le paiement d'origine | Résultat du remboursement |
|---|---|
000000 | Réussit |
000009 | Le paiement réussit, le remboursement échoue toujours. C'est celui à utiliser pour vos tests |
000001, 000002, 000003, 000004 | Rien à rembourser : le paiement lui-même n'aboutit jamais, donc l'appel de remboursement répond 422 |
| Tout autre suffixe | Réussit |
Pour un paiement par carte, 4000000000005423 débite normalement puis fait échouer chaque
remboursement. Toutes les autres cartes de test se remboursent sans problème. Les paiements en
cryptomonnaies et les paiements bancaires se remboursent toujours avec succès, car il n'existe pas
d'adresse d'échec pour les tester.
Un remboursement sandbox échoué porte un failure_reason tiré au hasard parmi
insufficient_funds, refund_rejected_by_issuer, transaction_already_reversed, network_error,
provider_error et provider_declined, accompagné d'un failure_message lisible. Ce sont des codes
qu'utilise aussi un remboursement live, listés dans
Pourquoi un remboursement a échoué.
Le seul cas aléatoire
Quand le paiement d'origine n'a aucun moyen de paiement rattaché, la sandbox se rabat sur un tirage au sort pondéré pour réussir environ sept fois sur dix. Si vos tests sont instables, voici pourquoi : payez avec un vrai numéro de test pour que le résultat soit choisi et non tiré au hasard.
Pourquoi un remboursement a échoué
Un remboursement failed porte toujours un failure_reason, pris dans cette liste en production
comme en sandbox, et un failure_message à côté : les mots du fournisseur quand il en a envoyé.
failure_reason | Ce qu'il signifie |
|---|---|
insufficient_funds | La réserve du fournisseur ne couvrait pas le remboursement |
refund_rejected_by_issuer | Un émetteur de carte l'a refusé |
transaction_already_reversed | Le paiement était déjà annulé ou remboursé chez le fournisseur |
invalid_number | Le numéro ou le compte du payeur ne peut pas le recevoir, par exemple fermé ou non abonné. Live uniquement |
limit_exceeded | Un plafond du compte destinataire ou du fournisseur a été atteint. Live uniquement |
network_error | Le fournisseur n'a pas pu être joint à temps |
provider_error | Le fournisseur était indisponible, ou a refusé l'appel lui-même |
provider_declined | Le fournisseur l'a refusé sans dire pourquoi |
ops_failed | Le support Wajub n'a pas pu mener à bien un remboursement qu'il avait pris en charge, sans raison connue : celui que le prestataire avait refusé garde la raison du prestataire, prise dans cette liste. failure_message porte sa note. Live uniquement |
Un remboursement échoué ne prend rien sur votre solde, à une exception près en sandbox : le remboursement d'un litige que vous avez accepté, qui tient lieu de perte du litige (voir L'argent bouge au succès). Une nouvelle tentative est un nouveau remboursement.
Lister les remboursements
Les remboursements sont renvoyés du plus récent au plus ancien, tous paiements confondus.
https://api.wajub.com/refunds| Paramètre de requête | Accepte |
|---|---|
per_page | De 1 à 100, 25 par défaut |
status | pending, processing, succeeded, failed, cancelled. Avant la version d'API 2026-10-12, un remboursement annulé se lit failed et failed le liste |
search | Texte libre sur la référence et l'id du remboursement |
date_from, date_to | Dates, date_to jamais antérieure à date_from |
cursor | Passe en pagination par curseur, pour les exports |
La récupération d'un remboursement se fait par son id.
https://api.wajub.com/refunds/{id}