Webhook

Lorsqu'un évènement se produit sur votre compte KKiaPay, vous pouvez en utilisant les webhooks vous informer sur leur exécution. À ce jour, vous pouvez utiliser les webhooks afin de notifier à votre backend le statut d'une transaction (la transaction est-elle un succès ou un échec).

Configuration des webhooks

Il vous faudra afin de procéder à la configuration de vos webhooks, suivre les étapes ci-après une fois sur le formulaire d'ajout d'un webhook (disponible après clic sur le bouton "Ajouter un webhook", présent dans l'onglet Webhook du sous-menu Clés API de votre tableau de bord) :

1. Inscrire l’URL sur laquelle vous désirez être notifié. Vous pouvez entrer n'importe quelle URL comme destination pour les événements. Toutefois, il doit s'agir d'une page dédiée sur votre serveur, configurée pour recevoir des événements.

2. Choisir les événements pour lesquels vous souhaitez être averti. Vous serez averti uniquement des événements spécifiés.

3. Définir un secret hash. Il sera utilisé afin de vérifier la provenance des informations que vous recevez.

Une fois le callback créé vous pouvez procéder à un test afin de vérifier que KKiaPay contacte bien votre URL.

Gérer les webhooks

Configuration faite, il est important de savoir accuser réception d’un événement après notification de KKiaPay. Pour ce faire, vous devez avant tout utiliser votre URL afin d'identifier le type d’évènement et renvoyer un code statut HTTP 2xx. Tous les codes de réponse en dehors de cette plage, y compris les codes 3xx, indiquent à KKiaPay que vous n'avez pas reçu l'événement.

En cas de non réception, KKiaPay tente 5 fois de suite (dans un intervalle de 500ms incrémentable) de vous renvoyer les informations.

Vérification des signatures webhook

KKiaPay signe les événements webhooks qu’il envoie à vos URL. Il est introduit dans l’en-tête de chaque requête x-kkiapay-secret une signature. Elle est utilisée afin de vous permettre de vérifier que les événements ont été envoyés par KKiaPay et non par un tiers. Le squelette de la requête est le suivant :

curl -H "x-kkiapay-secret: XXX" -H "Content-Type: application/json http://example.com/webhook

Toute requête x-kkiapay-secret utilise le secret hash fourni par votre personne sur le tableau de bord KKiaPay.

Payloads Response Body

À chaque notification d'événement nous vous envoyons un body request au format json ci après :

• Dans le cas d'une transaction échouée

{
    "transactionId": "erjEU5P9o",
    "isPaymentSucces": false,
    "account": "22996000001", // null for card and wave payments,
    "failureCode": "processing_error",
    "failureMessage": "processing_error",
    "label": "...",
    "method": "MOBILE_MONEY", // MOBILE_MONEY | WALLET | CARD,
    "amount": 1000,
    "fees": 19,
    "partnerId": "...",
    "performedAt": "2024-03-20T08:55:22.883Z",
    "stateData": {},
    "event": "transaction.failed"
}

• Dans le cas d'une transaction réussie

{
  "transactionId": "3iH6wjHJ3",
  "isPaymentSucces": true,
  "account": "22996000000", // null for card and wave payments,
  "label": "...",
  "method": "MOBILE_MONEY", // MOBILE_MONEY | WALLET | CARD,
  "amount": 1000,
  "fees": 19,
  "partnerId": "...",
  "performedAt": "2024-03-20T08:55:22.883Z",
  "stateData": {},
  "event": "transaction.success"
}