Documentation Index
Fetch the complete documentation index at: https://docs.caurisflux.com/llms.txt
Use this file to discover all available pages before exploring further.
Les webhooks sont des notifications HTTP envoyées par CaurisFlux vers votre serveur lorsqu’un événement se produit.
Les webhooks sont essentiels pour une intégration fiable. Ne vous fiez pas uniquement aux redirections.
Configuration
- Allez dans Dashboard > Paramètres > Webhooks
- Cliquez sur Ajouter un endpoint (HTTPS requis en production)
- Sélectionnez les événements à recevoir
- Copiez le secret de signature
Événements
| Événement | Description |
|---|
payment.completed | Paiement réussi |
payment.failed | Paiement échoué |
payment.cancelled | Paiement annulé |
payment.expired | Paiement expiré |
payout.completed | Payout réussi |
payout.failed | Payout échoué |
payout.cancelled | Payout annulé |
refund.completed | Remboursement effectué |
Structure
| Header | Description |
|---|
X-Cauris-Signature | Signature HMAC (format: sha256=xxx) |
X-Cauris-Timestamp | Timestamp Unix de l’envoi |
Content-Type | application/json |
Exemples de payload
{
"event": "payment.completed",
"timestamp": "2024-01-15T12:05:30.000Z",
"data": {
"transactionId": "TX000007272",
"status": "completed",
"amount": 10000,
"currency": "XOF",
"fees": 150,
"netAmount": 9850,
"provider": "wave",
"providerReference": "WAVE-TXN-123456",
"externalReference": "COMMANDE-12345",
"customerPhone": "+221771234567",
"customerName": "Amadou Diallo",
"paidAt": "2024-01-15T12:05:30.000Z",
"metadata": {
"orderId": "12345"
}
}
}
Vérification de la signature
Vérifiez toujours la signature pour éviter les faux webhooks.
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
// Dans votre handler Express
app.post('/webhooks/cauris', (req, res) => {
const signature = req.headers['x-cauris-signature'];
const isValid = verifyWebhook(
JSON.stringify(req.body),
signature,
process.env.WEBHOOK_SECRET
);
if (!isValid) {
return res.status(401).send('Invalid signature');
}
// Répondre immédiatement
res.status(200).send('OK');
// Traiter en arrière-plan
processWebhook(req.body);
});
Codes d’erreur
Paiements
| Code | Description |
|---|
insufficient_funds | Solde insuffisant |
user_cancelled | Annulé par l’utilisateur |
timeout | Délai expiré |
provider_error | Erreur du provider |
invalid_phone | Numéro invalide |
Payouts
| Code | Description |
|---|
invalid_recipient | Bénéficiaire invalide |
insufficient_balance | Solde insuffisant (votre compte) |
provider_error | Erreur du provider |
limit_exceeded | Limite dépassée |
account_blocked | Compte bloqué |
Retries
Si votre serveur ne repond pas 2xx, CaurisFlux réessaie :
| Tentative | Délai |
|---|
| 1 | Immédiat |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 heures |
Après 5 tentatives, le webhook est marqué comme non livré.
Bonnes pratiques
Répondez en < 5 secondes
Retournez 200 OK immédiatement, traitez en arrière-plan.
Idempotence
Stockez les transactionId / payoutId traités pour éviter les doublons.
HTTPS obligatoire
Votre endpoint doit être en HTTPS avec un certificat valide.
Loggez tout
Conservez les webhooks reçus pour debug et audit.
Tester
Depuis le Dashboard : Webhooks > Envoyer un test
Ou utilisez les numéros de test en sandbox pour déclencher des webhooks réels.