Developer documentation

Introduction

The API is organised around REST resources, with JSON responses and standard HTTP codes. All requests go over HTTPS.

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

Two environments: sandbox (keys sk_sb_…, no real money) and production (keys sk_live_…, activated when the contract is signed).

Quickstart

Take your first mobile money payment in the sandbox, in three steps.

1. Create a mobile money pay-in

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. Read the response

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

3. Receive the confirmation

When the customer confirms on their phone, BaobaPay sends payin.succeeded to your webhook endpoint — see Webhooks below.

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

Authentication

Every request is authenticated with a secret key passed in the Authorization header, in the Bearer format. Never expose a sk_live_ key on the client side.

Authorization: Bearer sk_sb_9f2a3b7c1d…

Idempotency

All POST requests that create movements accept an Idempotency-Key header. Replaying the same key returns the original response without creating a duplicate — essential for network retries and mobile money retries.

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

The key is retained for 24 h. Use a unique UUID per payment intent.

Amounts & currencies

Amounts are represented by a Money object — a currency and an integer value. XAF and XOF are currencies without minor units: the value is expressed in whole francs (no cents).

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

Fund model

Understanding where the money sits at any moment is the prerequisite to any integration.

Wallet topology

Two wallets are created when a platform opens on a third-party vertical — marketplace, freelance, crowdfunding, pots, travel, B2B. In direct sale (e-commerce), only the main wallet exists.

Segregation

A withdrawal from WLT-MAIN can only go to a settlement account of the platform. A payout from a third-party wallet can only go to that third party's account. The API refuses every cross combination — a marketplace owner cannot drain their sellers' wallet to their own account.

Withdrawal lifecycle

POST /withdrawals            → status: PENDING_APPROVAL
  ↓  (internal approval)
withdrawal.approved          → the funds have not left yet
  ↓  (execution by the operator)
withdrawal.paid              → the wallet balance is decremented here
      or
withdrawal.failed            → the balance stays intact, the request can be replayed

Cash collections

Cash declarations are merchant data: no wallet is credited, no flow can be reconciled in bank. They are kept and exportable, but do not enter the balance computation.

Errors

The API uses conventional HTTP codes and returns a structured error object.

{
  "type": "invalid_request",
  "code": "insufficient_kyc",
  "message": "The merchant account must be verified to collect in production."
}

E-commerce plugins & modules

Get paid without writing code: official modules maintained by BaobaPay. Each module installs the hosted checkout (mobile money, card, link) and the automatic reconciliation of orders via webhooks.

Common setup: paste the public API key + the webhook URL generated by the module. The order status changes automatically to « paid » on payin.succeeded. Sandbox supported in every module.

Endpoints

The collection resources of the aggregator API.

Webhooks

BaobaPay notifies your server of asynchronous events (payment confirmation, KYC change, dispute…). Each delivery is signed and replayed on failure (backoff up to 24 h).

Verify the signature

Every request carries a BaobaPay-Signature header — an HMAC-SHA256 of the raw body, computed with your endpoint secret. Compare it before processing the event.

const sig = req.headers['baobapay-signature'];
const expected = crypto
  .createHmac('sha256', endpointSecret)
  .update(rawBody)
  .digest('hex');
if (sig !== expected) return res.status(400).end();
// valid signature → process the event

Event catalogue

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

Sandbox & testing

The sandbox reproduces the entire API without real money. Trigger successes and failures deterministically.

Test cards

Test mobile money

• +237 6 71 22 41 88 → successful confirmation
• +237 6 00 00 00 00 → timed out (not confirmed)