Accepting Mobile Money in francophone West Africa isn't a matter of wiring up a Stripe-like SDK and waiting for a clean webhook five seconds later. Every operator (Wave, Orange Money, MTN MoMo, Moov) runs its own authorization flow, its own callback format, its own delays, and no shared standard ties them together. The actual engineering work isn't calling the initiation API, it's building a reconciliation layer that stays correct around asynchronous, sometimes silent, flows.

Why this isn't a "Stripe plugin" problem

With a card payment, authorization is synchronous: accepted or declined within a few hundred milliseconds. With Mobile Money, the payment almost always goes through a confirmation step on the customer's own phone - a USSD prompt, a push notification to approve, or a PIN entered inside a third-party app. Between the initiation API call and the actual confirmation, anywhere from a few seconds to several minutes can pass, and the callback notifying the result is never guaranteed to arrive exactly once, in order, or at all. On top of that, payer identity is based on a phone number rather than a stable account identifier, which brings its own normalization pitfalls.

The generic flow worth building

Regardless of the operator, the skeleton that actually holds up in production always follows the same logic:

  1. Create a local transaction record in a pending state, with a server-generated idempotency key.
  2. Call the provider's initiation API with that key and the phone number, which triggers the prompt on the customer's phone.
  3. Store the external reference the provider returns.
  4. Wait for the webhook callback that confirms or rejects the transaction, verifying its signature.
  5. Update the local state, treating duplicates as a normal case, not an exception.
  6. Run a periodic reconciliation job for transactions that never received a callback.
// Generic webhook controller (Node/Express)
// Every provider has its own signature scheme, but the principle is identical:
// verify before trusting anything in the request body.
const crypto = require('crypto');

app.post('/webhooks/mobile-money/:provider', express.raw({ type: '*/*' }), (req, res) => {
  const signatureHeader = req.headers['x-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected))) {
    return res.status(401).send('invalid signature');
  }

  const payload = JSON.parse(req.body);
  // Always respond 200 quickly, push the business logic to a queue
  queueTransactionReconciliation(req.params.provider, payload);
  res.status(200).send('ok');
});

Idempotency: the real core of the problem

Mobile Money providers sometimes send the same callback two or three times - a network timeout on their end, an automatic retry, or a duplicate notification for the same event. If handling a webhook credits an account or unlocks an order without a check, a duplicate callback can credit it twice. Protection should never rely solely on application logic: a uniqueness constraint in the database on (provider, external reference) is the only guarantee that survives a code bug.

-- The uniqueness constraint is the real anti-duplicate barrier,
-- not just an application-level check before insert
CREATE UNIQUE INDEX idx_transactions_provider_ref
  ON transactions (provider, external_reference);

-- The insert silently fails on a duplicate instead of duplicating the effect
INSERT INTO transactions (provider, external_reference, status, amount)
VALUES ($1, $2, $3, $4)
ON CONFLICT (provider, external_reference) DO NOTHING;

Diagnosing a "ghost" payment

The classic production symptom: a customer swears they paid, but the order sits pending on the application side. Three systematic checks before suspecting a bug:

  • Review the raw logs of received webhooks (always store them as-is, before any processing, so they can be replayed).
  • Query the provider's status API with the stored external reference, instead of trusting the callback alone.
  • Check phone number normalization - a number stored in local format (07XXXXXXXX) will never match a number returned in international format (+225XXXXXXXXXX) in a join or lookup.
# Replay a stored webhook locally to debug it
curl -X POST http://localhost:3000/webhooks/mobile-money/wave \
  -H "x-signature: $(cat stored_signature.txt)" \
  --data-binary @stored_payload.json

The fix: reconciliation as a safety net, not an option

The webhook should never be the sole source of truth. A scheduled job that periodically queries the provider's status endpoint for pending transactions older than a few minutes closes the loop whenever a callback was lost. The tradeoff is real: every reconciliation call consumes an API quota that's often rate-limited on the provider's side, so frequency needs calibration - every two to five minutes for recent transactions, spacing out progressively for older ones, rather than constant aggressive polling.

When the "simple" webhook isn't enough

Every operator carries its own rough edges that no generic documentation fully covers:

  • Some providers require an IP allow-list before they'll send callbacks to a given server, which complicates multi-region deployments or shared staging environments.
  • Others don't guarantee a webhook at all for certain transaction types and require pure polling instead.
  • The shape and field names of the callback (amount, currency, status) differ from one operator to the next, which calls for an internal normalization layer rather than letting native formats leak into the rest of the application.
  • A customer's phone number change (SIM reassignment, number portability) can silently invalidate what was assumed to be a stable customer identifier for recurring payments.
  • During a partial outage at one operator, a circuit breaker that switches the UX to an explicit message ("Wave is temporarily unavailable, try Orange Money instead") beats a silent retry loop that multiplies initiation attempts on the client side.

Testing without real money

Sandbox environments provided by operators never faithfully reproduce production behavior. Confirmation delay there is often instant or constant, while in production it varies significantly with the operator's network load and how quickly the customer responds to the prompt on their phone. Processing code tested only against a sandbox can therefore look reliable while never having faced a callback arriving after thirty seconds, or two callbacks arriving out of order.

// Simulate out-of-order, delayed callbacks locally,
// instead of only testing the sandbox's happy path
async function simulateDelayedCallback(payload, delayMs) {
  await new Promise((resolve) => setTimeout(resolve, delayMs));
  return fetch('http://localhost:3000/webhooks/mobile-money/wave', {
    method: 'POST',
    headers: { 'x-signature': signPayload(payload) },
    body: JSON.stringify(payload),
  });
}

// Two deliveries deliberately out of order and with variable latency
simulateDelayedCallback(payload, 200);
simulateDelayedCallback(payload, 4000);

A second frequent gap between sandbox and production involves test phone numbers: most operators restrict sandboxes to a dedicated range of fictitious numbers that never trigger a real confirmation step on an actual phone. A complete test path should therefore include, before going live, a gradual rollout phase (a feature flag by percentage of users or by city) with real numbers and small amounts, to observe actual callback behavior without exposing the entire customer base to a potential bug.

Takeaway

Mobile Money integration should be built as an asynchronous distributed system, not as a card payment: reliability comes from an end-to-end idempotency key, a uniqueness constraint in the database, and a reconciliation job that never depends solely on the webhook. Operator-specific quirks belong at the edges of the system, never leaking their native formats into the application's core.