Collect Mobile Money payments without guessing what happened

System architecture

Five nodes, one path for the money. Knowing who talks to whom answers half of all support questions.

Who does what

Five-minute start

From an empty account to your first successful test collection.

1. Create an account and get your test keys

Open an account on the console. A sandbox project and its credentials are generated immediately. The secret is shown once: copy it before closing the panel.

2. Check that the key works

# Authentication probe: consumes nothing, creates nothing
curl https://api.gba-cm.online/api/v1/me \
  -H "X-BCash-Key: $BCASH_KEY" \
  -H "X-BCash-Timestamp: $(date +%s)" \
  -H "X-BCash-Signature: $SIGNATURE"

How to compute $SIGNATURE is covered in Authentication. A 200 confirms that key, secret and clock are all correct.

3. Register a notification endpoint

{
  "url": "https://store.example.cm/webhooks/bcash",
  "events": ["transaction.succeeded", "transaction.failed"]
}

# → 201 { "reference": "whk_…", "secret": "whsec_…" }   ← the secret appears only here

4. Create a test collection

curl -X POST https://api.gba-cm.online/api/v1/collections \
  -H "X-BCash-Key: $BCASH_KEY" \
  -H "X-BCash-Timestamp: $(date +%s)" \
  -H "X-BCash-Signature: $SIGNATURE" \
  -H "Idempotency-Key: 8f1c2b4e-3a77-4c11-9f2d-6b0a5e91c7d3" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "operator": "MTN",
    "customer": { "phone": "+237650000000" },
    "merchantReference": "ORD-1042",
    "context": "API_DIRECT"
  }'

5. Force the outcome in sandbox

In testing, nobody is going to type a PIN: trigger the outcome yourself.

{ "target": "SUCCEEDED" }

# The transaction follows the nominal path: ledger entries,
# a signed transaction.succeeded webhook, and an audit trail.

Environments & keys

Two environments, one API, separate keys that never cross.

Anatomy of a credential

• Public key — identifies the calling application, sent in clear in X-BCash-Key. Visible in the console.
• Secret — used for signing. Displayed once, at creation or rotation. The console only keeps its last four characters, to help you identify the right key.
• Environment — carried by the credential, not by the project: one project can hold both a test key and a production key.
• Scopes — what the key is allowed to do (list).

Rotating without downtime

1. From the console, generate a new key in no-downtime mode.
2. Deploy the new key/secret pair to your servers.
3. Check in the console that the new key is recording calls (the last used column).
4. Revoke the old one.

Immediate revocation also exists, for a compromised secret: it kills the old key at once, and any integration still using it receives INVALID_SIGNATURE. The console asks you to retype the project name before applying it.

Authentication

Three ways to authenticate, for three kinds of caller. Picking the right one is the first architectural decision of any integration.

Signing an HMAC request

The string to sign concatenates four elements separated by newlines:

METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + sha256_hex(body)

# METHOD    : uppercase HTTP verb, e.g. POST
# PATH      : path only, e.g. /api/v1/collections (no host, no query string)
# TIMESTAMP : Unix seconds, identical to the X-BCash-Timestamp header
# body      : the exact JSON body sent; empty string on GET

$body      = json_encode($payload, JSON_UNESCAPED_SLASHES);
$timestamp = (string) time();
$toSign    = "POST\n/api/v1/collections\n{$timestamp}\n" . hash('sha256', $body);
$signature = hash_hmac('sha256', $toSign, $secret);

// Send exactly that $body: re-serialising after signing invalidates the request.

const body = JSON.stringify(payload);
const ts = Math.floor(Date.now() / 1000).toString();
const digest = crypto.createHash('sha256').update(body).digest('hex');
const signature = crypto
  .createHmac('sha256', secret)
  .update(`POST\n/api/v1/collections\n${ts}\n${digest}`)
  .digest('hex');

Ephemeral tokens for clients

Your backend exchanges its HMAC key for a short-lived token and hands it to the client. The token carries a strict subset of the key's scopes and lives at most 900 seconds.

// Request, HMAC-signed from YOUR server
{ "scopes": ["collections:create", "transactions:read"], "ttl": 600 }

// Response
{ "token": "bt_9f2c…", "expiresIn": 600, "scopes": ["collections:create", "transactions:read"] }

• A token cannot mint another one: the route rejects a Bearer bt_….
• Revoking the credential instantly invalidates every token it issued.
• Ask for the bare minimum: a checkout-screen token has no business reading your balances.

Idempotency

Mobile networks drop. This is the rule that keeps a dropped connection from charging your customer twice.

Every route that moves money requires the Idempotency-Key header, a UUID that you generate and keep for the duration of the operation.

Choosing your key

Tie the key to the business intent, not to the technical attempt. An order that is paid once deserves a stable key; generating a fresh one on every click re-enables exactly the double charge idempotency was meant to prevent.

// Once, when the order is created:
order.paymentIdempotencyKey ??= crypto.randomUUID();
// Every payment attempt for THIS order reuses that key.

Recovering a transaction after a drop

If you lose the response, don't recreate anything: look it up.

Both routes exist for precisely this situation. The second assumes you set merchantReference at creation — always do.

Amounts & currency

The CFA franc has no sub-unit. That simplicity is a trap for anyone coming from a cents-based API.

• amount is a strictly positive integer: 25000 means twenty-five thousand francs.
• Never multiply by 100, never round a float: floating-point arithmetic eventually produces a phantom franc in a reconciliation.
• currency is XAF. The field exists for the future; today it has one value.
• Three amounts coexist on a transaction: amount (what was requested), feeAmount (the fees) and netAmount (what you keep). Display the one that answers the question asked, not the most flattering one.

Errors & correlation ID

Every error shares the same envelope, and each one carries what support needs to find it.

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",           // stable machine code
    "message": "Insufficient balance.",     // human text, may be reworded
    "correlationId": "c7f3a91b4e2d",        // quote this to support
    "retryable": false,                     // would retrying help?
    "retryAfter": null,                     // suggested delay, in seconds
    "details": {}                             // context, depending on the code
  }
}

How to react

• Branch on code, never on message: the text may be rewritten, the code is a contract.
• retryable: true — replay the same request with the same Idempotency-Key, honouring retryAfter.
• retryable: false — retrying changes nothing. Fix the request or surface the error to the user.
• Log correlationId next to your order reference. It turns a support ticket into a three-minute diagnosis.

HTTP codes

The exhaustive catalogue of machine codes is published by the API itself: GET /api/v1/meta → errors.catalog. Consume it rather than copying a list that will age.

Pagination & filters

Collections are paginated server-side. Never fetch everything to filter in memory.

The response carries the total; don't recompute it from the number of items received.

Operators

The list is dynamic: it carries each operator's service state.

Fees & quotes

Two different questions hide behind “how much does it cost”. The API asks which one you are asking.

Choosing your basis

// Request
{
  "type": "COLLECTION",
  "context": "WOOCOMMERCE",
  "amount": 25000,
  "amountBasis": "ORDER_NET",
  "operator": "MTN"
}

// Response
{
  "reference": "fq_7Q4K…",
  "orderAmount": 25000,
  "customerFeeAmount": 500,
  "customerPayableAmount": 25500,   // ← use this as "amount" at creation
  "merchantNetAmount": 25000,
  "feePayer": "CUSTOMER",
  "ruleVersion": "2026-07-01",
  "expiresAt": "2026-07-27T10:15:00Z"   // 900 s
}

Consuming a quote

To guarantee the customer the price you displayed, pass feeQuoteId at creation — and amount must then equal customerPayableAmount exactly. Any other value is rejected: that is the protection against a screen showing one price while the API debits another.

• A quote is valid for 900 seconds and is consumed once.
• ruleVersion identifies the pricing grid applied: keep it with your order, it explains a discrepancy six months later.
• Without a quote, fees are computed at creation using the grid in force at that moment.

Collections

The route to use nine times out of ten: it fixes the type and resolves your destination wallet on its own.

Request body

Response

{
  "reference": "TRX7QK4M2",
  "type": "COLLECTION",
  "status": "PENDING_CONFIRMATION",
  "amount": 25500,
  "feeAmount": 500,
  "netAmount": 25000,
  "merchantReference": "ORD-1042",
  "nextAction": {
    "type": "AWAIT_MOBILE_CONFIRMATION",
    "displayMessage": "Confirm the payment on your phone.",
    "expiresAt": "2026-07-27T10:05:00Z"
  },
  "createdAt": "2026-07-27T10:00:00Z"
}

Using nextAction

This block tells you what to display while waiting, so you don't have to invent one message per operator:

• AWAIT_MOBILE_CONFIRMATION — the customer must approve on their phone. Show displayMessage and a countdown to expiresAt.
• AWAIT_PROCESSING — nothing for the customer to do, execution is under way.

Payouts

Sending money from your balance to a Mobile Money number.

{
  "amount": 50000,                       // what the recipient RECEIVES
  "operator": "ORANGE",
  "recipient": { "phone": "+237690000000", "name": "ALBA Supplies" },
  "merchantReference": "INV-2026-118"
}

A payout fails if the available balance is insufficient: the required amount is reserved at creation, then released if the operation fails.

Transaction lifecycle

Twelve statuses, four terminal ones. A transaction is never “maybe paid”.

Tracking a transaction

Two strategies, and one is clearly better:

• Webhooks — recommended. You are notified as soon as state changes, without polling.
• Periodic polling — acceptable as a safety net, for instance a sweep of non-terminal transactions older than ten minutes. Space your calls out: polling every second does not make the customer confirm any faster.

Cancel & refund

Cancelling

Possible only before execution: CREATED, FEE_QUOTED, HELD, QUEUED. A transaction in PROCESSING cannot be cancelled — the money may already be moving. The call releases reserved funds and is idempotent: cancelling an already-cancelled transaction returns 200.

Refunding

• Refundable: COLLECTION and MERCHANT_PAYMENT in SUCCEEDED.
• A refund is a new transaction of type REFUND, linked through parentReference.
• Without amount, the outstanding balance is refunded in full; otherwise the refund is partial and can be repeated.
• When refunds add up to the original amount, the initial transaction becomes REVERSED and transaction.reversed is emitted.
• No fees are charged on a refund.

POST /api/v1/transactions/TRX7QK4M2/refund
Idempotency-Key: 3d9a1c77-2f40-4b8e-9c15-77e0a2b4d611

{ "amount": 5000, "reason": "Missing item" }

Balances & wallets

A balance is not a single number: three compartments coexist.

The merchant wallet is created automatically at the first collection. A wallet can be frozen by compliance: it remains readable, but movements are blocked. Freezing a wallet and suspending an organisation are two distinct mechanisms.

Webhooks: principles

You don't wait on the API: it calls you when state changes.

{
  "id": "evt_9K2mQ7…",              // stable across attempts → deduplication key
  "type": "transaction.succeeded",
  "apiVersion": "2026-07-20",
  "createdAt": "2026-07-27T10:02:13Z",
  "livemode": true,                  // false in sandbox
  "data": {
    "object": { /* the full transaction */ },
    "previousAttributes": { "status": "PENDING_CONFIRMATION" }
  }
}

The four rules

1. Verify the signature before reading the body. An unverified endpoint is an open door: anyone can post “payment succeeded”.
2. Answer 2xx quickly, within a few seconds. Acknowledge, then process in the background. Slow processing triggers pointless retries.
3. Deduplicate on id. The same evt_… can arrive twice; your handler must be a no-op the second time.
4. Don't assume ordering. A transaction.succeeded may arrive before a transaction.pending_confirmation. Trust the status carried by the object, not the arrival order.

Verifying the signature

The one non-negotiable step of the integration.

// The RAW body is essential: re-serialised JSON does not yield the same bytes.
app.post('/webhooks/bcash', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-BCash-Timestamp');
  const raw = req.body.toString('utf8');

  // Replay window: reject an event that is too old.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);

  const expected = crypto.createHmac('sha256', process.env.BCASH_WEBHOOK_SECRET)
    .update(`${ts}\n${raw}`).digest('hex');

  const candidates = [req.get('X-BCash-Signature'), req.get('X-BCash-Signature-Previous')].filter(Boolean);
  const valid = candidates.some(sig =>
    sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)));   // constant-time comparison

  if (!valid) return res.sendStatus(401);

  res.sendStatus(200);              // acknowledge BEFORE processing
  queue.push(JSON.parse(raw));       // async handling, deduplicated on event.id
});

$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_BCASH_TIMESTAMP'] ?? '';

if (abs(time() - (int) $ts) > 300) { http_response_code(400); exit; }

$expected = hash_hmac('sha256', "{$ts}\n{$raw}", $secret);
$ok = hash_equals($expected, $_SERVER['HTTP_X_BCASH_SIGNATURE'] ?? '')
   || hash_equals($expected, $_SERVER['HTTP_X_BCASH_SIGNATURE_PREVIOUS'] ?? '');

if (!$ok) { http_response_code(401); exit; }

Managing endpoints

An endpoint reference looks like whk_… and its secret like whsec_…. The secret is shown only at creation and rotation; afterwards the object returns only secretLast4.

Rotating the secret

The new secret signs immediately in X-BCash-Signature, while the old one co-signs in X-BCash-Signature-Previous for 24 hours. If your verification accepts both headers, rotation loses no delivery. The end of the overlap is readable in previousSecretValidUntil.

Filtering events

An empty events array means “all”. Restricting is healthier: your endpoint only receives what it knows how to handle, and events added later won't surprise it.

Delivery, retries, duplicates

Log and replay

The console keeps every attempt: HTTP code, response time, returned body. A delivery can be replayed manually.

Reference policy

The exact parameters (attempt count, intervals, tolerance window) are published by the API: GET /api/v1/meta → webhookDelivery. Read them rather than assuming them; they can be tuned without a major version change.

Sandbox

Same code, same responses, same webhooks — with no money at stake.

This route forces the outcome of a non-terminal transaction along the nominal path: ledger entries, signed webhooks, audit trail. It is not a façade simulation — it is the real machinery, triggered by hand.

{ "target": "SUCCEEDED" }   // or "FAILED", "EXPIRED"

Called with a production credential, it returns 403. The current list of scenarios is published in GET /api/v1/meta → sandbox.

Test scenarios

What you should have exercised before requesting production access. The happy path proves almost nothing.

Going live

1. Complete your file in the console: legal profile, supporting documents, settlement Mobile Money number, verified phone.
2. Submit it. Only the account owner can: it is an act that binds the organisation.
3. Answer compliance requests if any. The exact reason is shown in the console.
4. Once approved, create a production key from your project.
5. Switch your environment variables and verify with a small real amount.

Overview

One console for merchants, developers, support and administration: menus and permissions differ, the application does not.

The console authenticates with a session JWT and consumes the /api/dashboard/* routes. It never uses HMAC signing: that stays reserved for server-to-server exchanges.

Organisations & activation

An organisation is the entity that collects. Its status determines what is allowed.

Tracking progress through the API

{
  "organizationStatus": "READY_TO_SUBMIT",
  "completionPercent": 83,
  "steps": [
    { "code": "EMAIL_VERIFIED",       "status": "DONE" },
    { "code": "SANDBOX_PROJECT",      "status": "DONE" },
    { "code": "FIRST_SANDBOX_TX",     "status": "DONE" },
    { "code": "ORGANIZATION_PROFILE", "status": "DONE" },
    { "code": "PHONE_VERIFIED",       "status": "DONE" },
    { "code": "APPLICATION_FILE",     "status": "IN_PROGRESS" }
  ],
  "nextAction": "SUBMIT_APPLICATION_FILE",
  "statusReason": null
}

Required documents

The list depends on your legal form and is shown in your file. The common core: the representative's ID (front and back) and proof of ownership of the settlement Mobile Money number. Companies additionally provide the RCCM extract and the NIU certificate.

• Accepted formats: PDF, JPEG, PNG — 10 MB maximum per document.
• Each file is scanned before compliance can see it.
• A new file is added as a new version: nothing is overwritten, and a past decision stays attached to the exact file that was examined.

Roles & team

A user can belong to several organisations, with a different role in each.

• There is exactly one owner per organisation. Removing them is impossible: ownership must first be transferred, an operation confirmed by a one-time code.
• An invitation is valid for 7 days, single-use, and reveals to the invitee only the organisation name and the proposed role — nothing else before acceptance.
• An account created from an invitation is locked to the invited address: a forwarded link cannot be used to join under another identity.

Switching organisation

Switching issues a new token scoped to the chosen organisation. A token carries a single scope: there is no header that lets you target another organisation on a per-request basis.

Projects & credentials

A project represents one integration: a store, an app, a backend.

• Each project carries a type (WooCommerce, Flutter, direct API, payment link), a domain or bundle ID, and its credentials.
• One project can hold both a sandbox key and a production key: the environment belongs to the credential.
• Notification endpoints attach to the project, which isolates integrations: a webhook outage on the store does not affect the mobile app.
• Split projects by real integration. Sharing one key between a store and an app makes every rotation risky and every incident unreadable.

Console API

The same data as the interface, should you want to build your own dashboards.

How operations are executed

What happens to a transaction between your API call and your customer's Mobile Money account.

Once the transaction is recorded, B-Cash hands it to its orchestration layer. That layer relays the operation to the relevant operator, follows its outcome and reports it back to the ledger. Your integration needs to know nothing about it: it observes statuses, not mechanisms.

What this means for you

• It is not instant. An operation crosses an external system: a few seconds normally, longer when an operator is under load. Design your screens around a wait, never around an immediate answer.
• Availability varies per operator. That is what the state field of GET /v1/operators is for: read it rather than assuming everything is always reachable.
• An outcome can remain unconfirmed. That case is covered below, and it is the only one that requires specific behaviour from you.

When the outcome is not confirmed

Occasionally an operation cannot be concluded immediately: the operator does not answer in a usable way, or confirmation does not arrive within the expected window. The transaction then moves to PENDING_RECONCILIATION and the funds involved stay reserved until reconciliation settles it.

Resolution is automatic: the transaction reaches a terminal status and the corresponding event is delivered to you. No action is required from you — and that is precisely the point.

WooCommerce

The shortest path: your store collects payments without you writing any code.

1. Create a WooCommerce project in the console and note its public key and sandbox secret.
2. Install the B-Cash extension in WooCommerce, then fill in the key, the secret and the environment.
3. Copy the notification URL shown by the extension and register it as an endpoint in the console, attached to that project.
4. Place a test order and force the outcome from the sandbox: the order should turn “paid” on its own.
5. Once your file is approved, replace the keys with production ones.

The extension sends context as WOOCOMMERCE and the order number in merchantReference: you can therefore trace any transaction from your WooCommerce back office.

Mobile apps

The pattern is simple, provided you never invert the roles: your backend holds the secret, never the app.

Mobile app          Your backend              B-Cash API
    │                     │                        │
    │  "I want to pay"    │                        │
    │────────────────────>│                        │
    │                     │  POST /v1/auth/token   │   (HMAC-signed)
    │                     │───────────────────────>│
    │                     │<── bt_… (TTL 600 s) ───│
    │<── ephemeral token ─│                        │
    │                                              │
    │  POST /v1/collections  (Bearer bt_…)         │
    │─────────────────────────────────────────────>│
    │<── nextAction: AWAIT_MOBILE_CONFIRMATION ────│
    │                                              │
    │  Waiting screen until expiresAt              │
    │                     │<── signed webhook ─────│
    │<── your push /      │                        │
    │    your polling ────│                        │

Rules on the app side

• Request a token with the bare minimum of scopes, just before payment.
• Display nextAction.displayMessage rather than a hard-coded string: it is adapted to the chosen operator.
• Honour expiresAt: show a countdown, and above all conclude nothing before it.
• Never show “payment successful” on the strength of a screen alone. Wait for the status returned by your backend, which is itself notified by webhook.
• An expired token is not a payment error: request another and carry on.

Custom backend

Direct integration: you control everything, so you carry everything.

Pre-production checklist

Minimal order state machine

async function handleEvent(event) {
  // 1. Deduplication: let the uniqueness constraint do the work
  if (await events.exists(event.id)) return;
  await events.insert(event.id);

  const tx = event.data.object;
  const order = await orders.findByReference(tx.merchantReference);
  if (!order) return;                       // event from another system

  // 2. Trust the STATUS on the object, never the arrival order
  switch (tx.status) {
    case 'SUCCEEDED':               return order.markPaid(tx);
    case 'FAILED':
    case 'EXPIRED':                 return order.markUnpaid(tx);
    case 'REVERSED':                return order.markRefunded(tx);
    case 'PENDING_RECONCILIATION':  return order.markUnderReview(tx);   // wait
    default:                        return;                            // transient state
  }
}

Statuses & types

Transaction statuses

CREATED, FEE_QUOTED, HELD, QUEUED, PROCESSING, PENDING_CONFIRMATION, SUCCEEDED, FAILED, CANCELLED, REVERSED, EXPIRED, PENDING_RECONCILIATION. Details in Transaction lifecycle.

Transaction types

Events

The exhaustive, current list is published in GET /api/v1/meta. An unknown event must be ignored without error: new types can appear within 1.x.

Scopes

An ephemeral token can only carry a strict subset of the scopes of the key that issued it. Grant each credential the minimum it needs: a store key has no reason to be able to pay out.

Versioning

The API is at version 1.3. Within 1.x, these guarantees hold:

• No existing field is removed or renamed.
• No enumeration value is withdrawn; new ones may appear.
• New optional fields may be added at any time.
• A deprecated field remains accepted but stops having an effect: that is the case for callbackUrl, ignored in favour of registered endpoints.

Practical consequence: your deserialisation must be tolerant. A client that crashes on an unknown field will break at the next minor release.

The apiVersion field on webhooks (e.g. 2026-07-20) dates the envelope format; keep it in your logs, it explains differences between older and newer events.

Status & support

/v1/meta is worth reading at least once: it publishes the enumerations, the exhaustive event list, the signature specification, the idempotency and quoting rules, and the error code catalogue. Everything this page describes is available there in a form your code can consume.

Contacting support effectively

Three items almost always settle an incident:

1. The correlationId from the error response.
2. The transaction reference, or your merchantReference.
3. The precise timestamp and the environment involved.

Write to support@gba-cm.online. Never send a secret or a screenshot containing a key: if you believe a secret has leaked, rotate it first and report afterwards.