Catalogue des événements

Chaque événement envoyé par Wajub, regroupé par sujet, avec ce qu'il faut faire à sa réception. Tous arrivent dans l'enveloppe des webhooks avec la ressource complète dans data, sauf les livraisons du cycle de vie Sync, qui ont leur propre format.

Comment un endpoint décide de se déclencher

La correspondance des abonnements est une simple comparaison de chaînes avec le tableau events que vous avez enregistré. Trois cas, pas un de plus.

Les jokers de préfixe n'existent pas. À partir de la version 2026-10-12 de l'API, enregistrer payment.*, ou tout nom qui n'est pas un type d'événement, répond 422 ; sur les versions antérieures, il est enregistré comme une chaîne littérale à laquelle aucun événement n'est jamais égal. Si vous voulez tout ce qui concerne une ressource, listez ses types, copiés depuis cette page.

Comment les noms sont construits

resource.verb, le verbe au passé, le tout en minuscules. Les verbes sont les mêmes d'une ressource à l'autre, ce qui rend la liste plus courte à retenir qu'il n'y paraît.

Trois orthographes font perdre un après-midi : c'est succeeded, jamais completed ni complete ; c'est cancelled avec deux l ; et Sync utilise deauthorized avec un z alors que tout le reste de la plateforme suit l'orthographe britannique.

Paiements

Les six états que traverse un paiement, et la tentative qui échoue sans y mettre fin. Seul payment.succeeded signifie que l'argent est là.

payment.failed transporte failure_reason dans data. Le champ est absent, et non null, quand il n'y a aucun motif à donner.

Une tentative refusée sur-le-champ

payment.attempt_failed n'est pas une fin. Un fournisseur a refusé une tentative sur-le-champ, ou aucun fournisseur ne pouvait la prendre, et le paiement est revenu à pending : le payeur peut réessayer sur le même paiement. payment.processing vous est peut-être déjà parvenu pour cette tentative, et c'est ce qui le suit. Un refus qui arrive plus tard, de l'opérateur, met fin au paiement avec payment.failed.

data est le paiement, avec en plus un objet attempt :

"attempt": {
  "failure_code": "insufficient_funds",
  "failure_message": "Insufficient funds.",
  "channel": "cm.mtn"
}

failure_code est le code de refus du fournisseur quand il en donne un, no_eligible_provider quand aucun fournisseur ne pouvait prendre la tentative, et payment_declined sinon. En sandbox, un numéro qui se termine par 000001 l'envoie. Sur un canal qui demande un code que le payeur génère, il est aussi envoyé quand ce code manque (otp_required) ou est refusé (invalid_otp, et otp_attempts_exceeded la troisième fois) ; les autres refus gardent le code du prestataire. Un refus de ce code par l'opérateur arrivé plus tard envoie aussi payment.attempt_failed, pas payment.failed.

Paiements fractionnés

Émis quand un même paiement est débité en plusieurs tranches, via split_count ou split_amounts sur POST /payments/{id}/splits.

data contient le paiement complet, plus un objet split qui indique de quelle tranche il s'agit.

"split": {
  "id": "splt_9mWvL2xR7tB5nY4hC6dF",
  "split_number": 2,
  "amount": 500000,
  "currency": "XAF",
  "split_currency": "XAF",
  "status": "succeeded",
  "reference": "order-4172-2",
  "provider_reference": "MP260115.1032.B41209",
  "initiated_at": "2026-01-15T10:32:04+00:00",
  "succeeded_at": "2026-01-15T10:32:41+00:00"
}

Le paiement parent n'atteint payment.succeeded qu'une fois toutes les tranches réussies, ou quand vous le clôturez avec POST /payments/{id}/close. Compter vous-même les payment.split.succeeded pour décider que la commande est complète, c'est le meilleur moyen de livrer une commande à moitié payée.

Le live les envoie pour les mêmes appels, sur les canaux Mobile Money. Le paiement parent envoie aussi payment.processing chaque fois qu'une tranche part chez le payeur, et il est partial entre deux tranches. Ni le live ni la sandbox ne fractionnent un paiement d'eux-mêmes : un débit unique au-dessus du plafond par transaction indiqué dans Plafonds et quotas est refusé avec un 422, et POST /payments/{id}/splits le règle en tranches. Paiements fractionnés décrit ce que renvoie chaque appel.

Remboursements

data.transaction est l'id du paiement remboursé, sous forme de chaîne, pas d'objet imbriqué.

Transferts

Les payouts depuis votre solde, que ce soit vers un portefeuille Mobile Money, un compte bancaire ou une carte.

Clients

Le payload de customer.deleted est le client après anonymisation : le nom est remplacé, et l'e-mail, le téléphone et la date de naissance ont disparu. Si vous avez besoin des valeurs d'origine pour vos propres données, vous devez les avoir conservées.

Bénéficiaires

data contient, pour ces deux événements, la dette elle-même : id, beneficiary, reference, refund, currency, amount, recovered, outstanding, status, settled_at et created_at, montants en unité principale. Voir l'endpoint des créances.

Liens de paiement

Un paiement effectué via un lien émet payment.*, pas link.*. Les événements de lien concernent l'objet lien lui-même. Les endpoints propres à un lien, réglés dans son onglet Webhooks, reçoivent aussi ses paiements, billets, dons, commandes et remboursements : voir Les webhooks d'un lien.

Factures

Litiges

Rétrofacturations et réclamations. Ce sont les événements assortis des délais les plus courts.

Comptes, pour les plateformes Sync

Ces événements décrivent un marchand connecté à une plateforme Sync, pas votre propre compte. Ceux qu'envoie l'API arrivent dans l'enveloppe habituelle :

Chacun d'eux désigne sa connexion dans data.account : l'identifiant acc_…, la valeur que vous envoyez dans X-Sync. Lisez la connexion à cet endroit, pas dans data.id, qui n'est pas toujours la connexion :

Sur ces événements, account est l'identifiant lui-même, une chaîne. Sur la copie d'un événement de paiement, de remboursement, de transfert ou de litige que reçoit une plateforme, et sur fee.received, account est un objet et l'identifiant se trouve dans account.id : voir Les plateformes Sync reçoivent une copie.

Il n'existe pas de account.deleted. account.created annonce l'invitation que vous avez créée ; l'acceptation du marchand est account.connected, plus bas. Quand le marchand révoque lui-même la connexion, le account.deauthorized que vous recevez est celui au format Sync.

Le reste de la vie de la connexion, ainsi que les mêmes changements quand ils sont faits depuis le Dashboard plutôt que par l'API, sont envoyés au format Sync décrit dans la section suivante :

Livraisons du cycle de vie Sync

Les événements du second tableau ne voyagent pas comme les autres. Ils sont envoyés aux endpoints de la plateforme propriétaire de la connexion, dans l'environnement de cette connexion.

• Seul un abonnement exact les reçoit. * et un tableau events vide ne correspondent pas. Listez chaque type voulu.
• Le corps est à plat, sans l'enveloppe habituelle : event, account (l'id acc_… de la connexion), sandbox, timestamp, puis les champs propres à l'événement. Il n'y a pas de data : lisez la connexion dans account, la clé qu'utilisent sous data les événements account.* de l'API. Ne vous fiez qu'aux champs documentés ici.
• Les en-têtes sont différents : X-Sync-Event nomme l'événement, X-Idempotency-Key identifie la livraison, et X-Sync-Signature-V1 avec X-Sync-Timestamp portent la signature.
• Vérifiez la signature comme pour toute autre livraison. X-Sync-Signature-V1 est v1= suivi du HMAC-SHA256 en hexadécimal de {timestamp}.{raw_body}, avec le secret de signature de l'endpoint pour clé, et X-Sync-Timestamp est cet horodatage en secondes Unix. Passez les deux à constructEvent dans les SDK, ou vérifiez-les à la main comme dans Vérification de signature, et refusez une livraison dont l'horodatage s'écarte de plus de 300 secondes de votre horloge. Enregistrez ensuite chaque X-Idempotency-Key traité, et ignorez une livraison dont la clé a déjà été vue.
• Seul un 2xx vaut livraison, comme pour tout autre événement : une redirection n'est pas suivie et compte comme un échec. Chaque tentative part vers l'endpoint tel qu'il est au moment de l'envoi, signée avec son secret actuel, et un endpoint désactivé ou supprimé entre-temps ne reçoit plus rien.
• Les nouvelles livraisons ne durent que quelques minutes : gardez l'endpoint disponible et répondez en moins de 10 secondes. Ces livraisons n'apparaissent pas dans le journal des événements de Konsole.

Voici à quoi ressemble account.connected :

Solde et frais

balance.updated envoie le mouvement lui-même, c'est ce qu'il vous faut pour un registre.

Les totaux que renvoie GET /balance ne figurent pas dans ce payload. Appelez l'endpoint quand vous en avez besoin.

Conformité

Émis pendant la vérification de votre compte, puis chaque fois que votre dossier change d'état.

Pour une plateforme qui inscrit des marchands, compliance.verified est le signal qu'un compte connecté peut commencer à accepter des paiements live. Ne le déduisez de rien d'autre.

Prestataires

Émis quand l'ensemble des prestataires et des canaux disponibles sur votre compte change.

Utile si vous mettez en cache les canaux de votre compte au lieu d'appeler GET /providers à chaque checkout.

Endpoints de webhook

Utile sur un compte plateforme où plusieurs personnes peuvent modifier la configuration. Notez que l'endpoint qui reçoit cet événement peut être celui qui vient d'être modifié.

Ce que contient réellement data

data est la ressource telle que la renvoie son endpoint REST. Trois points sont à connaître.

Un champ sans valeur peut être absent ou null. Lisez chaque champ avec une valeur par défaut, et acceptez null.

Un metadata vide arrive en {}, jamais en [].

Le payload est toujours dans la dernière version de l'API. La version fixée s'applique à vos appels API, pas aux livraisons de webhooks : l'api_version de l'enveloppe est la version courante de la plateforme au moment où l'événement a été enregistré, et le corps est structuré pour cette version. Épingler votre compte sur 2026-08-01 ne change pas ce que reçoit votre endpoint.

Les événements qu'on cherche et qui n'existent pas

Sandbox et live sont deux flux séparés

Un endpoint appartient à un seul environnement. Un endpoint sandbox ne reçoit que des événements sandbox, et un endpoint live que des événements live. Deux choses changent dans le payload :

• livemode vaut false en sandbox et true en live.
• Les ids d'événement sont préfixés evt_test_ en sandbox et evt_ en live.

Un handler qui code en dur la longueur d'un id ou qui retire un préfixe cassera dès qu'il rencontrera l'autre environnement.

Les plateformes Sync reçoivent une copie

Quand un paiement, un remboursement ou un transfert appartient à un marchand connecté via Sync, ou qu'un litige est ouvert sur un tel paiement, l'événement est livré deux fois : une fois aux endpoints du marchand, et une fois à ceux de la plateforme, sous forme d'événement distinct avec son propre id. La copie de la plateforme porte un objet account supplémentaire pour que vous sachiez de quel marchand connecté elle provient. Les liens, factures et bénéficiaires créés par la connexion ne sont pas copiés : GET /events avec X-Sync liste leurs événements.

"account": {
  "id": "acc_7Yh2MpL4tRb3nP8sZcXv",
  "reference": "boutique-akwa"
}

Dédupliquez sur l'id de l'événement, pas sur l'id du paiement : les deux copies décrivent le même paiement et portent volontairement deux ids d'événement différents.