Common conventions

This chapter applies to every route of the individual and business journeys. You only need to read it once.

API addresses

Environment	Base URL
Production	https://api.kratospay.com/api/v1
Staging	https://dev-aggregator-api.kratospay.com/api/v1

Every path in this documentation is relative to this base URL (for example, POST /transactions becomes POST https://api.kratospay.com/api/v1/transactions). Bodies are JSON (Content-Type: application/json, Accept: application/json).

Two kinds of authentication

Type	Used for	How to send it
Session token (dashboard)	Managing your account: profile, applications, API keys, KYC, payment links, balance, withdrawals.	`Authorization: Bearer {token}`, obtained when signing in.
API key (`sk_test_…` / `sk_live_…`)	Integrating payments on your server: create, track, cancel or refund a transaction, and manage GIMAC QR points.	`Authorization: Bearer sk_live_…` (or the `X-Api-Key` header), plus `X-Application-ID: {your application id}`.

The API key must never be placed in a mobile app or a browser: it can collect and refund. Keep it on your server.

sk_test_…: test environment, simulated networks, no real money. sk_live_…: real payments.
The key is shown only once, when it is created. If lost, revoke it and generate a new one.

Response format

Success (HTTP 2xx)

{
  "success": true,
  "data": {},
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-11-02T10:30:00Z"
  }
}

Failure (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 is only present for validation errors (422): one entry per invalid field, each with its list of messages. Give the meta.request_id to support if something goes wrong.

HTTP codes

HTTP	Meaning	What to do
200 / 201 / 202	Success (201 = resource created, 202 = processing accepted, in progress).	—
401	Token or API key missing, invalid, expired or revoked.	Sign in again / check the key and its environment.
403	Restricted action (e.g. business-only feature, missing team permission).	Check the account type and permissions.
404	Resource not found or owned by another account (never 403 in that case).	Check the identifier.
422	Invalid data or business rule refused (balance, KYC, network unavailable…).	Read `error.code` and `error.details`.
429	Too many requests.	Retry after a short wait.
5xx	Incident on Kratos Pay's side or the payment network.	Retry; never create the same operation twice without an idempotency key.

Payment networks and numbers

`provider` value	Network	Collection	Send / withdrawal	Refund
`orange_money_cm`	Orange Money Cameroon	Yes	Yes	Yes
`mtn_momo_cm`	MTN Mobile Money Cameroon	Yes	Yes	No
`mastercard`	Mastercard and Visa cards (secure checkout page)	Yes	No	No
`gimac`	GIMAC QR (scan-to-pay)	Yes	No	No

The up-to-date list of accepted values is returned by GET /payment-providers (session token). Copy the selector value as is. For both Mastercard and Visa, keep the provider field set to mastercard.
For Mobile Money, send the number without a country code (696246686) and matching the provider's country; bank card payments do not require a phone number.
Amounts: send a number (5000). Responses return amounts as strings with two decimals ("5000.00"). Default currency: XAF.
Mobile Money and card payments are asynchronous (pending); wait for the webhook or fetch the transaction. A received GIMAC QR payment creates a success transaction immediately.

Idempotency

On every money-creating call, send an idempotency_key unique per business operation (e.g. order number). If your call times out and you resend it with the same key, you get the transaction already created instead of a second one. A key already used by another operation is refused with 422.