Conventions communes
Ce chapitre vaut pour toutes les routes des parcours particulier et entreprise. Il suffit de le lire une fois.
Adresses de l'API
| Environnement | Adresse de base |
|---|---|
| Production | https://api.kratospay.com/api/v1 |
| Recette (staging) | https://dev-aggregator-api.kratospay.com/api/v1 |
Tous les chemins de cette documentation sont relatifs à cette adresse de base (exemple : POST /transactions devient POST https://api.kratospay.com/api/v1/transactions). Les corps sont en JSON (Content-Type: application/json, Accept: application/json).
Deux types d'authentification
| Type | Pour quoi faire | Comment l'envoyer |
|---|---|---|
| Jeton de session (dashboard) | Gérer son compte : profil, applications, clés API, KYC, liens de paiement, solde, retraits. | Authorization: Bearer {token}, obtenu à la connexion. |
Clé API (sk_test_… / sk_live_…) | Intégrer les paiements dans votre serveur : créer, suivre, annuler ou rembourser une transaction, et gérer les points QR GIMAC. | Authorization: Bearer sk_live_… (ou en-tête X-Api-Key), plus X-Application-ID: {id de votre application}. |
La clé API ne doit jamais être placée dans une application mobile ou un navigateur : elle peut encaisser et rembourser. Gardez-la sur votre serveur.
sk_test_…: environnement de test, réseaux simulés, aucun argent réel.sk_live_…: vrais paiements.- La clé n'est affichée qu'une seule fois, à sa création. Perdue, elle se révoque et se régénère.
Format des réponses
{
"success": true,
"data": {},
"meta": {
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-11-02T10:30:00Z"
}
}{
"success": false,
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Solde insuffisant.",
"details": {
"amount": [
"Le montant dépasse le solde disponible."
]
}
},
"meta": {
"request_id": "...",
"timestamp": "..."
}
}error.details n'est présent que pour les erreurs de validation (422) : une entrée par champ fautif, chacune avec la liste de ses messages. Communiquez le meta.request_id au support en cas de problème.
Codes HTTP
| HTTP | Signification | Que faire |
|---|---|---|
| 200 / 201 / 202 | Succès (201 = ressource créée, 202 = traitement accepté, en cours). | — |
| 401 | Jeton ou clé API absent, invalide, expiré ou révoqué. | Se reconnecter / vérifier la clé et son environnement. |
| 403 | Action réservée (ex. fonction réservée aux entreprises, permission d'équipe manquante). | Vérifier le type de compte et les droits. |
| 404 | Ressource introuvable ou appartenant à un autre compte (jamais 403 dans ce cas). | Vérifier l'identifiant. |
| 422 | Données invalides ou règle métier refusée (solde, KYC, réseau indisponible…). | Lire error.code et error.details. |
| 429 | Trop de requêtes. | Réessayer après une courte attente. |
| 5xx | Incident côté Kratos Pay ou réseau de paiement. | Réessayer ; ne jamais créer deux fois la même opération sans clé d'idempotence. |
Réseaux de paiement et numéros
Valeur de provider | Réseau | Encaissement | Envoi / retrait | Remboursement |
|---|---|---|---|---|
orange_money_cm | Orange Money Cameroun | Oui | Oui | Oui |
mtn_momo_cm | MTN Mobile Money Cameroun | Oui | Oui | Non |
mastercard | Cartes Mastercard et Visa (page de paiement sécurisée) | Oui | Non | Non |
gimac | QR GIMAC (paiement par scan) | Oui | Non | Non |
- La liste à jour des valeurs acceptées s'obtient par
GET /payment-providers(jeton de session). Recopiez la valeurselectortelle quelle. Pour Mastercard comme pour Visa, le champproviderrestemastercard. - Pour Mobile Money, envoyez le numéro sans indicatif (
696246686) et correspondant au pays du réseau ; la carte bancaire ne requiert pas de numéro. - Montants : envoyez un nombre (
5000). Les réponses renvoient les montants en chaîne avec deux décimales ("5000.00"). Devise par défaut :XAF. - Les paiements Mobile Money et carte sont asynchrones (
pending) ; attendez le webhook ou consultez la transaction. Un paiement QR GIMAC reçu crée directement une transactionsuccess.
Idempotence
Sur toute création d'argent, envoyez un idempotency_key unique par opération métier (ex. numéro de commande). Si votre appel échoue sur un timeout et que vous le renvoyez avec la même clé, vous recevez la transaction déjà créée au lieu d'en créer une seconde. Une clé déjà utilisée par une autre opération est refusée en 422.