Intégration des Webhooks

Configuration initiale

1. Configurer l'URL du webhook

Pour configurer votre URL de webhook :

Connectez-vous au Dashboard Business
Naviguez vers Paramètres > API & Webhooks
Entrez votre URL de webhook (doit être HTTPS)
Copiez votre secret webhook (nécessaire pour vérifier les signatures)

Important : Votre endpoint webhook doit :

Utiliser HTTPS
Être accessible publiquement
Retourner un code de statut HTTP 2xx (le délai d'attente est de 5 secondes, voir Comportement des webhooks)

2. Créer votre endpoint webhook

Votre endpoint doit :

Accepter les requêtes POST
Vérifier la signature HMAC-SHA256
Traiter le payload JSON
Retourner un code HTTP 200 pour confirmer la réception

Structure du payload

TRANSACTION_COMPLETED est la transaction elle-même, sans enveloppe ni champ event :

{
    "id": "txn_1234567890",
    "amount": {
      "amount": 10000,
      "currency": "XOF"
    },
    "fees": {
      "amount": 100,
      "currency": "XOF"
    },
    "status": "success",
    "counterpartLabel": "John Doe",
    "counterpartIdentifier": "+2250701234567",
    "paymentMethod": "wave",
    "transactionType": "PaymentRequest",
    "businessName": "Ma Boutique",
    "storeName": "Magasin Principal",
    "description": "Payment for order #12345",
    "executedAt": "2024-01-15 14:30:25",
    "transactionDetails": {
      "id": "d22c81f3-ee04-4ec5-8bd2-cd8af5dabcfc",
      "reference": "PAY-2024-001",
      "paymentLinkId": "abc123def456"
    }
  }

Les Service Providers réutilisent l'URL d'entreprise () pour une demande de rattachement. Jèko POSTe une enveloppe { "event": "SERVICE_PROVIDER_LINK_REQUEST", "payload": { "id", "status", "merchantBusinessId", … } }, signée avec Jeko-Signature. Ce n'est pas le payload transaction plat ci-dessus. Un abonnement events: ["TRANSACTION_COMPLETED"] ne la reçoit pas ; events: null (défaut) la reçoit. Les webhooks magasin ne la reçoivent pas. Voir Rattacher un marchand déjà inscrit.

Quand le webhook est envoyé

Il n'existe qu'un seul webhook transaction. Il est envoyé lorsque :

Une transaction de paiement est complétée avec succès
Une transaction de transfert est complétée avec succès
Une transaction de transfert échoue

Champs du payload

Champ	Type	Description
`id`	string	Identifiant unique de la transaction
`amount`	MoneyModel	Montant de la transaction
`fees`	MoneyModel	Frais de la transaction
`status`	string	Statut de la transaction (`pending`, `success` ou `error`)
`counterpartLabel`	string	Nom du contrepartie (client ou bénéficiaire)
`counterpartIdentifier`	string	Identifiant du contrepartie (numéro de téléphone, etc.)
`paymentMethod`	string	Méthode de paiement utilisée (wave, orange, mtn, moov, djamo, bank)
`transactionType`	string	Type de transaction (`PaymentRequest`)
`businessName`	string	Nom de l'entreprise
`storeName`	string	Nom du magasin
`description`	string	Description de la transaction
`executedAt`	string	Date d'exécution de la transaction, au format `YYYY-MM-DD HH:mm:ss`
`transactionDetails`	object	Détails supplémentaires de la transaction
`transactionDetails.id`	string?	ID de la demande de paiement ou du transfert (optionnel)
`transactionDetails.reference`	string?	Référence de la transaction (optionnel)
`transactionDetails.paymentLinkId`	string?	ID du lien de paiement si applicable (optionnel)

Types de transactions

Le champ transactionType vaut "PaymentRequest".

Ne le confondez pas avec le champ type de l'endpoint , qui vaut payment ou transfer : ce sont deux modèles différents.

Statuts de transaction

Le champ status indique le statut :

"pending" : Transaction en cours de traitement
"success" : Transaction réussie
"error" : Transaction échouée

Vérification de la signature

Tous les webhooks sont signés avec HMAC-SHA256. Vous devez vérifier la signature pour authentifier la requête.

Algorithme de vérification

L'en-tête Jeko-Signature contient le HMAC-SHA256 du corps brut, encodé en hexadécimal minuscule, sans préfixe ni horodatage : a3f5c9…, et rien d'autre.

Récupérez l'en-tête Jeko-Signature
Calculez le HMAC-SHA256 du corps de la requête (raw body) avec votre secret webhook
Comparez la signature calculée avec celle reçue

Important : Utilisez le corps de la requête brut (raw body), pas le JSON parsé.

Exemples d'intégration

Consultez Exemples de code pour des implémentations complètes dans différents langages.

Bonnes pratiques

Vérifiez toujours la signature : Ne traitez jamais un webhook sans vérifier sa signature
Idempotence : Traitez les webhooks de manière idempotente (évitez les traitements en double)
Réponse rapide : Accusez réception sans attendre la fin de votre traitement. Le délai d'attente est de 5 secondes, au-delà le webhook est réessayé
Logging : Enregistrez tous les webhooks reçus pour le débogage
Gestion d'erreurs : Gérez les erreurs gracieusement et retournez toujours un code HTTP approprié

Consultez Bonnes pratiques pour plus de détails.

On this page