Ce guide explique les concepts essentiels pour intégrer l’API CaurisFlux.
Transaction Une transaction représente un mouvement de fonds. Chaque transaction possède :
Un identifiant unique (transaction_id)
Un type : payment (entrée de fonds) ou payout (sortie de fonds)
Un statut indiquant son état actuel
Un montant et une devise
Paiement (Payment) Un paiement est une transaction entrante : votre client vous verse de l’argent.
Cycle de vie d’un paiement :
Vous initiez un paiement via l’API
Le client valide sur son Mobile Money
Les fonds sont transférés vers votre compte CaurisFlux
Vous recevez un webhook de confirmation
Virement (Payout) Un payout est une transaction sortante : vous envoyez de l’argent vers un compte Mobile Money.
Usage courant :
Remboursements
Paiement de fournisseurs
Transferts vers des bénéficiaires
Statuts de paiement Liste des statuts Statut Description Final ? pendingPaiement initié, en attente de confirmation Non processingPaiement en cours de traitement par le provider Non successPaiement confirmé, fonds reçus Oui failedPaiement échoué Oui cancelledPaiement annulé par le client ou expiré Oui expiredSession de paiement expirée avant validation Oui
Transitions de statut Quand agir selon le statut Statut Action recommandée pendingAfficher une page d’attente au client processingIndiquer que le paiement est en cours successConfirmer la commande, déclencher la livraison failedAfficher l’erreur, proposer de réessayer cancelledProposer de recommencer le paiement expiredCréer une nouvelle session de paiement
Vérification du statut Webhook Un webhook est une notification HTTP envoyée par CaurisFlux vers votre serveur lorsqu’un événement se produit.
Caractéristiques :
Méthode : POST
Format : JSON
Authentification : Signature HMAC-SHA256
Retry automatique en cas d’échec
Structure d’un webhook : Événements disponibles : Événement Description payment.successPaiement réussi payment.failedPaiement échoué payment.pendingPaiement en attente payment.expiredSession expirée payout.successVirement envoyé payout.failedVirement échoué refund.successRemboursement effectué
Environnements Sandbox (Test)
URL : https://sandbox.cauris-pay.com/v1Clés : sk_test_* / pk_test_*Usage : Développement et tests
Caractéristiques :
Aucun mouvement de fonds réel
Numéros de test pour simuler différents scénarios
Webhooks fonctionnels (vers vos endpoints de test)
Production
URL : https://prod-api.caurisflux.com/api/v1Clés : sk_live_* / pk_live_*Usage : Transactions réelles
Caractéristiques :
Mouvements de fonds réels
Requiert un compte vérifié (KYC)
Suivi complet dans le Dashboard
Clés API Clé secrète (Secret Key)
Préfixe : sk_test_ ou sk_live_
Usage : Côté serveur uniquement
Permissions : Toutes les opérations API
Ne jamais exposer les clés API côté client (navigateur, app mobile).
Clé publique (Public Key)
Préfixe : pk_test_ ou pk_live_
Usage : Côté client (si applicable)
Permissions : Limitées (widgets, checkout)
Montants et devises Les montants sont toujours exprimés en unités entières de la devise (pas de décimales).
Montant affiché Valeur API 5 000 XOF 5000100 000 XOF 1000001 500 XAF 1500
Devises supportées Code Nom Zone XOFFranc CFA BCEAO UEMOA (Sénégal, Côte d’Ivoire, Mali, etc.) XAFFranc CFA BEAC CEMAC (Cameroun, etc.)
Limites de montant Les limites varient selon le provider et le pays. Consultez le guide Mobile Money pour les détails.
Paramètre Valeur typique Montant minimum 100 Montant maximum 1 000 000 - 2 000 000
Référence marchand (merchant_reference) Identifiant que vous attribuez à la transaction pour la lier à votre système.
Bonnes pratiques :
Utilisez un identifiant unique (numéro de commande)
Stockez-le dans votre base de données
Utilisez-le pour réconcilier les paiements
Données personnalisées que vous pouvez attacher à une transaction. Elles sont retournées dans les webhooks.
Les metadata ne sont pas validées par CaurisFlux. Vous pouvez y stocker n’importe quelle donnée JSON.
Idempotence L’API supporte les clés d’idempotence pour éviter les doublons lors de retries.
Si vous répétez la même requête avec la même clé d’idempotence, l’API retourne le résultat de la première requête sans créer de doublon.
Prochaines étapes
Flux d'intégration Cycle de vie complet d’un paiement
Gestion des erreurs Codes d’erreur et résolution
