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 quitte jamais l'un de ces derniers.

Votre intégration ne peut jamais produire deux de ces six statuts. POST /transfers crée un payout avec processing, ou avec review lorsqu'une mesure de protection le retient. pending et cancelled appartiennent à la file de confirmation de la Konsole. Un payout reste pending tant qu'un collègue doit l'approuver, puis passe à cancelled en cas de refus. Vous pouvez les lire avec GET /transfers si votre équipe utilise cette file, mais jamais les obtenir en réponse à votre propre appel.

Événement émis ou non

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

transfer.created contient toujours processing ou review, jamais pending. Le payload est sérialisé après la validation de la transaction de création, pas lors de l'insertion. La ligne pending de courte durée qui existe dans cette transaction ne vous parvient donc jamais.

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 placez votre référence dans metadata lors de la création du payout. Les métadonnées reviennent dans 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();

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'],
      process.env.WAJUB_WEBHOOK_SECRET,
    );
  } 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 l'interroge. Le premier contrôle est effectué 30 secondes après la transmission du payout. Les suivants ont lieu environ toutes les minutes, avec un intervalle croissant, soit une dizaine de contrôles sur environ quarante-cinq minutes. 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. Cet appel dépend de la limite générale de l'API, soit 120 requêtes par minute avec le plan par défaut. Une boucle consomme 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.