Statuts et webhooks

201 Created confirme la réception d'une requête, pas le paiement d'une personne. Entre cette réponse et l'arrivée des fonds sur un téléphone se trouvent un opérateur, une file d'attente et, parfois, une personne.

Le statut indique où se trouve un payout. Le webhook vous informe de son évolution. Cette page explique la signification de chaque statut pour vos fonds, les événements émis ou non, et les conditions permettant à un handler de rester correct après une troisième livraison en double.

Les six statuts

Trois décrivent un payout toujours actif qui retient vos fonds. Les trois autres sont définitifs : un payout ne les quitte jamais.

POST /transfers crée un payout avec processing, ou avec review lorsqu'une mesure de protection le retient, et rien d'autre. Un payout arrêté avant tout envoi se termine en cancelled : rejeté dans le Dashboard, son failure_reason est merchant_rejected ; annulé par Wajub, cancelled_by_wajub. Un payout refusé par la revue de Wajub (admin_rejected) ou par l'opérateur se termine en failed.

cancelled est arrivé avec la version d'API 2026-10-12. Un appel fixé sur une version antérieure lit un tel payout en failed, avec le même failure_reason, et le trouve avec status=failed.

Événement émis ou non

Il existe cinq événements de transfert. Ils ne couvrent pas les six statuts. Ces absences sont importantes.

Un webhook est structuré pour la version d'API courante de Wajub, pas pour celle que vous fixez. Tant que 2026-10-12 n'est pas la version courante, un payout annulé est annoncé en transfer.failed, avec status: failed.

transfer.created contient toujours processing ou review, jamais pending.

Les trois séquences réellement observées

Le payout réussit

Quatre secondes, trois événements. Seul le dernier indique un mouvement de fonds.

Les deux premiers événements ne vous apprennent rien de plus que la réponse 201. Agissez sur transfer.succeeded et ignorez les autres, sauf si vous affichez une chronologie au support.

Le payout échoue

Les deux mêmes événements sont suivis d'un troisième différent. Un échec survenu dans Wajub avant la transmission à un opérateur et un échec renvoyé par l'opérateur sont identiques sur le réseau : même séquence, même plage de temps et même nom d'événement.

Ces deux clés contiennent toute l'information fournie sur un échec. Lisez-les après avoir vérifié le statut au lieu de supposer leur présence.

failure_reason est un code court à utiliser dans vos branches et vos logs. failure_message est une phrase à montrer à une personne. Transferts liste les codes écrits par Wajub et explique pourquoi les autres viennent directement de l'opérateur. Pour un payout sur le circuit Wajub, transfer.failed libère aussi votre réservation. Le principal et l'estimation des frais reviennent dans available avant la fin de votre handler.

Le payout est retenu

transfer.created arrive avec status: "review", puis plus rien pendant des minutes ou des heures. Le payout attend l'intervention d'une personne chez Wajub. Aucun événement ne marque cette attente, car le payout a été créé directement dans cet état.

La résolution produit l'un de deux événements. transfer.processing signifie que le payout est approuvé et suit maintenant son traitement normal. transfer.failed avec failure_reason: admin_rejected signifie qu'il est refusé.

Structure d'un événement

Tous les événements de tous les produits utilisent la même enveloppe. Le transfert constitue l'intégralité de data, avec la même structure que la réponse de GET /transfers/{uid}.

L'enveloppe contient sept clés. Deux d'entre elles ne correspondent pas à ce que leur nom suggère.

L'une de ces sept clés mérite un avertissement. Une erreur à cet endroit ne produit aucun message.

request vous sera peu utile. request.id n'est jamais renseigné. request.idempotency_key est un identifiant généré pour l'événement lui-même, sans rapport avec la valeur Idempotency-Key envoyée avec POST /transfers. Pour relier un événement à votre propre appel, utilisez data.id ou envoyez votre propre reference lors de la création du payout : elle revient dans data.reference avec chaque événement.

Deux caractéristiques de data sont à connaître avant de l'utiliser. Le bénéficiaire, le moyen de paiement et le prestataire sont toujours développés. Un événement de transfert indique donc la destination des fonds sans second appel API. De plus, metadata ne contient pas uniquement vos données. Sur un payout live qui utilise le circuit Wajub, Wajub ajoute un objet reservation, puis un objet settlement lorsque le payout implique une conversion de devise. Lisez les clés que vous avez ajoutées et ne vérifiez jamais la structure exacte de l'ensemble.

Le handler

Effectuez trois opérations dans cet ordre : prouvez que l'événement vient de Wajub, répondez, puis traitez-le. Répondre avant le traitement n'est pas une optimisation. Cette méthode empêche une base de données lente de provoquer une multiplication des nouvelles tentatives.

import express from 'express';

const app = express();

// The client verifies with the secret it was built with: webhookSecret,
// or WAJUB_WEBHOOK_SECRET when you pass none.
app.post('/webhooks/wajub', express.raw({ type: 'application/json' }), (req, res) => {
  let event;

  try {
    event = wajub.webhooks.constructEvent(
      req.body,
      req.headers['x-wajub-signature'],
      req.headers['x-wajub-timestamp'],
    );
  } catch {
    return res.status(400).send('invalid signature');
  }

  res.status(200).end();

  queue.push(event);
});

Le renvoi d'une réponse 400 pour une mauvaise signature est volontaire. Rejouer les mêmes octets échouerait de la même façon, donc une nouvelle tentative n'apporterait rien. Vérification de signature détaille l'algorithme, l'obligation d'utiliser le corps brut et la fenêtre de cinq minutes de l'horodatage.

Le traitement doit être effectué en dehors de la requête. Il se divise d'abord selon le nom de l'événement, puis selon son statut.

async function handleTransferEvent(event) {
  const transfer = event.data;

  if (await alreadyProcessed(event.id)) {
    return;
  }

  switch (event.event) {
    case 'transfer.succeeded':
      await markSupplierPaid(transfer.id, transfer.amount, transfer.currency);
      break;

    case 'transfer.failed':
      await flagPayoutFailure(transfer.id, transfer.failure_reason);
      break;

    case 'transfer.created':
      if (transfer.status === 'review') {
        await notifyOpsPayoutHeld(transfer.id);
      }
      break;
  }

  await recordProcessed(event.id);
}

transfer.processing est volontairement absent. Toute action à ce stade serait prématurée. Les fonds n'ont pas bougé. Un handler qui livre une commande avec processing la livre avant même la tentative de payout.

Les quatre causes d'erreur

Chacune de ces erreurs produit un handler qui passe la revue, fonctionne en préproduction et paie deux fois une personne en production.

Délai avant de vous inquiéter

Dans la sandbox, le délai fixe est d'environ deux secondes. En live, il dépend de l'opérateur. Il est généralement de quelques secondes, mais atteint parfois plusieurs minutes.

Si le callback de l'opérateur n'arrive jamais, Wajub continue de l'interroger. Un payout résolu de cette façon produit le même événement transfer.succeeded ou transfer.failed que les autres, mais plus tard. Votre handler ne peut pas distinguer ce cas et ne doit pas essayer.

Lire plutôt qu'écouter

Les webhooks conviennent au payout que vous attendez. La lecture convient au payout que vous contrôlez.

Utilisez cet appel pour un rapprochement planifié, pour répondre au support ou pendant le développement, avant de disposer d'une URL publique accessible par Wajub. Ne créez pas une boucle autour d'un payout en attendant succeeded. Lire un transfert compte dans la limite générale de votre équipe, soit 120 requêtes par minute avec le plan par défaut, et non dans la part réservée à l'envoi de payouts. Une boucle consomme pourtant la capacité nécessaire à tous les autres appels de votre intégration.

Pour un rapprochement en fin de journée, listez les payouts par période et comparez-les aux événements reçus. Si un payout enregistré chez vous comme processing est définitif chez Wajub, vous avez manqué une livraison. La Konsole affiche chaque tentative effectuée pour vous joindre.

Si vous êtes une plateforme

Un payout effectué pour un compte connecté est livré deux fois : une fois aux endpoints de ce compte et une fois aux vôtres. Votre copie contient un objet account supplémentaire qui désigne le marchand concerné. Un seul endpoint peut ainsi servir tous vos comptes connectés. Sync explique leur configuration.