Testing Mobile Money Payments Before Production: Sandbox, Test Numbers and Checklist

Putting a "Pay" button online without ever testing it means promising your customers an experience you have never seen work. In Senegal, where payments flow through Wave, Orange Money, Free Money and aggregators like PayDunya, CinetPay and Hub2, every integration has its own traps. A well-used sandbox saves you from discovering bugs with real money and unhappy customers.

This guide explains how to test a mobile money payment end to end: which environments exist, which test numbers to use, which scenarios to cover, and how to switch to production without breaking everything.

Why sandbox testing is non-negotiable

A mobile money payment is not a simple API call that answers instantly. It is a chain: your server calls the aggregator, which contacts the operator, which sends a USSD push or notification to the customer's phone, who validates with a PIN, and the confirmation comes back through an asynchronous webhook, sometimes several seconds later.

Every link can fail. The customer may decline, have no balance, enter a wrong PIN, or simply never see the push. If you only test the "happy path" in production, you will not know what your customer sees when it fails. The sandbox lets you replay all these cases at will, without moving a single CFA franc.

What the sandbox actually reproduces

A good test environment simulates operator responses: success, failure, insufficient balance, timeout, user cancellation. It also gives you test webhooks to validate that your back end reacts correctly. What it does not always simulate well: the real network latency in Senegal and the exact behavior of the USSD push on old phones. Keep that limit in mind.

The test environments of the main players

In Senegal, your integrations almost always go through an aggregator rather than directly through the operator. Here is the landscape.

PayDunya

PayDunya provides a test mode activated by a simple different API key (the key starts with "test_" instead of "live_"). You create a transaction as in production, but no real debit happens. The platform returns simulated statuses you can force. It is one of the easiest to get started with for a Senegalese project.

CinetPay

CinetPay offers a test account distinct from the production account, with its own credentials (site_id and apikey). Amounts are fictitious and you can trigger the different return codes. Be sure to separate your environment variables between test and prod, because mixing keys is the leading cause of incidents when going live.

Hub2

Hub2 exposes a unified multi-operator API with a documented sandbox environment. It is useful when you want to accept Wave, Orange Money and MTN without integrating each operator separately. The sandbox returns test numbers and responses for each method.

Orange Money and Wave directly

Orange Money Web Payment has a development environment with test numbers and a simulated validation flow. Wave, on its side, favors integration via payment link or checkout; its test environment is more restricted, one more reason to go through an aggregator if you want a rich sandbox.

Test numbers and data

Each aggregator publishes test numbers in its documentation. Do not invent them: a random number will return a generic error that teaches you nothing. The official numbers trigger precise behaviors.

Typically you will find:

• A number that always returns success.
• A number that always returns failure (operator decline).
• A number that simulates insufficient balance.
• A number that never responds, to test your timeout.

Note these numbers in your internal documentation. Your developers and QA must be able to replay a failure in ten seconds without searching.

The scenarios you must absolutely cover

Testing only the successful payment is the classic mistake. Here is the minimum matrix.

1. Successful payment

The nominal case. Verify that the confirmation webhook arrives, that the order moves to "paid", that the receipt is sent, and that the customer sees a clear success page.

2. Declined payment

The operator rejects it. Verify that the order stays pending or moves to "failed", that the customer sees an understandable message (not a technical code), and that they can retry.

3. Insufficient balance

Very common in Senegal. The message must be explicit: "Insufficient balance, please top up your account." Above all, do not mark the order as paid.

4. Timeout / no response

The customer never validated the push. Your system must wait a reasonable delay then mark the transaction "expired", without losing it. This is where idempotency matters.

5. Double submission

The customer clicks "Pay" twice. You must generate an idempotency key per attempt to never debit twice. Test it explicitly.

6. Duplicate or late webhook

Aggregators sometimes resend the same webhook several times. Your back end must process the first and ignore the rest for the same transaction.

Customer mini case: a delivery site in Dakar

A prepared-meals shop delivering in Dakar contacted us after a failed launch. Going straight to production without a sandbox, 18% of their orders stayed stuck in "awaiting payment" while the customer had actually paid. The webhook arrived, but their code processed it before the order was recorded, and matched it to an empty identifier.

We replayed the scenario in the CinetPay sandbox: webhook received on a non-existent order, then re-received 30 seconds later. The fix was to store the transaction at initiation, use the order reference as the key, and make webhook processing idempotent. After deployment, the rate of stuck orders fell below 1%. All of this was validated in the sandbox before a single real transaction.

Moving to production without breaking

Going live is the moment when everything can go wrong. A few rules.

Strictly separate your keys

Test and live keys must never coexist in the same file without a clear distinction. Use environment variables and verify at startup that you are loading the right set for the environment.

Make a real low-amount transaction

Before opening to the public, place a real order of 100 FCFA with your own number. Verify the debit, the webhook, the receipt, the success page. Refund yourself afterwards. It is your last safety net.

Watch the first 24 hours

Set up alerts on transactions that stay "pending" too long. The first hours reveal the cases the sandbox did not cover.

Developer checklist

Before declaring a payment "production ready":

• Test and live keys are separated and loaded by environment.
• The six scenarios (success, decline, insufficient balance, timeout, double click, duplicate webhook) are tested in the sandbox.
• Idempotency prevents any double debit.
• The webhook is verified (signature) and idempotent.
• Error messages are in plain language, not technical codes.
• A real low-amount transaction has been validated end to end.
• Alerts exist for stuck transactions.

FAQ

Is the sandbox really faithful to production?

It is faithful for logic (statuses, webhooks, return codes) but not always for network latency or the behavior of the USSD push on old phones. That is why a real low-amount transaction remains essential before opening.

Which aggregator offers the simplest sandbox in Senegal?

PayDunya is often the fastest to get started with thanks to the simple key change between test and live. CinetPay and Hub2 are more complete if you target several operators.

How do I test a timeout without waiting minutes?

Use the aggregator's dedicated test number that never responds. Your code must then trigger its expiration logic. You control the delay instead of being at the mercy of the network.

Do I need to test each operator separately?

Yes. Wave, Orange Money and Free Money have different flows and messages. A scenario that works on one can break on another, especially on the error messages shown to the customer.

What if the aggregator has no sandbox for a method?

Use an aggregator that provides one, or test with real controlled micro-transactions. Never launch a never-tested payment method directly on real customers.

Let's talk about your project. Integrating a mobile money payment and want to test it seriously before launch? Write to us on WhatsApp +221 77 596 93 33.