Test Mode
Validate your payment, payout, webhook, and reconciliation flows safely before enabling production traffic.
Introduction
Test mode should validate more than request syntax. It should prove that your backend, event handling, retries, and reconciliation logic behave correctly before any real funds are involved.
Sandbox Validation
Exercise payment and payout creation with controlled low-risk inputs.
Webhook Readiness
Confirm that webhook deliveries match your expected asynchronous lifecycle handling.
Reconciliation Confidence
Compare status polling, event delivery, and internal ledger references before launch.
Required Headers
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATUREWhat to Validate in Test
- payment initiation
- payout initiation
- webhook reception
- retry handling
- transaction status reconciliation
- internal ledger correlation through
external_id - the payer's return to your
return_url/cancel_url, for redirect operators
Suggested Checklist
- initiate a payment with a small amount
- store the returned
track_id - verify webhook delivery
- compare webhook state with
GET /payments/status/{track_id} - test failure handling and retry behavior
- confirm KYC status before enabling live usage
Test numbers
In sandbox, the outcome of a payment is decided by the payer's number. No real debit, no prompt on a real handset.
| Number | Operator | Outcome |
|---|---|---|
+237670000001 | MTN Cameroon | SUCCESS |
+237670000002 | MTN Cameroon | FAILED |
+237670000003 | MTN Cameroon | pending, then SUCCESS after ~5 s |
+237670000004 | MTN Cameroon | fails, insufficient funds |
+237690000001 | Orange Cameroon | SUCCESS |
+237690000002 | Orange Cameroon | FAILED |
+237690000003 | Orange Cameroon | pending, then SUCCESS after ~5 s |
+237690000099 | Orange Cameroon | fails, insufficient funds |
+2250700000001 | Ivory Coast | SUCCESS |
+2250700000002 | Ivory Coast | FAILED |
+2250700000003 | Ivory Coast | pending, then SUCCESS after ~5 s |
+2250700000004 | Ivory Coast | fails, insufficient funds |
+241077000001 | Airtel Gabon | SUCCESS |
+241077000002 | Airtel Gabon | FAILED |
+241077000003 | Airtel Gabon | pending, then SUCCESS after ~5 s |
+241077000099 | Airtel Gabon | fails, insufficient funds |
+241066000001 | Moov Gabon | SUCCESS |
+241066000002 | Moov Gabon | FAILED |
+241066000003 | Moov Gabon | pending, then SUCCESS after ~5 s |
+241066000099 | Moov Gabon | fails, insufficient funds |
+23566000001 | Airtel Chad | SUCCESS |
+23566000002 | Airtel Chad | FAILED |
+23566000003 | Airtel Chad | pending, then SUCCESS after ~5 s |
+23566000099 | Airtel Chad | fails, insufficient funds |
+23590000001 | Moov Chad | SUCCESS |
+23590000002 | Moov Chad | FAILED |
+23590000003 | Moov Chad | pending, then SUCCESS after ~5 s |
+23590000099 | Moov Chad | fails, insufficient funds |
+23672000001 | Orange Central African Republic | SUCCESS |
+23672000002 | Orange Central African Republic | FAILED |
+23672000003 | Orange Central African Republic | pending, then SUCCESS after ~5 s |
+23672000099 | Orange Central African Republic | fails, insufficient funds |
+242066000001 | MTN Congo | SUCCESS |
+242066000002 | MTN Congo | FAILED |
+242066000003 | MTN Congo | pending, then SUCCESS after ~5 s |
+242066000099 | MTN Congo | fails, insufficient funds |
+242055000001 | Airtel Congo | SUCCESS |
+242055000002 | Airtel Congo | FAILED |
+242055000003 | Airtel Congo | pending, then SUCCESS after ~5 s |
+242055000099 | Airtel Congo | fails, insufficient funds |
+240555000001 | Muni Dinero (Equatorial Guinea) | SUCCESS |
+240555000002 | Muni Dinero (Equatorial Guinea) | FAILED |
+240555000003 | Muni Dinero (Equatorial Guinea) | pending, then SUCCESS after ~5 s |
+240555000099 | Muni Dinero (Equatorial Guinea) | fails, insufficient funds |
+22360000001 | Moov Mali | SUCCESS |
+22360000002 | Moov Mali | FAILED |
+22360000003 | Moov Mali | pending, then SUCCESS after ~5 s |
+22360000099 | Moov Mali | fails, insufficient funds |
+22660000001 | Moov Burkina Faso | SUCCESS |
+22660000002 | Moov Burkina Faso | FAILED |
+22660000003 | Moov Burkina Faso | pending, then SUCCESS after ~5 s |
+22660000099 | Moov Burkina Faso | fails, insufficient funds |
+22665000001 | Orange Burkina Faso | SUCCESS |
+22665000002 | Orange Burkina Faso | FAILED |
+22665000003 | Orange Burkina Faso | pending, then SUCCESS after ~5 s |
+22665000099 | Orange Burkina Faso | fails, insufficient funds |
+22870000001 | TMoney (Togo) | SUCCESS |
+22870000002 | TMoney (Togo) | FAILED |
+22870000003 | TMoney (Togo) | pending, then SUCCESS after ~5 s |
+22870000099 | TMoney (Togo) | fails, insufficient funds |
+22897000001 | Moov Togo | SUCCESS |
+22897000002 | Moov Togo | FAILED |
+22897000003 | Moov Togo | pending, then SUCCESS after ~5 s |
+22897000099 | Moov Togo | fails, insufficient funds |
+2290164000001 | Moov Benin | SUCCESS |
+2290164000002 | Moov Benin | FAILED |
+2290164000003 | Moov Benin | pending, then SUCCESS after ~5 s |
+2290164000099 | Moov Benin | fails, insufficient funds |
Gabon and Congo require the domestic trunk 0 in this format (+241077..., not +24177...) — that's the form Peex itself validates. Benin uses the ten-digit numbering plan in effect since November 30, 2024 (a fixed 01 ahead of the old eight-digit number).
Any other number is rejected in sandbox. That is deliberate: it stops a flow from looking healthy when it simulated nothing.
Redirect operators: the test payment page
Bank card, Orange, Wave and Djamo send the payer to a page. In sandbox, redirect_url points at a Genuka Pay test page standing in for the operator, with two buttons: Pay and Cancel.
What that changes:
- The payment does not settle on its own. It stays
PROCESSINGuntil somebody clicks — like a real Wave payment, which waits for the payer. - Pay applies the outcome your test number asked for:
+2250700000004still fails with insufficient funds, it just fails where a real payment would. - Cancel fails the payment with the code
PAYMENT_DECLINED. - Either way you land on your
return_url/cancel_urlwithstatusandreference, through exactly the same code as production.
This is the only way to test your return URL
Always send return_url when testing a redirect operator. Without it the test page sends you to the Genuka Pay homepage — which is precisely what your customer would get in live.
What Behaves Like Live
- Sandbox keys start with
pk_test_/sk_test_; there is no header or URL to change. - A mobile money payment on a
…01or…02number is settled in the response itself (SUCCESSorFAILED). A "pending" number first answers with no final outcome, then the payment moves toSUCCESSabout 5 seconds later.transaction.*webhooks are sent to the sandbox environment's endpoints. CARDrequires card payments to be enabled on your account, as in live.- Payouts follow the same path as in live: they stay in
AWAITING_APPROVALuntil approved. - KYC ceilings do not apply in sandbox, and no WhatsApp receipt is sent.
Example Sandbox Payment
curl -X POST "https://api-pay.genuka.com/api/v1/payments" \
-H "X-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Timestamp: UNIX_TIMESTAMP" \
-H "X-Signature: HMAC_SHA256_SIGNATURE" \
-H "Content-Type: application/json" \
-d '{
"amount": 100,
"currency": "XAF",
"payer_phone": "+237670000001",
"external_id": "test_payment_001"
}'Before Going Live
- complete KYC verification
- confirm your current limits in the dashboard (KYC page)
- configure production webhook endpoints
- rotate credentials if required by your deployment workflow
- start with low-risk amounts and monitor closely
Launch principle
Sandbox readiness is about operational confidence, not just successful HTTP responses. If your webhook, retry, or reconciliation logic is still ambiguous, you are not done testing.
How is this guide?
Last updated on