Référence API

Référence complète de l'API CaurisFlux

URL de base

Sandbox

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

Production

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_

TIP

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

WARNING

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"

INFO

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", ...}'

TIP

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

Support

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