Catalogue des événements

Konsole propose 72 types d'événements auxquels vous abonner. 68 d'entre eux atteignent réellement un endpoint, et les quatre qui ne l'atteignent pas sont nommés en bas de cette page. Presque tous arrivent dans la même enveloppe, décrite dans Webhooks ; seul data change de l'un à l'autre, et data contient toujours la ressource complète, identique à ce que renvoie l'endpoint REST de cette ressource. L'exception est le cycle de vie des connexions Sync, qui a son propre format.

Cette page est la liste complète, regroupée par sujet, avec ce qu'il vaut la peine de faire à la réception de chaque événement.

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. payment.* est 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.

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.

La sandbox envoie ce qu'envoie le live

Un paiement qui passe à expired envoie payment.expired, et un paiement qui passe à cancelled envoie payment.cancelled, en sandbox comme en live. Un délai dépassé en sandbox envoyait payment.failed et une annulation en sandbox rien du tout : un handler testé en sandbox manquait toutes les expirations du live.

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 devient Deleted User <pseudonym>, 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.

link.expired apparaît dans le sélecteur de Konsole mais n'est pas livré aux endpoints de votre compte. S'y abonner sur un endpoint de compte ne produit rien.

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. sync_uid porte le même id acc_… et reste pour les plateformes qui le lisent déjà. 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.
• X-Sync-Signature est conservé pour les intégrations existantes. C'est le HMAC-SHA256 du seul corps brut, en hexadécimal sans préfixe v1=. Il ne signe pas l'heure, donc il ne distingue pas un rejeu d'une livraison. Il sera retiré plus tard : vérifiez X-Sync-Signature-V1 à la place.
• Les nouvelles tentatives sont courtes : trois tentatives, espacées de 30 secondes puis de 2 minutes, 10 secondes chacune. 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 huit montants que renvoie GET /balance ne figurent pas dans ce payload. Appelez l'endpoint quand vous avez besoin des totaux.

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 sérialisée par le même code que celui qui sert l'endpoint REST, avec trois conséquences à connaître.

Un champ sans valeur est absent ou null, selon la ressource. Un paiement ou un client le retire : un paiement sans description n'a tout simplement pas de clé description. Un transfert, une facture, un lien ou un compte l'envoie à null. Lisez chaque champ avec une valeur par défaut, et acceptez null.

Un objet vide reste un objet. Un metadata vide arrive en {}, comme l'endpoint REST le renvoie, jamais en [] : un handler qui le lit dans une map ou une struct ne casse pas sur l'objet vide.

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

Les événements que Wajub enregistre pour son propre usage ne sont jamais livrés, même aux abonnés à *.

Types auxquels vous pouvez vous abonner mais qui n'arrivent jamais

Konsole vous laisse cocher ce type. Rien n'est jamais livré.

payment.checkout_page_opened et payment.redirected_to_callback étaient proposés aussi, et jamais livrés non plus : ce sont des entrées de la chronologie du checkout, enregistrées dans le seul journal des événements de Konsole. Ils ne sont plus proposés. Un endpoint qui en liste déjà un le garde, sans effet, et peut toujours être enregistré avec. Les deux restent visibles dans Événements : vous pouvez toujours auditer un checkout après coup.

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.