Référence de l’API

Encaissements

Un encaissement est une demande de paiement adressée à un payeur sur son canal mobile money. Il naît à l’état CREATED et se termine à SUCCEEDED ou FAILED ; UNKNOWN signale un paiement que le canal n’a pas confirmé.

POST/v1/charges
GET/v1/charges/{charge_id}
GET/v1/charges

L’objet Encaissement

idUUIDrequis: Identifiant de l'encaissement.
environmentchaîne: Environnement de la clé d'origine : sandbox (test) ou live (argent réel). Une clé ne lit et n'agit que dans son environnement.défaut : live
statuschaînerequis: État : CREATED, PENDING, SUCCEEDED, FAILED ou UNKNOWN (non confirmé, à réconcilier). SUCCEEDED et FAILED sont définitifs.
amount_minorentierrequis: Montant brut demandé au payeur (unités mineures).
currencychaînerequis: Devise : CDF ou USD.
railchaînerequis: Canal de paiement.valeurs : mpesa
fee_minorentier ou null: Frais prélevés (unités mineures). null jusqu'à la confirmation.
net_minorentier ou null: Net dû au marchand = brut - frais (unités mineures). null jusqu'à la confirmation.
fee_percent_bpsentier ou null: Pourcentage appliqué, en points de base (1 % = 100).
fee_fixed_minorentier ou null: Frais fixe appliqué (unités mineures).
fee_min_minorentier ou null: Plancher de frais appliqué.
fee_max_minorentier ou null: Plafond de frais appliqué.
fee_sourcechaîne ou null: Provenance du barème : catalog (grille publique) ou negotiated.
redirect_urlchaîne ou null: Page de paiement où rediriger le payeur, pour les canaux qui en exigent une. null pour le mobile money.
descriptionchaîne ou null: Motif fourni à la création.
created_atdate-heurerequis: Date de création (UTC, ISO 8601).

Objet Encaissement

{
  "id": "8089246d-8876-4e7b-b156-4431ae6bc527",
  "environment": "sandbox",
  "status": "CREATED",
  "amount_minor": 2500000,
  "currency": "CDF",
  "rail": "mpesa",
  "fee_minor": null,
  "net_minor": null,
  "fee_percent_bps": null,
  "fee_fixed_minor": null,
  "fee_min_minor": null,
  "fee_max_minor": null,
  "fee_source": null,
  "redirect_url": null,
  "description": "Commande 1042",
  "created_at": "2026-09-24T12:45:46.919251Z"
}

Créer un encaissement

POST/v1/charges

Demande un paiement au payeur sur son canal mobile money. L'API répond sans attendre le payeur, à l'état CREATED ; l'issue finale se lit sur l'encaissement ou arrive par webhook. Exige un en-tête Idempotency-Key : la même clé renvoie la même réponse, jamais un second encaissement.

En-tête Idempotency-Key requis, et inclus dans la chaîne signée.

Corps de la requête

amount_minorentierrequis: Montant demandé au payeur, en unités mineures (entier) : 2500000 vaut 25 000,00 CDF.> 0
currencychaînerequis: Devise de l'encaissement.valeurs : CDF, USD
railchaîne: Canal de paiement.valeurs : mpesa · défaut : mpesa
customer_refchaîne ou null: Numéro mobile money du payeur, en RDC : +243 suivi de 9 chiffres. Les écritures 0XXXXXXXXX et 243XXXXXXXXX sont acceptées et normalisées ; tout autre format est refusé (422). Requis pour M-Pesa.64 caractères max.
descriptionchaîne ou null: Motif libre, repris dans votre espace marchand et sur le reçu.255 caractères max.
webhook_urlURL ou null: Adresse HTTPS prévenue de l'issue finale, en plus des adresses déclarées dans votre espace marchand.

Réponse

Code 201, avec l’objet Encaissement.

Erreurs

400En-tête Idempotency-Key manquant.
401Authentification manquante ou invalide.
409Idempotency-Key réutilisée avec un corps différent.
422Validation échouée, ou transaction refusée par les contrôles anti-fraude.
429Limite de débit dépassée (voir Retry-After).

Forme commune et conduite à tenir : les erreurs.

POST /v1/charges

KEY="ak_sandbox"
SECRET="sk_sandbox_demo"

P="/v1/charges"
BODY='{"amount_minor":2500000,"currency":"CDF","customer_ref":"+243810000000","description":"Commande 1042"}'
IDEM=$(uuidgen)
TS=$(date +%s)
SIG=$(printf '%s' "$TS.POST.$P.$IDEM.$BODY" \
  | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.*= //')

curl "https://sandbox.inopas.net$P" \
  -H "X-Inopas-Key: $KEY" \
  -H "X-Inopas-Timestamp: $TS" \
  -H "X-Inopas-Signature: sha256=$SIG" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  -d "$BODY"

import { createHmac, randomUUID } from "node:crypto";

const KEY = "ak_sandbox";
const SECRET = "sk_sandbox_demo";
const path = "/v1/charges"; // signé sans la query string
const body = JSON.stringify({
  "amount_minor": 2500000,
  "currency": "CDF",
  "customer_ref": "+243810000000",
  "description": "Commande 1042"
});
const idem = randomUUID();
const ts = String(Math.floor(Date.now() / 1000));
const sig = createHmac("sha256", SECRET)
  .update(`${ts}.POST.${path}.${idem}.${body}`)
  .digest("hex");

const res = await fetch(`https://sandbox.inopas.net${path}`, {
  method: "POST",
  headers: {
    "X-Inopas-Key": KEY,
    "X-Inopas-Timestamp": ts,
    "X-Inopas-Signature": `sha256=${sig}`,
    "Idempotency-Key": idem,
    "Content-Type": "application/json",
  },
  body,
});
console.log(res.status, await res.json());

import hashlib, hmac, json, time, urllib.error, urllib.request, uuid

KEY = "ak_sandbox"
SECRET = b"sk_sandbox_demo"
path = "/v1/charges"  # signé sans la query string
body = json.dumps({
    "amount_minor": 2500000,
    "currency": "CDF",
    "customer_ref": "+243810000000",
    "description": "Commande 1042",
}, separators=(",", ":")).encode()
idem = str(uuid.uuid4())
ts = str(int(time.time()))
sig = hmac.new(SECRET, f"{ts}.POST.{path}.{idem}.".encode() + body, hashlib.sha256).hexdigest()

entetes = {"X-Inopas-Key": KEY, "X-Inopas-Timestamp": ts, "X-Inopas-Signature": "sha256=" + sig}
entetes |= {"Idempotency-Key": idem, "Content-Type": "application/json"}
req = urllib.request.Request("https://sandbox.inopas.net" + path, headers=entetes, data=body, method="POST")
try:
    with urllib.request.urlopen(req) as resp:
        print(resp.status, json.load(resp))
except urllib.error.HTTPError as e:
    print(e.code, json.load(e))

Réponse 201

HTTP/2 201

{
  "id": "8089246d-8876-4e7b-b156-4431ae6bc527",
  "environment": "sandbox",
  "status": "CREATED",
  "amount_minor": 2500000,
  "currency": "CDF",
  "rail": "mpesa",
  "fee_minor": null,
  "net_minor": null,
  "fee_percent_bps": null,
  "fee_fixed_minor": null,
  "fee_min_minor": null,
  "fee_max_minor": null,
  "fee_source": null,
  "redirect_url": null,
  "description": "Commande 1042",
  "created_at": "2026-09-24T12:45:46.919251Z"
}

Lire un encaissement

GET/v1/charges/{charge_id}

Lit l'état courant de l'encaissement et, une fois confirmé, sa ventilation brut, frais, net. Un identifiant qui n'appartient pas à votre compte répond 404.

Paramètres

charge_idUUID, dans le cheminrequis: Identifiant renvoyé à la création.

Réponse

Code 200, avec l’objet Encaissement.

Erreurs

401Authentification manquante ou invalide.
404Encaissement introuvable.
422Paramètre invalide (validation_error).

Forme commune et conduite à tenir : les erreurs.

GET /v1/charges/{charge_id}

KEY="ak_sandbox"
SECRET="sk_sandbox_demo"

P="/v1/charges/8089246d-8876-4e7b-b156-4431ae6bc527"
TS=$(date +%s)
SIG=$(printf '%s' "$TS.GET.$P.." \
  | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.*= //')

curl "https://sandbox.inopas.net$P" \
  -H "X-Inopas-Key: $KEY" \
  -H "X-Inopas-Timestamp: $TS" \
  -H "X-Inopas-Signature: sha256=$SIG"

import { createHmac } from "node:crypto";

const KEY = "ak_sandbox";
const SECRET = "sk_sandbox_demo";
const path = "/v1/charges/8089246d-8876-4e7b-b156-4431ae6bc527"; // signé sans la query string
const ts = String(Math.floor(Date.now() / 1000));
const sig = createHmac("sha256", SECRET)
  .update(`${ts}.GET.${path}..`)
  .digest("hex");

const res = await fetch(`https://sandbox.inopas.net${path}`, {
  headers: {
    "X-Inopas-Key": KEY,
    "X-Inopas-Timestamp": ts,
    "X-Inopas-Signature": `sha256=${sig}`,
  },
});
console.log(res.status, await res.json());

import hashlib, hmac, json, time, urllib.error, urllib.request

KEY = "ak_sandbox"
SECRET = b"sk_sandbox_demo"
path = "/v1/charges/8089246d-8876-4e7b-b156-4431ae6bc527"  # signé sans la query string
body = b""
idem = ""
ts = str(int(time.time()))
sig = hmac.new(SECRET, f"{ts}.GET.{path}.{idem}.".encode() + body, hashlib.sha256).hexdigest()

entetes = {"X-Inopas-Key": KEY, "X-Inopas-Timestamp": ts, "X-Inopas-Signature": "sha256=" + sig}
req = urllib.request.Request("https://sandbox.inopas.net" + path, headers=entetes)
try:
    with urllib.request.urlopen(req) as resp:
        print(resp.status, json.load(resp))
except urllib.error.HTTPError as e:
    print(e.code, json.load(e))

Réponse 200

HTTP/2 200

{
  "id": "8089246d-8876-4e7b-b156-4431ae6bc527",
  "environment": "sandbox",
  "status": "CREATED",
  "amount_minor": 2500000,
  "currency": "CDF",
  "rail": "mpesa",
  "fee_minor": null,
  "net_minor": null,
  "fee_percent_bps": null,
  "fee_fixed_minor": null,
  "fee_min_minor": null,
  "fee_max_minor": null,
  "fee_source": null,
  "redirect_url": null,
  "description": "Commande 1042",
  "created_at": "2026-09-24T12:45:46.919251Z"
}

Lister les encaissements

GET/v1/charges

Du plus récent au plus ancien, par pages de limit éléments. Passez next_cursor en cursor pour obtenir la page suivante ; null signale la fin. Attention : la liste inclut aujourd'hui aussi les reversements et remboursements du compte, sans champ pour les distinguer. Pour des totaux, utilisez /v1/reports/summary.

Paramètres

limitentier, dans le requête: Taille de page (1–100).de 1 à 100 · défaut : 20
cursorchaîne, dans le requête: Curseur opaque de pagination.

Réponse

Code 200 , avec une page : chaque élément de data est un objet Encaissement.

dataliste de objetrequis: Les éléments de la page, du plus récent au plus ancien.
next_cursorchaîne ou null: Curseur de la page suivante (null si fin de liste).

Erreurs

400Curseur invalide.
401Authentification manquante ou invalide.
422Paramètre invalide (validation_error).

Forme commune et conduite à tenir : les erreurs.

GET /v1/charges

KEY="ak_sandbox"
SECRET="sk_sandbox_demo"

P="/v1/charges"
TS=$(date +%s)
SIG=$(printf '%s' "$TS.GET.$P.." \
  | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.*= //')

curl "https://sandbox.inopas.net$P?limit=2" \
  -H "X-Inopas-Key: $KEY" \
  -H "X-Inopas-Timestamp: $TS" \
  -H "X-Inopas-Signature: sha256=$SIG"

import { createHmac } from "node:crypto";

const KEY = "ak_sandbox";
const SECRET = "sk_sandbox_demo";
const path = "/v1/charges"; // signé sans la query string
const ts = String(Math.floor(Date.now() / 1000));
const sig = createHmac("sha256", SECRET)
  .update(`${ts}.GET.${path}..`)
  .digest("hex");

const res = await fetch(`https://sandbox.inopas.net${path}?limit=2`, {
  headers: {
    "X-Inopas-Key": KEY,
    "X-Inopas-Timestamp": ts,
    "X-Inopas-Signature": `sha256=${sig}`,
  },
});
console.log(res.status, await res.json());

import hashlib, hmac, json, time, urllib.error, urllib.request

KEY = "ak_sandbox"
SECRET = b"sk_sandbox_demo"
path = "/v1/charges"  # signé sans la query string
body = b""
idem = ""
ts = str(int(time.time()))
sig = hmac.new(SECRET, f"{ts}.GET.{path}.{idem}.".encode() + body, hashlib.sha256).hexdigest()

entetes = {"X-Inopas-Key": KEY, "X-Inopas-Timestamp": ts, "X-Inopas-Signature": "sha256=" + sig}
req = urllib.request.Request("https://sandbox.inopas.net" + path + "?limit=2", headers=entetes)
try:
    with urllib.request.urlopen(req) as resp:
        print(resp.status, json.load(resp))
except urllib.error.HTTPError as e:
    print(e.code, json.load(e))

Réponse 200

HTTP/2 200

{
  "data": [
    {
      "id": "8089246d-8876-4e7b-b156-4431ae6bc527",
      "environment": "sandbox",
      "status": "CREATED",
      "amount_minor": 2500000,
      "currency": "CDF",
      "rail": "mpesa",
      "fee_minor": null,
      "net_minor": null,
      "fee_percent_bps": null,
      "fee_fixed_minor": null,
      "fee_min_minor": null,
      "fee_max_minor": null,
      "fee_source": null,
      "redirect_url": null,
      "description": "Commande 1042",
      "created_at": "2026-09-24T12:45:46.919251Z"
    }
  ],
  "next_cursor": null
}

L’objet Encaissement

Créer un encaissement

Corps de la requête

Réponse

Erreurs

Lire un encaissement

Paramètres

Réponse

Erreurs

Lister les encaissements

Paramètres

Réponse

Erreurs

Un seul branchement, tous les paiements.