Les webhooks sont des notifications HTTP POST envoyées à votre URL configurée lorsque le statut d'un paiement entrant ou d'un transfert sortant change sur notre plateforme.

Pour assurer l'intégrité et l'authenticité des données envoyées, le payload de chaque webhook sera signé avec la clé secrète, accessible depuis l'espace développeur.

Le résultat de la signature est placé dans l'entête X-Webhook-Signature de la requête. Se référer à la rubrique ###Comment générer une signature, obtenir des snippet de code. Si la signature fournie dans la requête correspod au résultat de votre sugnature, alors poursuivre le traitement du webhook. Le cas échéant, ignorer le webhook.

Format de l'entête : X-Webhook-Signature: v1:signature

Types d'événements

Versions du payload

La version est portée par votre configuration webhook, accessible depuis l'espace développeur. Seule la structure du champ data change : l'enveloppe (message, eventType, eventId, data, timestamp) et la signature sont identiques dans les deux versions.

Les nouvelles configurations sont créées en V2. Les marchands déjà intégrés restent en V1 tant qu'ils n'ont pas demandé la migration : les événements payout.* ne sont donc pas envoyés en V1.

En V2, un seul des deux objets est présent par webhook — data.payment sur un événement payment.*, data.payout sur un événement payout.*. L'autre clé est absente du payload, elle n'est pas envoyée vide.

⚠️ Important : Cette documentation décrit les webhooks envoyés À votre système. Vous devez implémenter cet endpoint côté client pour recevoir nos notifications.

Signature HMAC-SHA256 du payload,  générée avec la clé secrète du marchand (clientSecret) pour vérifier l'authenticité de la requête

Ce champs optionnel, contient des informations envoyées par le marchand à la création/initialisation d'un paiement ou la génération d'un lien
- Il est au format JSON et ne conteient ni de list, ni de structure imbriquée
- Ex : { "order_id": "ORD-456", "vip": true, "referrer": "campaign-2026" }

{
  "message": "Statut du paiement",
  "eventType": "payment.success",
  "data": {
    "payment": {
      "transactionId": "123e4567-e89b-12d3-a456-426614174000",
      "status": "SUCCESS",
      "paidAmount": 100,
      "fees": 3,
      "paymentMethod": "OM",
      "payerIdentifier": "00224626241509",
      "currency": "GNF",
      "createdAt": "2025-07-13T10:30:00Z"
    },
    "payout": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "orderId": "123e4567-e89b-12d3-a456-426614174044",
      "merchantPayoutReference": "PR001",
      "providerReference": "PR001",
      "status": "SUCCESS",
      "destination": {
        "type": "WALLET",
        "countryCode": "GN",
        "currency": "GNF",
        "account": {
          "providerCode": "OM",
          "accountNumber": "622000000"
        }
      },
      "amount": 150000,
      "feesAmount": 2000,
      "totalAmountToPay": 170000,
      "createdAt": "2025-07-13T10:30:00Z"
    }
  }
}