Passer au contenu principal
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.

​
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

ChampDescription
eventType d’événement, par exemple payment.completed ou payment.failed
clientIdVotre identifiant client Payfonte
data.statusStatut de transaction, success, failed ou pending
data.referenceRéférence de transaction Payfonte
data.externalReferenceRéférence fournie par le marchand, si elle existe
data.amountMontant de transaction en sous-unités
data.chargeFrais de transaction appliqués
data.providerSlug ou nom du provider utilisé
data.channelCanal de paiement, par exemple card ou mobile-money
data.userMétadonnées client, nom, e-mail, téléphone si disponibles
Exemple de payload :
payment.completed
{
  "event": "payment.completed",
  "clientId": "payfonte",
  "data": {
    "clientId": "payfonte",
    "reference": "ORDER-1001",
    "externalReference": "ORDER-1001",
    "platformReference": "644ec09c4c2604002fac9d17",
    "amount": 10000,
    "provider": "mtn-momo-nigeria",
    "channel": "mobile-money",
    "status": "success",
    "charge": 0,
    "chargeFee": 0,
    "user": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "paidAt": 1682883430
  }
}

​
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 -> API Keys/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

1

Répondre rapidement

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

Détecter les doublons

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

Vérifier la transaction si nécessaire

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

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 :
  1. L’URL passée dans la requête checkout ou direct-charge via webhook
  2. L’URL webhook configurée sur l’intégration provider
  3. L’URL webhook configurée dans les paramètres du dashboard

​
Problèmes fréquents

ProblèmeCause probableCorrectif
Traitement webhook en doublePas de garde idempotenteStockez reference + status déjà traités et ignorez les répétitions
Signature invalideMauvais secret ou corps modifiéUtilisez le bon client-secret et hashez le corps exact reçu
Mises à jour manquéesTimeout de l’endpoint ou réponse non 200Répondez vite avec 200 et déplacez la logique lourde vers un worker asynchrone
Événements du mauvais environnementConfiguration sandbox et production mélangéeUtilisez 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.