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

EnvironnementAdresse de base
Productionhttps://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

TypePour quoi faireComment 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

Succès (HTTP 2xx)
{
  "success": true,
  "data": {},
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-11-02T10:30:00Z"
  }
}
Échec (HTTP 4xx/5xx)
{
  "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

HTTPSignificationQue faire
200 / 201 / 202Succès (201 = ressource créée, 202 = traitement accepté, en cours).—
401Jeton ou clé API absent, invalide, expiré ou révoqué.Se reconnecter / vérifier la clé et son environnement.
403Action réservée (ex. fonction réservée aux entreprises, permission d'équipe manquante).Vérifier le type de compte et les droits.
404Ressource introuvable ou appartenant à un autre compte (jamais 403 dans ce cas).Vérifier l'identifiant.
422Données invalides ou règle métier refusée (solde, KYC, réseau indisponible…).Lire error.code et error.details.
429Trop de requêtes.Réessayer après une courte attente.
5xxIncident 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 providerRéseauEncaissementEnvoi / retraitRemboursement
orange_money_cmOrange Money CamerounOuiOuiOui
mtn_momo_cmMTN Mobile Money CamerounOuiOuiNon
mastercardCartes Mastercard et Visa (page de paiement sécurisée)OuiNonNon
gimacQR GIMAC (paiement par scan)OuiNonNon
  • La liste à jour des valeurs acceptées s'obtient par GET /payment-providers (jeton de session). Recopiez la valeur selector telle quelle. Pour Mastercard comme pour Visa, le champ provider reste mastercard.
  • 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 transaction success.

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.