Webhooks et callbacks

Payfonte envoie des événements webhook vers votre endpoint configuré lorsque l’état d’un paiement change. Utilisez les webhooks comme source de vérité principale pour les résultats de paiement asynchrones.

Adresses IP source des webhooks

Si vous limitez le trafic entrant par adresse IP, ajoutez à votre liste d’autorisation les adresses IP source Payfonte suivantes pour chaque environnement.

Environnement	Adresses IP source
Production	`49.13.133.127`, `49.13.229.61`, `194.32.79.135`
Sandbox	`49.12.224.228`, `49.13.224.113`

Pourquoi les webhooks sont importants

Mises à jour en temps réel

Recevez l’état des paiements sans interroger chaque transaction en continu.

Finalisation fiable

Confirmez le statut final, success ou failed, avant d’exécuter une commande.

Sécurité opérationnelle

Gérez les retries de manière idempotente pour éviter les doubles traitements.

Champs du payload webhook

Champ	Description
`event`	Type d’événement, par exemple `payment.completed`
`clientId`	Votre identifiant client Payfonte
`data.status`	Statut de transaction, `success`, `failed` ou `pending`
`data.reference`	Référence de transaction Payfonte
`data.externalReference`	Référence fournie par le marchand, si elle existe
`data.amount`	Montant de transaction en sous-unités
`data.charge`	Frais de transaction appliqués
`data.provider`	Slug ou nom du provider utilisé
`data.channel`	Canal de paiement, par exemple `card` ou `mobile-money`
`data.user`	Métadonnées client, nom, e-mail, téléphone si disponibles

Exemple de payload :

payment.completed

{
  "clientId": "solara_textiles",
  "data": {
    "amount": 74250,
    "channel": "mobile-money",
    "charge": 1856,
    "clientId": "solara_textiles",
    "completedAt": "2026-05-08T09:24:51.127Z",
    "country": "SN",
    "currency": "XOF",
    "externalReference": "ord_8473926150",
    "id": "7f24c91a6b8e45d2f1309c7a",
    "locale": "en",
    "metadata": {},
    "paidAt": 1778232291,
    "paymentReference": "PF20260508092451QZRM4",
    "platformReference": "7f24c91a6b8e45d2f1309c7a",
    "provider": "wave-senegal",
    "reference": "PF20260508092451QZRM4",
    "status": "success",
    "statusDescription": "succeeded",
    "user": {
      "phoneNumber": "221771234589"
    }
  },
  "deliveryId": "7f24c923bb1d0e4a9c8156fd",
  "event": "payment.completed",
  "reference": "PF20260508092451QZRM4",
  "webhook": "https://merchant.example.com/webhooks/payfonte?client_id=solara_textiles"
}

Vérification de signature, obligatoire

Chaque webhook inclut :

L’en-tête x-webhook-signature
Une valeur HMAC sha512 du corps brut de la requête, signée avec votre client-secret

Utilisez votre client-secret depuis Settings -> Security -> API Keys and Webhooks.

const crypto = require("crypto");

app.post("/payfonte/webhook", express.json({ type: "*/*" }), (req, res) => {
  const secret = process.env.PAYFONTE_CLIENT_SECRET;
  const payload = JSON.stringify(req.body);
  const expected = crypto
    .createHmac("sha512", secret)
    .update(payload)
    .digest("hex");
  const received = req.headers["x-webhook-signature"];

  if (expected !== received) {
    return res.status(401).send("Invalid signature");
  }

  // Acquittez rapidement puis traitez de façon asynchrone.
  res.status(200).send("OK");
  processWebhook(req.body);
});

Si la validation de signature échoue, ne traitez pas l’événement.

Modèle de traitement idempotent

Répondre rapidement

Retournez un HTTP 200 rapidement afin d’éviter des retries inutiles.

Détecter les doublons

Utilisez reference + status, ou un identifiant de livraison si disponible, pour identifier les événements déjà traités.

Vérifier la transaction si nécessaire

Pour les flux critiques, vérifiez le statut du paiement depuis votre backend avant la finalisation.

Appliquer la transition d'état sans risque

Garantissez que les actions métier, comme l’exécution de commande, ne s’exécutent qu’une fois par succès final.

Priorité des URL webhook

Payfonte utilise les URL webhook dans cet ordre :

L’URL passée dans la requête checkout ou direct-charge via webhook
L’URL webhook configurée sur l’intégration provider
L’URL webhook configurée dans les paramètres du dashboard

Problèmes fréquents

Problème	Cause probable	Correctif
Traitement webhook en double	Pas de garde idempotente	Stockez `reference` + `status` déjà traités et ignorez les répétitions
Signature invalide	Mauvais secret ou corps modifié	Utilisez le bon `client-secret` et hashez le corps exact reçu
Mises à jour manquées	Timeout de l’endpoint ou réponse non 200	Répondez vite avec `200` et déplacez la logique lourde vers un worker asynchrone
Événements du mauvais environnement	Configuration sandbox et production mélangée	Utilisez les bons endpoints et identifiants pour chaque environnement

Documentation associée

Checkout standard

Flux par redirection avec finalisation webhook.

API Direct Charge

Flux de direct charge et gestion des actions.

Autorisation

Exigences sur les identifiants et les en-têtes.

Premiers pas

Concepts clés

Prestataires et couverture

Développement

Encaisser des paiements

Décaissements

Webhooks et callbacks

Adresses IP source des webhooks

Pourquoi les webhooks sont importants

Mises à jour en temps réel

Finalisation fiable

Sécurité opérationnelle

Champs du payload webhook

Vérification de signature, obligatoire

Modèle de traitement idempotent

Priorité des URL webhook

Problèmes fréquents

Documentation associée

Checkout standard

API Direct Charge

Autorisation

​Adresses IP source des webhooks

​Pourquoi les webhooks sont importants

Mises à jour en temps réel

Finalisation fiable

Sécurité opérationnelle

​Champs du payload webhook

​Vérification de signature, obligatoire

​Modèle de traitement idempotent

​Priorité des URL webhook

​Problèmes fréquents

​Documentation associée

Checkout standard

API Direct Charge

Autorisation

Adresses IP source des webhooks

Pourquoi les webhooks sont importants

Champs du payload webhook

Vérification de signature, obligatoire

Modèle de traitement idempotent

Priorité des URL webhook

Problèmes fréquents

Documentation associée