API MbotePay

Introduction

Toutes les requêtes se font en HTTPS et renvoient du JSON. L'URL de base est :

Deux opérations principales :

Authentification

Génère une clé API dans l'app (Développeur → Nouvelle clé). Passe-la en en-tête Authorization sur chaque requête :

Authorization: Bearer mp_live_xxxxxxxxxxxxxxxxxxxx

Idempotence

Pour éviter les doublons (retry réseau), envoie un en-tête Idempotency-Key unique par opération. Deux requêtes avec la même clé ne créent qu'une seule transaction.

Idempotency-Key: commande_12345

Montants & devises

Les montants (amount) sont exprimés dans l'unité principale de la devise (ex. 5000 = 5 000 CDF), jamais en centimes. La devise (currency) est le code ISO : CDF, USD, XAF, XOF, KES, RWF, UGX, ZMW, SLE.

Opérateurs & pays

Chaque requête précise le pays (country), l'opérateur (operator), la devise (currency) et le numéro (phone, format international sans +, ex. 243812345678). Voici la couverture complète — 12 pays, 22 opérateurs :

Frais

Les frais sont identiques à ceux de l'app MbotePay. Le PayIn répercute le coût réel de l'opérateur (sans marge) — ton solde est crédité net de frais. Le PayOut ajoute 1 % de frais MbotePay au coût de l'opérateur — ton solde est débité du montant + frais. Le montant exact figure dans le champ fee de la transaction.

PayIn — encaisser

curl https://app.mbotepay.com/api/v1/payin \
  -H "Authorization: Bearer mp_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cmd_12345" \
  -d '{
    "amount": 5000,
    "currency": "CDF",
    "country": "COD",
    "operator": "VODACOM_MPESA_COD",
    "phone": "243812345678",
    "reference": "cmd_12345",
    "callback_url": "https://ton-site.com/webhooks/mbotepay"
  }'

Réponse

{
  "id": "6f2a…-tx",
  "object": "payin",
  "status": "PROCESSING",
  "amount": 5000,
  "currency": "CDF",
  "operator": "VODACOM_MPESA_COD",
  "phone": "243812345678",
  "reference": "cmd_12345"
}

Le client reçoit une invite mobile money pour valider. Le statut final (COMPLETED ou FAILED) est notifié par webhook.

PayOut — verser

Mêmes champs que PayIn. Débite ton solde MbotePay vers le phone du bénéficiaire. Des frais s'appliquent (voir Frais), renvoyés dans fee.

curl https://app.mbotepay.com/api/v1/payout \
  -H "Authorization: Bearer mp_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: paie_98765" \
  -d '{
    "amount": 20000,
    "currency": "CDF",
    "country": "COD",
    "operator": "AIRTEL_COD",
    "phone": "243991234567",
    "reference": "paie_98765",
    "callback_url": "https://ton-site.com/webhooks/mbotepay"
  }'

Réponse

{
  "id": "9a1b…-tx",
  "object": "payout",
  "status": "PROCESSING",
  "amount": 20000,
  "fee": 400,
  "currency": "CDF",
  "operator": "AIRTEL_COD",
  "phone": "243991234567",
  "reference": "paie_98765"
}

Statut d'une transaction

curl https://app.mbotepay.com/api/v1/transactions/6f2a…-tx \
  -H "Authorization: Bearer mp_live_..."

{
  "id": "6f2a…-tx",
  "object": "payin",
  "status": "COMPLETED",
  "amount": 5000,
  "fee": 0,
  "currency": "CDF",
  "reference": "cmd_12345",
  "created": "2026-07-08T09:00:00Z",
  "updated": "2026-07-08T09:00:22Z"
}

Statuts

Webhooks

Si tu fournis callback_url, MbotePay envoie une requête POST à cette URL dès que la transaction atteint un statut terminal. Le corps :

{
  "id": "6f2a…-tx",
  "object": "payin",
  "event": "payin.completed",
  "status": "completed",
  "amount": 5000,
  "fee": 0,
  "currency": "CDF",
  "reference": "cmd_12345"
}

Vérifier la signature

Chaque webhook porte un en-tête X-MbotePay-Signature: t=<timestamp>,v1=<hmac>. Recalcule le HMAC-SHA256 de `${t}.${corpsBrut}` avec ton secret de webhook (fourni à la création de la clé) et compare :

import crypto from "crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(parts.t + "." + rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Erreurs

Les erreurs renvoient un code HTTP adapté et un corps JSON :

{ "error": { "message": "Clé API invalide ou révoquée.", "code": "unauthorized" } }

Une question ? support@mbotepay.com · MbotePay — LEGETEC SARL, Kinshasa (RDC).