Ce guide vous accompagne dans la création de votre premier paiement, de la configuration initiale à la réception du webhook de confirmation.
1. Obtenir vos clés API
Accéder aux clés API
Dans le Dashboard, allez dans Paramètres > Clés API
Copier les clés de test
Vous trouverez deux types de clés :
pk_test_* : Clé publiquesk_test_* : Clé secrète (côté serveur uniquement)
Ne partagez jamais vos clés secrètes (sk_*). Elles donnent un accès complet à votre compte.
2. Comprendre les environnements
| Environnement | Préfixe des clés | URL de base | Usage |
|---|
| Sandbox | pk_test_ / sk_test_ | https://sandbox-api.caurisflux.com/api/v1 | Développement et tests |
| Production | pk_live_ / sk_live_ | https://prod-api.caurisflux.com/api/v1 | Transactions réelles |
3. Récupérer les méthodes de paiement disponibles
Avant d’initier un paiement, récupérez les méthodes disponibles pour le pays via GET /payments/providers?country=SN¤cy=XOF.
Informations retournées par provider :
name : Nom du provider (Wave, Orange Money, etc.)providerCode : Code à utiliser dans l’APIminAmount / maxAmount : Limites de montantcurrencies : Devises supportées
4. Créer un paiement
Option A : Paiement Direct (Mobile Money)
Utilisez cette méthode quand vous connaissez le provider choisi par le client.
Endpoint : POST /payments/initiate
Paramètres requis :
type : directprovider : Code du provider (wave, orange_money, etc.)country : Code pays (SN, CI, etc.)amount : Montant en centimescurrency : Devise (XOF, XAF)customerPhone : Numéro du clientcallbackUrl : URL de votre webhookreturnUrl : URL de redirection après paiement
Réponse :
transactionId : Identifiant unique de la transactionstatus : Statut initial (pending)redirectUrl : URL où rediriger le client
Option B : Paiement Checkout (Page hébergée)
Le client sera redirigé vers la page CaurisFlux pour choisir sa méthode de paiement.
Paramètres :
type : checkout- Pas besoin de spécifier le
provider
5. Rediriger le client
Redirigez l’utilisateur vers l’URL redirectUrl retournée par l’API.
Le client sera redirigé vers une page de paiement où il pourra :
- Confirmer le montant
- Valider le paiement via son application Mobile Money
- Être redirigé vers votre
returnUrl après paiement
6. Recevoir la confirmation par webhook
La redirection vers returnUrl ne garantit pas que le paiement est réussi. Vous devez configurer un webhook pour recevoir la confirmation.
- Dans le Dashboard, allez dans Paramètres > Webhooks
- Cliquez sur Ajouter un endpoint
- Entrez l’URL de votre serveur (ex:
https://votresite.com/webhooks/cauris)
- Sélectionnez les événements à recevoir
- Copiez le Webhook Secret généré
Traiter le webhook
- Vérifier la signature avec le header
x-cauris-signature
- Traiter l’événement selon le type (
payment.completed, payment.failed)
- Répondre rapidement avec un status 200
Événements principaux
| Événement | Description |
|---|
payment.completed | Paiement confirmé et réussi |
payment.failed | Paiement échoué |
payment.expired | Paiement expiré (non complété à temps) |
7. Vérifier le statut d’un paiement
Vous pouvez vérifier le statut via GET /payments/status/:transactionId.
8. Tester avec des numéros de simulation
En sandbox, utilisez ces numéros pour simuler différents scénarios :
| Numéro | Résultat |
|---|
+221770000001 | Paiement réussi |
+221770000010 | Solde insuffisant |
+221770000011 | Transaction refusée |
+221770000020 | Reste en attente (timeout) |
Flux complet
- Client passe commande sur votre site
- Votre serveur appelle
POST /payments/initiate
- CaurisFlux retourne l’URL de redirection
- Client est redirigé vers la page de paiement
- Client valide avec son PIN Mobile Money
- CaurisFlux envoie le webhook de confirmation
- Votre serveur met à jour la commande
- Client est redirigé vers votre page de succès
Prochaines étapes
