Webhooks
Configurez vos endpoints webhook et vérifiez les livraisons de manière sécurisée.
Genuka Pay notifie votre backend des changements d'état des paiements (et du module Abonnements) par des requêtes HTTP signées.
Headers requis
Les requêtes de gestion d’endpoints webhook doivent inclure :
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATUREFlux recommandé
Les webhooks doivent être gérés depuis le dashboard Genuka Pay, via la page Webhooks.
Ce flux permet à votre équipe :
- de créer des endpoints
- de choisir les événements
- d’activer ou désactiver les endpoints
- d’inspecter quelques métadonnées de livraison
- de régénérer le secret
Utilisez l’API ci-dessous seulement pour l’automatisation ou l’outillage interne.
API de gestion
GET /api/v1/webhook-endpointsPOST /api/v1/webhook-endpointsGET /api/v1/webhook-endpoints/{id}PUT /api/v1/webhook-endpoints/{id}(ouPATCH)DELETE /api/v1/webhook-endpoints/{id}POST /api/v1/webhook-endpoints/{id}/regenerate-secretPOST /api/v1/webhook-endpoints/{id}/test
Le secret de signature est renvoyé à la création, à la lecture d'un endpoint et à sa régénération, jamais dans la liste. POST /{id}/test envoie un événement webhook.test signé et formé exactement comme une vraie livraison : il permet de tester votre vérification de signature.
Créer un endpoint
curl -X POST "https://api-pay.genuka.com/api/v1/webhook-endpoints" \
-H "X-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Timestamp: UNIX_TIMESTAMP" \
-H "X-Signature: HMAC_SHA256_SIGNATURE" \
-H "Content-Type: application/json" \
-d '{
"name": "Backend de production",
"target_url": "https://merchant.example.com/webhooks/genuka",
"events": [
"transaction.success",
"transaction.failed",
"transaction.processing"
],
"is_active": true
}'Événements disponibles
transaction.successtransaction.failedtransaction.processingpayout.successpayout.failedpayout.processingpayout.cancelledkyc.submittedkyc.approvedkyc.rejectedcompany.suspendedcompany.reactivated
Événements réellement émis
Aujourd'hui, seuls transaction.success, transaction.failed et transaction.processing (ainsi que les événements d'abonnement) sont envoyés. payout.*, kyc.*, company.suspended et company.reactivated sont acceptés à l'abonnement d'un endpoint mais ne sont pas encore émis : ne bâtissez pas de logique qui les attend. Les payouts se suivent par GET /api/v1/payouts/{id}.
transaction.refunded et company.created ne peuvent plus être choisis : Genuka Pay n'a pas de remboursement, et une entreprise existe avant ses endpoints. Un endpoint déjà abonné les garde, sans jamais les recevoir.
Les événements transaction.* concernent les encaissements : paiements API, checkout hébergé et liens de collecte.
Les événements des abonnements (customer.*, subscription.*, invoice.*) sont décrits dans Webhooks d'abonnement.
Forme du payload
{
"id": "01HW...",
"event": "transaction.success",
"timestamp": "2026-09-19T12:10:00.000000Z",
"data": {
"transaction_id": "01HR...",
"idempotency_key": "...",
"amount": 10000,
"net_amount": 9575,
"provider_fee_amount": 150,
"genuka_fee_amount": 275,
"total_fee_amount": 425,
"currency": "XOF",
"status": "SUCCESS",
"completed_at": "2026-09-19T12:10:00.000000Z",
"metadata": { "external_id": "order_10001" }
}
}Retrouvez votre propre référence dans data.metadata.external_id, celle que vous avez envoyée à l'initiation. Pour un paiement fait via un checkout hébergé, data.metadata est le metadata de la session.
data.transaction_id est l'id du paiement. Les événements transaction.success et transaction.failed ne contiennent pas de track_id : rapprochez-les par transaction_id, idempotency_key ou metadata.external_id.
transaction.failed
{
"id": "01HW...",
"event": "transaction.failed",
"timestamp": "2026-09-19T12:10:00.000000Z",
"data": {
"transaction_id": "01HR...",
"idempotency_key": "order_10001",
"status": "FAILED",
"reason": "Solde insuffisant",
"failure": { "code": "INSUFFICIENT_FUNDS", "message": "Solde insuffisant" },
"details": { "...": "..." },
"failed_at": "2026-09-19T12:10:00.000000Z",
"metadata": { "external_id": "order_10001" }
}
}failure.code vaut l'un de : INSUFFICIENT_FUNDS, INCORRECT_PIN, INVALID_PAYER, LIMIT_EXCEEDED, ACCOUNT_RESTRICTED, PAYMENT_DECLINED, PAYMENT_EXPIRED, PROVIDER_ERROR, UNKNOWN. failure.message est rédigé pour être montré à votre client.
transaction.processing
{
"id": "01HW...",
"event": "transaction.processing",
"timestamp": "2026-09-19T12:09:30.000000Z",
"data": {
"transaction_id": "01HR...",
"status": "PROCESSING",
"provider_reference": "...",
"track_id": "JK-01k7c4t9m2y8x5b3n6q0r1s2t4",
"processing_at": "2026-09-19T12:09:30.000000Z"
}
}Envoyé quand la demande est transmise à l'opérateur, sauf si l'issue finale est déjà connue.
Headers envoyés :
Signature— HMAC-SHA256 de la requête, voir ci-dessousX-Webhook-IdX-Webhook-Event
Livraison et nouvelles tentatives
- Méthode
POST, corps JSON,Content-Type: application/json. - Délai de réponse : 3 secondes. Toute réponse hors
2xx, ou l'absence de réponse, déclenche une nouvelle tentative. - 3 tentatives au total, espacées de façon exponentielle. Au-delà, la livraison est abandonnée : prévoyez une réconciliation par polling.
- L'ordre d'arrivée n'est pas garanti, et une même livraison peut arriver deux fois : dédupliquez sur
id(aussi dansX-Webhook-Id). target_urldoit être une URLhttps://sur un nom de domaine public (500 caractères max).- Un endpoint créé avec une clé API appartient à l'environnement de cette clé (
SANDBOXouLIVE).
Vérification de signature
La signature arrive dans le header Signature : un HMAC-SHA256 du corps brut de la requête, avec le secret de l’endpoint.
import crypto from "crypto";
// rawBody : le corps de la requête tel que reçu, avant tout parsing JSON.
function verifyWebhook(rawBody, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
const received = Buffer.from(signature, "utf8");
const computed = Buffer.from(expected, "utf8");
return (
received.length === computed.length &&
crypto.timingSafeEqual(received, computed)
);
}Signez le corps brut, pas l’objet reparsé
Re-sérialiser le JSON après l’avoir parsé change les espaces et l’ordre des clés : la signature ne correspondra plus. Gardez le corps brut (express.raw(), request.body non parsé) pour la vérification. Comparez aussi en temps constant, et rejetez toute livraison non signée.
Rotation du secret
curl -X POST "https://api-pay.genuka.com/api/v1/webhook-endpoints/{id}/regenerate-secret" \
-H "X-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Timestamp: UNIX_TIMESTAMP" \
-H "X-Signature: HMAC_SHA256_SIGNATURE"Le nouveau secret doit être stocké immédiatement.
Recommandations
- retournez un
2xxrapidement - poussez le traitement lourd dans une queue
- vérifiez la signature avant traitement
- implémentez l’idempotence côté récepteur
How is this guide?
Last updated on