Vue d'ensemble

Kratos Pay API est la passerelle de paiement de Kratos Financials Inc. Elle permet à n'importe quelle application — boutique en ligne, plateforme SaaS, application mobile — d'encaisser et d'envoyer des paiements Mobile Money, d'accepter les cartes bancaires et les paiements QR GIMAC, puis de suivre les transactions par webhook.

Endpoints Live

Télécharger le guide pour une utilisation hors connexion

Authentification

Les paiements s'appellent depuis votre serveur avec une clé API (sk_test_… en test, sk_live_… en production) et l'identifiant de votre application. Ne placez jamais la clé dans un navigateur ou une application mobile.

Authorization: Bearer sk_live_VOTRE_CLE
X-Application-ID: 1
Content-Type: application/json
Accept: application/json

Champs obligatoires : type, provider, amount, et phone_number pour Mobile Money. Pour les cartes Mastercard et Visa, utilisez provider: "mastercard" ; aucun numéro n'est requis. Ajoutez une idempotency_key unique par opération.

Ouvrir le Swagger pour les intégrations API

Encaissement — collection

Méthode POSThttps://api.kratospay.com/api/v1/transactions

Payload JSON

{
  "type": "collection",
  "provider": "orange_money_cm",
  "amount": 5000,
  "currency": "XAF",
  "phone_number": "696246686",
  "idempotency_key": "commande-1234",
  "metadata": {
    "description": "Commande 1234"
  }
}

Réponse HTTP 201 — demande initiée

{
  "success": true,
  "data": {
    "uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
    "type": "collection",
    "provider": "orange_money",
    "status": "pending",
    "amount": "5000.00",
    "currency": "XAF",
    "reference": "MP240101.1234.A56789",
    "phone_number": "696246686",
    "created_at": "2026-11-02T08:00:00Z",
    "updated_at": "2026-11-02T08:00:00Z"
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Encaissement par carte — Mastercard

Méthode POSThttps://api.kratospay.com/api/v1/transactions

Payload JSON

{
  "type": "collection",
  "provider": "mastercard",
  "amount": 25000,
  "currency": "XAF",
  "idempotency_key": "commande-5678",
  "return_url": "https://monsite.com/merci",
  "metadata": {
    "description": "Commande 5678"
  }
}

Réponse HTTP 201 — demande initiée

{
  "success": true,
  "data": {
    "uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b4",
    "type": "collection",
    "provider": "mastercard",
    "status": "pending",
    "amount": "25000.00",
    "currency": "XAF",
    "reference": "K7H2M9QXP4R8T1W5Z3NB",
    "phone_number": null,
    "checkout_url": "https://master.kratos-travel.com/?sessionId=SESSION0002..."
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Visa suit le même parcours que Mastercard : conservez provider: "mastercard" et traitez la réponse checkout_url de la même façon.

Envoi — disbursement

Méthode POSThttps://api.kratospay.com/api/v1/transactions

Payload JSON

{
  "type": "disbursement",
  "provider": "mtn_momo_cm",
  "amount": 2000,
  "currency": "XAF",
  "phone_number": "677895412",
  "idempotency_key": "paiement-fournisseur-42",
  "metadata": {
    "description": "Paiement fournisseur"
  }
}

Réponse HTTP 201 — demande initiée

{
  "success": true,
  "data": {
    "uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b4",
    "type": "disbursement",
    "provider": "mtn_momo",
    "status": "pending",
    "amount": "2000.00",
    "currency": "XAF",
    "reference": "MP240101.1235.B12345",
    "phone_number": "677895412",
    "created_at": "2026-11-02T08:05:00Z",
    "updated_at": "2026-11-02T08:05:00Z"
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Un décaissement débite le solde de l'application et crée une transaction pending en attente du réseau. Vérifiez le solde, attendez le webhook transaction.success ou transaction.failed, et utilisez GET /transactions/{uuid} pour le suivi.

Erreur HTTP 422 — données invalides ou règle refusée

error.details liste les messages de chaque champ fautif. Communiquez le meta.request_id au support en cas de problème.

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Solde insuffisant.",
    "details": {
      "amount": [
        "Le montant dépasse le solde disponible."
      ]
    }
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Erreur HTTP 401 — non authentifié

Clé API absente, invalide, inactive, expirée, ou clé d'un autre environnement (sk_test_ utilisée en production, ou l'inverse).

À vérifier côté intégration

  • Le statut pending signifie que la transaction a été initiée et attend la confirmation du client sur son téléphone ; attendez le webhook ou consultez GET /transactions/{uuid} avant de confirmer le paiement.
  • Utilisez une idempotency_key unique par opération et conservez l'uuid retourné par l'API.
  • Le numéro s'écrit sans indicatif (696246686) et doit appartenir au pays du réseau choisi.
  • Avec une clé sk_live_…, ces appels déplacent de vrais fonds. Vérifiez le numéro, le réseau, le montant et l'environnement avant l'envoi.
  • Pour la carte, ouvrez checkout_url et confirmez le paiement par webhook ou consultation de transaction, jamais avec la seule redirection. Un paiement QR GIMAC reçu arrive directement en success.

Ce que permet l'API

  • Encaisser par Mobile Money (collection), carte bancaire via une page hébergée, ou QR GIMAC.
  • Envoyer des fonds vers un portefeuille Mobile Money depuis votre solde (disbursement), retirer votre argent, programmer des retraits ou payer plusieurs bénéficiaires en une fois.
  • Encaisser sans coder grâce aux liens de paiement et aux QR codes.
  • Être notifié en temps réel de chaque changement de statut via des webhooks signés.
  • Tester l'intégralité du parcours sans argent réel avec une clé sk_test_….

Vocabulaire clé

  • Application : une intégration (site, application, terminal) avec ses clés, son webhook et son solde. Son identifiant s'envoie dans X-Application-ID.
  • Clé API : sk_test_… (test, aucun argent réel) ou sk_live_… (vrais paiements). Elle reste sur votre serveur.
  • Transaction : un mouvement d'argent identifié par un uuid, dans un des statuts pending, success, failed, expired, refunded…
  • Webhook : une notification HTTP POST envoyée par Kratos Pay vers votre serveur à chaque changement de statut d'une transaction.
  • Idempotency key : un identifiant unique que vous générez pour chaque opération, pour éviter qu'une même transaction soit créée deux fois en cas de nouvel essai réseau.

Deux profils de marchand

Marchand particulier (développeur)Marchand entreprise
Pour quiUne personne qui encaisse pour elle-même et intègre l'API (site, application, bot).Une société qui encaisse pour son activité.
ConnexionTéléphone + code WhatsAppE-mail + mot de passe + TOTP obligatoire
Validation KYCPas exigée pour encaisser en liveObligatoire avant tout paiement réel
ApplicationsUne application personnelle, créée automatiquementPlusieurs applications (site, application mobile, terminal…)
Fonctions réservées—Équipe, retraits programmés, paiements de masse
  • Particulier : créer le compte → se connecter → récupérer son application → configurer le webhook → générer une clé API → encaisser → suivre → retirer son argent.
  • Entreprise : créer le compte → activer le TOTP → soumettre le KYC → créer une application → clé API → encaisser → liens de paiement → solde et retraits → équipe.