Remboursements

Un remboursement est un objet à part entière, avec son propre id, son propre statut et ses propres webhooks. Ce n'est pas un état dans lequel passe le paiement. La distinction compte plus qu'il n'y paraît : le paiement que vous remboursez reste succeeded pour toujours, et tout ce que vous voulez savoir sur l'argent qui revient se trouve sur le remboursement.

Vous pouvez restituer le montant total ou une partie, et cumuler plusieurs remboursements partiels jusqu'à épuisement du montant d'origine.

Ce qui peut être remboursé

Quatre conditions sont vérifiées avant l'enregistrement d'un remboursement, et chacune échoue avec son propre 422.

Le montant remboursable est le montant du paiement moins tout ce qui a déjà été remboursé, en comptant les remboursements encore pending comme ceux qui ont réussi. Un remboursement en attente réserve donc sa part immédiatement : c'est ce qui empêche deux appels simultanés de rembourser deux fois le même argent.

Créer un remboursement

Le paiement est désigné par son id Wajub. Votre propre reference sur le paiement n'est pas acceptée ici, car la recherche porte sur l'id du paiement et rien d'autre.

reason est obligatoire et sa liste est fermée. Toute valeur hors de cette liste donne un 422 : choisissez la plus proche plutôt que d'en inventer une.

Envoyez l'appel depuis votre serveur, avec une Idempotency-Key si le remboursement peut être déclenché par un processus qui retente ses appels.

curl https://api.wajub.com/refunds \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-4172" \
  -d '{
    "payment": "trx_test_CSUGajfv9xh0XQ5wu2lx",
    "amount": 2000,
    "reason": "product_not_received",
    "reference": "rma-881"
  }'

Wajub répond 201 Created. Rien n'a encore quitté votre solde : le remboursement a été accepté et mis en file, et status vous indique où il en est.

Le paiement est porté par transaction, pas par payment. Les lectures renvoient aussi un détail tax quand une taxe s'applique, une timeline des changements de statut, et failure_reason avec failure_message quand le remboursement a échoué. Un remboursement qui a pris de l'argent sur votre solde renvoie en plus ledger_balance_currency, ledger_balance_before et ledger_balance_after : votre solde juste avant le remboursement et juste après, si bien que la différence est ce qu'il a pris, part des frais du paiement comprise quand elle a bougé avec lui. En sandbox, ce sont ceux de votre solde sandbox. refund.succeeded part une fois le remboursement sorti de votre solde : son contenu les porte aussi, et il peut arriver quelques minutes après le passage du remboursement à succeeded. Un remboursement qui n'a rien pris, parce qu'un litige perdu l'avait déjà fait, n'a aucun des trois.

Le remboursement a son propre cycle de vie

Cinq états, dont trois terminaux. Un remboursement ne revient jamais à un état précédent.

Le délai ne dépend pas de Wajub. Sur une carte, c'est l'émetteur qui décide, et plusieurs jours sont normaux. Sur Mobile Money, le crédit arrive généralement en quelques minutes, parfois en quelques heures. Rien dans votre intégration n'y change quoi que ce soit : annoncez au client une fourchette plutôt qu'une heure précise.

Qui envoie un remboursement live

En production, un remboursement est envoyé de l'une de trois façons. execution_mode sur le remboursement dit laquelle, une fois que Wajub l'a planifié, et manual_reason dit pourquoi quand il n'est pas envoyé automatiquement.

manual_reason est un objet avec un code stable sur lequel brancher votre logique et un message que vous pouvez afficher.

Un remboursement peut changer de voie sans changer de statut. Un remboursement pas encore envoyé reste pending quand l'équipe Wajub le prend en charge. Un remboursement déjà transmis à l'opérateur reste processing quand l'opérateur le refuse et que le support Wajub le traite (automatic_attempt_failed) : il ne revient pas à pending. Dans les deux cas il se termine succeeded ou failed. Chaque changement de voie envoie refund.updated avec le remboursement tel qu'il est désormais. Les remboursements sandbox n'ont aucun des deux champs.

Ce que dit le statut du paiement

Cela dépend de votre version de l'API, et c'est le point qui piège tout le monde.

À partir de la version 2026-10-11, un paiement affiche partially_refunded dès que des remboursements réussis couvrent une partie de son montant, et refunded dès qu'ils le couvrent en entier. Un remboursement pending, processing ou failed ne change rien. Sur une version antérieure, le paiement continue d'afficher succeeded, quel que soit le montant remboursé. Gestion des versions indique celle sur laquelle votre compte est fixé.

Le statut est une lecture, et rien d'autre ne bouge avec lui : aucun événement de paiement n'est émis, et le paiement n'est pas modifié par ailleurs. Pour savoir ce qui reste remboursable, quelle que soit la version, listez les remboursements du paiement et additionnez ceux qui sont pending, processing ou succeeded.

Soustrayez ce total du montant du paiement et vous obtenez ce qui reste remboursable, c'est-à-dire exactement le chiffre que l'API vérifie quand vous envoyez le remboursement suivant.

Qui supporte les frais

Wajub garde les frais d'un paiement que vous remboursez. Ce que vous décidez, c'est qui les supporte au final, pour la part des frais qui correspond au montant remboursé : vous, ou le client. C'est fees_bearer.

Sans ce champ, les frais restent à celui qui les a payés : c'est la première et la dernière case du tableau, et c'est ainsi que les remboursements ont toujours fonctionné. Pour changer cela pour tous les remboursements, réglez-le une fois dans Settings, Refunds ; fees_bearer sur un remboursement prend le dessus.

Le remboursement vous dit ce qui a été appliqué : fee_amount est la part des frais, et payer_amount ce que le client reçoit. Votre solde est débité de payer_amount, ni plus ni moins. Un remboursement partiel prend la même proportion des frais, et le remboursement qui solde le paiement prend ce qu'il en reste : les parts s'additionnent exactement. Dans une devise sans subdivision, comme le XAF, une part est un nombre entier, et payer_amount aussi.

Un paiement encaissé sur votre propre compte prestataire est différent. Wajub ne détient rien de son argent : votre solde n'est pas débité, vous envoyez le remboursement vous-même depuis ce prestataire, et le montant à envoyer est payer_amount. Avec bearer: merchant, Wajub n'a facturé aucuns frais sur ce paiement : fee_amount vaut 0 et payer_amount est égal à amount. Avec bearer: customer, le payeur a payé les frais en plus à votre prestataire, et le tableau ci-dessus s'applique.

L'argent bouge au succès, pas à la création

Créer un remboursement réserve le montant sur ce qui est remboursable, mais ne touche à aucun solde. Le débit a lieu quand le remboursement atteint succeeded, et seulement à ce moment-là, pour payer_amount : le montant, plus ou moins la part des frais.

Deux conséquences à anticiper. En sandbox, un remboursement réussi débite votre solde sandbox du montant remboursé, comme un remboursement live débite votre solde. Un remboursement qui rembourse un litige que vous avez accepté le débite même s'il échoue, puisque le litige est perdu dans tous les cas. Et un remboursement émis sur un paiement déjà perdu dans un litige est plafonné au montant principal qui n'a pas déjà été repris : le même argent ne peut pas sortir deux fois par deux portes différentes.

Ce que devient ensuite le solde, et comment se comporte un solde négatif, est expliqué dans Solde et règlements.

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.

Dé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.

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é.

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é.

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 plus haut). 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.

La récupération d'un remboursement se fait par son id.

Dans le Dashboard

Un remboursement peut être émis sans écrire de code. Ouvrez un paiement dans Payments, utilisez son action de remboursement, et le résultat est le même objet que celui que crée l'API. Le formulaire demande qui supporte les frais quand le paiement en portait, et affiche ce que le client recevra. L'action exige la permission refund_payments, distincte de manage_payments : un membre de l'équipe peut ainsi gérer les commandes sans pouvoir rendre de l'argent.

Refunds les liste tous avec leur statut, et les exporte en CSV ou Excel en production.

Refund requests est le côté entrant. Un payeur qui utilise Pocket peut demander le remboursement d'un paiement qu'il a effectué, et la demande y attend jusqu'à ce que quelqu'un l'approuve ou la rejette. Rien n'est remboursé avant l'approbation, et l'approbation crée le remboursement exactement comme le ferait l'API.