GUIDE

Recevoir les webhooks

Yóbbal PAY envoie un POST JSON signé à votre serveur à chaque changement d’état d’un paiement ou d’un remboursement.

1. Déclarer votre adresse

Un administrateur la déclare dans le tableau de bord, menu Webhooks, une fois en TEST et une fois en LIVE. Le LIVE exige HTTPS. Le secret de signature whsec_… s’affiche une seule fois, à la création ou au renouvellement.

2. Les événements

payment.succeeded

Le client a payé. Livrez la commande.

payment.failed

Le paiement a échoué chez l’opérateur.

payment.expired

Pas de paiement dans les 30 minutes.

payment.discrepancy

Écart à vérifier : ne demandez pas au client de repayer.

refund.pending

Remboursement demandé, en attente de l’opérateur.

refund.succeeded

Remboursement confirmé par l’opérateur.

refund.failed

Remboursement refusé. Une nouvelle demande est possible.

3. Vérifier la signature

Lisez YobbalPay-Signature: t=…,v1=….

Calculez le HMAC-SHA256 hexadécimal de t + "." + corps brut avec votre secret. Comparez en temps constant et refusez un horodatage distant de plus de 5 minutes. Dédupliquez avec YobbalPay-Event-Id, stable entre les relances.

4. Relances

Tout statut autre que 2xx, un délai de plus de 10 secondes ou une erreur réseau déclenche une relance. Les délais vont de 1 minute à 24 heures pendant 3 jours, puis la livraison passe en échec. Les redirections ne sont jamais suivies.

Vérifier une signature

import crypto from "node:crypto" // rawBody est le Buffer brut, avant JSON.parse. export function verify(rawBody, header, secret) { const p = Object.fromEntries( header.split(",").map(x => x.split("=", 2)) ) if (!/^\d+$/.test(p.t ?? "")) return false if (Math.abs(Date.now()/1000 - Number(p.t)) > 300) return false if (!/^[a-f0-9]{64}$/i.test(p.v1 ?? "")) return false const expected = crypto .createHmac("sha256", secret) .update(p.t + ".") .update(rawBody) .digest() return crypto.timingSafeEqual( expected, Buffer.from(p.v1, "hex") ) }

Le corps brut doit être conservé avant toute analyse JSON.

Exemple de webhook

YobbalPay-Event-Id: UUID_DE_L_EVENEMENT YobbalPay-Event-Type: payment.succeeded YobbalPay-Signature: t=HORODATAGE,v1=HMAC { "id": "UUID_DE_L_EVENEMENT", "type": "payment.succeeded", "environment": "TEST", "createdAt": "HORODATAGE_ISO", "data": { "payment": { "id": "UUID_DU_PAIEMENT", "status": "SUCCEEDED", "amount": 5000, "amountCharged": 5051, "currency": "XOF", "provider": "wave" } } }

Corps illustratif du contrat, aucune livraison observée dans ce panneau.