Introduction

URL de base

https://sandbox-api.caurisflux.com/api/v1

https://prod-api.caurisflux.com/api/v1

Environnement	URL	Préfixe clés
Sandbox	`https://sandbox-api.caurisflux.com/api/v1`	`pk_test_` / `sk_test_`
Production	`https://prod-api.caurisflux.com/api/v1`	`pk_live_` / `sk_live_`

En mode sandbox, utilisez les clés pk_test_* / sk_test_* et les numéros de test pour simuler des transactions sans argent réel.

Authentification

Toutes les requêtes API doivent inclure vos clés API. Vous avez deux options :

Option 1 : Header X-API-Key (recommandé)

X-API-Key: pk_test_xxx:sk_test_xxx

Option 2 : Bearer Token

Authorization: Bearer pk_test_xxx:sk_test_xxx

Le format est clé_publique:clé_secrète. Les deux clés sont nécessaires pour l’authentification.

Exemple de requête authentifiée

curl https://sandbox-api.caurisflux.com/api/v1/payments/balance \
  -H "X-API-Key: pk_test_xxx:sk_test_xxx" \
  -H "Content-Type: application/json"

Certains endpoints publics (comme /payments/providers ou /countries/active) ne nécessitent pas d’authentification.

Format des requêtes

Content-Type : application/json
Encodage : UTF-8
Méthodes : GET, POST, PUT, DELETE

curl -X POST https://sandbox-api.caurisflux.com/api/v1/payments/initiate \
  -H "X-API-Key: pk_test_xxx:sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "direct",
    "provider": "wave",
    "amount": 5000,
    "currency": "XOF",
    "country": "SN",
    "customerPhone": "+221771234567",
    "externalReference": "ORDER-001"
  }'

Format des réponses

Toutes les réponses sont en JSON avec une structure cohérente :

Réponse réussie

{
  "success": true,
  "data": {
    "transactionId": "TX000007272",
    "status": "pending",
    "amount": 5000,
    "currency": "XOF",
    "redirectUrl": "https://pay.wave.com/c/sn/~abc123",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Réponse d’erreur

{
  "statusCode": 400,
  "message": "Le montant doit être supérieur à 100 XOF",
  "error": "Bad Request"
}

Pagination

Les endpoints qui retournent des listes supportent la pagination :

Paramètre	Description	Défaut	Max
`page`	Numéro de page	1	-
`limit`	Nombre d’éléments par page	20	100

{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}

Codes de statut HTTP

Code	Signification
`200`	Succès
`201`	Ressource créée
`400`	Requête invalide
`401`	Non authentifié
`403`	Non autorisé
`404`	Ressource non trouvée
`422`	Erreur de validation
`429`	Trop de requêtes
`500`	Erreur serveur

Gestion des erreurs

Les erreurs retournent un objet JSON avec les détails :

{
  "statusCode": 400,
  "message": "Le montant doit être supérieur à 100 XOF",
  "error": "Bad Request"
}

Codes d’erreur courants

Code	Description
`insufficient_funds`	Solde insuffisant
`invalid_phone`	Numéro de téléphone invalide
`invalid_amount`	Montant invalide
`provider_error`	Erreur du fournisseur
`limit_exceeded`	Limite dépassée

Rate limiting

Plan	Limite
Standard	100 requêtes/minute
Business	1000 requêtes/minute
Enterprise	Illimité

Les en-têtes de réponse incluent :

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800

Idempotence

Pour éviter les paiements en double, incluez l’en-tête X-Idempotency-Key avec une valeur unique (par exemple, votre ID de commande) :

curl -X POST https://sandbox-api.caurisflux.com/api/v1/payments/initiate \
  -H "X-API-Key: pk_test_xxx:sk_test_xxx" \
  -H "X-Idempotency-Key: ORDER-12345" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "type": "direct", ...}'

Les clés d’idempotence expirent après 24h. Utilisez votre ID de commande comme clé pour garantir l’unicité.

Flux de paiement (Collect)

Récupérer les méthodes → GET /payments/providers
Initier le paiement → POST /payments/initiate
Rediriger le client vers redirectUrl retourné
Recevoir le webhook de confirmation
Vérifier le statut → GET /payments/status/:transactionId

Flux de payout (Décaissement)

Obtenir un devis → POST /payouts/quote
Confirmer le payout → POST /payouts/initiate (avec quoteId)
Recevoir le webhook de confirmation
Vérifier le statut → GET /payouts/status/:payoutId

Le flux quote-based garantit que le marchand connaît le montant exact débité avant de confirmer. Le devis est valide 5 minutes.

Support

Email : integration@caurisflux.com
Documentation : https://docs.caurisflux.com

Référence API

Paiements

Pays et Méthodes

Solde

Payouts (Décaissements)

URL de base

Authentification

Option 1 : Header X-API-Key (recommandé)

Option 2 : Bearer Token

Exemple de requête authentifiée

Format des requêtes

Format des réponses

Réponse réussie

Réponse d’erreur

Codes de statut HTTP

Gestion des erreurs

Codes d’erreur courants

Rate limiting

Idempotence

Flux de paiement (Collect)

Flux de payout (Décaissement)

Support

​URL de base

​Authentification

​Option 1 : Header X-API-Key (recommandé)

​Option 2 : Bearer Token

​Exemple de requête authentifiée

​Format des requêtes

​Format des réponses

​Réponse réussie

​Réponse d’erreur

​Pagination

​Codes de statut HTTP

​Gestion des erreurs

​Codes d’erreur courants

​Rate limiting

​Idempotence

​Flux de paiement (Collect)

​Flux de payout (Décaissement)

​Support

URL de base

Authentification

Option 1 : Header X-API-Key (recommandé)

Option 2 : Bearer Token

Exemple de requête authentifiée

Format des requêtes

Format des réponses

Réponse réussie

Réponse d’erreur

Pagination

Codes de statut HTTP

Gestion des erreurs

Codes d’erreur courants

Rate limiting

Idempotence

Flux de paiement (Collect)

Flux de payout (Décaissement)

Support