Skip to main content

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

  1. Allez dans Dashboard > Paramètres > Webhooks
  2. Cliquez sur Ajouter un endpoint (HTTPS requis en production)
  3. Sélectionnez les événements à recevoir
  4. Copiez le secret de signature

Événements

ÉvénementDescription
payment.completedPaiement réussi
payment.failedPaiement échoué
payment.cancelledPaiement annulé
payment.expiredPaiement expiré
payout.completedPayout réussi
payout.failedPayout échoué
payout.cancelledPayout annulé
refund.completedRemboursement effectué

Structure

Headers

HeaderDescription
X-Cauris-SignatureSignature HMAC (format: sha256=xxx)
X-Cauris-TimestampTimestamp Unix de l’envoi
Content-Typeapplication/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

CodeDescription
insufficient_fundsSolde insuffisant
user_cancelledAnnulé par l’utilisateur
timeoutDélai expiré
provider_errorErreur du provider
invalid_phoneNuméro invalide

Payouts

CodeDescription
invalid_recipientBénéficiaire invalide
insufficient_balanceSolde insuffisant (votre compte)
provider_errorErreur du provider
limit_exceededLimite dépassée
account_blockedCompte bloqué

Retries

Si votre serveur ne repond pas 2xx, CaurisFlux réessaie :
TentativeDélai
1Immédiat
21 minute
35 minutes
430 minutes
52 heures
Après 5 tentatives, le webhook est marqué comme non livré.

Bonnes pratiques

1

Répondez en < 5 secondes

Retournez 200 OK immédiatement, traitez en arrière-plan.
2

Idempotence

Stockez les transactionId / payoutId traités pour éviter les doublons.
3

HTTPS obligatoire

Votre endpoint doit être en HTTPS avec un certificat valide.
4

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.