Documentation développeur

Introduction

L'API est organisée autour de ressources REST, avec des réponses JSON et des codes HTTP standards. Toutes les requêtes passent par HTTPS.

https://api.baobapay.com/api/v1           // production
https://api.sandbox.baobapay.com/api/v1   // sandbox

Deux environnements : sandbox (clés sk_sb_…, aucun argent réel) et production (clés sk_live_…, activées à la signature du contrat).

Quickstart

Encaissez un premier paiement mobile money en sandbox, en trois étapes.

1. Créez un pay-in mobile money

curl https://api.sandbox.baobapay.com/api/v1/payins/mobile-money \
  -H "Authorization: Bearer sk_sb_9f2a…" \
  -H "Idempotency-Key: 8f14e45f" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "CMD-10412",
    "amount": { "currency": "XAF", "value": 24500 },
    "operator": "MTN",
    "phone": "+237671224188"
  }'

2. Lisez la réponse

{
  "id": "pi_10482",
  "status": "PENDING",
  "amount": { "currency": "XAF", "value": 24500 }
}

3. Recevez la confirmation

Quand le client confirme sur son téléphone, BaobaPay envoie payin.succeeded à votre endpoint de webhook — voir Webhooks plus bas.

{
  "type": "payin.succeeded",
  "data": { "id": "pi_10482", "status": "SUCCEEDED" }
}

Authentification

Chaque requête s'authentifie par une clé secrète passée en en-tête Authorization, au format Bearer. Ne jamais exposer une clé sk_live_ côté client.

Authorization: Bearer sk_sb_9f2a3b7c1d…

Idempotence

Toutes les requêtes POST qui créent des mouvements acceptent un en-tête Idempotency-Key. Rejouer la même clé renvoie la réponse d'origine, sans créer de doublon — indispensable pour les reprises réseau et les retries mobile money.

Idempotency-Key: 8f14e45f-ceea-467d-9c1b-2a…

La clé est conservée 24 h. Utilisez un UUID unique par intention de paiement.

Montants & devises

Les montants sont représentés par un objet Money — une devise et une valeur entière. XAF et XOF sont des devises sans sous-unité : la valeur est exprimée en francs entiers (pas de centimes).

{ "currency": "XAF", "value": 24500 }   // 24 500 FCFA

Modèle de fonds

Comprendre où l'argent se trouve à chaque instant est le préalable à toute intégration.

Topologie des wallets

Deux wallets sont créés à l'ouverture d'une plateforme sur les verticales à tiers — marketplace, freelance, crowdfunding, cagnottes, voyage, B2B. En vente directe (e-commerce), seul le wallet principal existe.

Ségrégation

Un retrait depuis WLT-MAIN ne peut aller que vers un compte de règlement de la plateforme. Un reversement depuis un wallet de tiers ne peut aller que vers le compte de ce tiers. L'API refuse toute combinaison croisée — un propriétaire de marketplace ne peut pas vider le wallet de ses vendeurs vers son propre compte.

Cycle d'un retrait

POST /withdrawals            → status: PENDING_APPROVAL
  ↓  (validation interne)
withdrawal.approved          → les fonds ne sont pas encore partis
  ↓  (exécution par l'opérateur)
withdrawal.paid              → le solde du wallet est décrémenté ici
      ou
withdrawal.failed            → le solde reste intact, la demande est rejouable

Encaissements espèces

Les déclarations d'espèces sont des données du marchand : aucun wallet n'est crédité, aucun flux n'est réconciliable en banque. Elles sont conservées et exportables, mais n'entrent pas dans le calcul des soldes.

Erreurs

L'API utilise les codes HTTP conventionnels et renvoie un objet d'erreur structuré.

{
  "type": "invalid_request",
  "code": "insufficient_kyc",
  "message": "Le compte marchand doit être vérifié pour encaisser en production."
}

Plugins & modules e-commerce

Encaissez sans écrire de code : modules officiels maintenus par BaobaPay. Chaque module installe le checkout hébergé (momo, carte, lien) et la réconciliation automatique des commandes via webhooks.

Configuration commune : coller la clé API publique + l'URL de webhook générée par le module. Le statut de commande passe automatiquement à « payée » sur payin.succeeded. Sandbox supporté dans chaque module.

Endpoints

Les ressources d'encaissement de l'API agrégateur.

Webhooks

BaobaPay notifie votre serveur des événements asynchrones (confirmation d'un paiement, changement KYC, litige…). Chaque livraison est signée et rejouée en cas d'échec (backoff jusqu'à 24 h).

Vérifier la signature

Chaque requête porte un en-tête BaobaPay-Signature — un HMAC-SHA256 du corps brut, calculé avec le secret de votre endpoint. Comparez-le avant de traiter l'événement.

const sig = req.headers['baobapay-signature'];
const expected = crypto
  .createHmac('sha256', endpointSecret)
  .update(rawBody)
  .digest('hex');
if (sig !== expected) return res.status(400).end();
// signature valide → traiter l'événement

Catalogue des événements

{
  "type": "payin.succeeded",
  "created": 1752931320,
  "data": {
    "id": "pi_10482",
    "amount": { "currency": "XAF", "value": 24500 },
    "operator": "MTN"
  }
}

Sandbox & tests

La sandbox reproduit l'intégralité de l'API sans argent réel. Déclenchez des succès et des échecs de façon déterministe.

Cartes de test

Mobile money de test

• +237 6 71 22 41 88 → confirmation réussie
• +237 6 00 00 00 00 → délai dépassé (non confirmé)