Logo GenukaGenuka Pay
Guides

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

Authenticated Sandbox Request
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURE

What 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

  1. initiate a payment with a small amount
  2. store the returned track_id
  3. verify webhook delivery
  4. compare webhook state with GET /payments/status/{track_id}
  5. test failure handling and retry behavior
  6. 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.

NumberOperatorOutcome
+237670000001MTN CameroonSUCCESS
+237670000002MTN CameroonFAILED
+237670000003MTN Cameroonpending, then SUCCESS after ~5 s
+237670000004MTN Cameroonfails, insufficient funds
+237690000001Orange CameroonSUCCESS
+237690000002Orange CameroonFAILED
+237690000003Orange Cameroonpending, then SUCCESS after ~5 s
+237690000099Orange Cameroonfails, insufficient funds
+2250700000001Ivory CoastSUCCESS
+2250700000002Ivory CoastFAILED
+2250700000003Ivory Coastpending, then SUCCESS after ~5 s
+2250700000004Ivory Coastfails, insufficient funds
+241077000001Airtel GabonSUCCESS
+241077000002Airtel GabonFAILED
+241077000003Airtel Gabonpending, then SUCCESS after ~5 s
+241077000099Airtel Gabonfails, insufficient funds
+241066000001Moov GabonSUCCESS
+241066000002Moov GabonFAILED
+241066000003Moov Gabonpending, then SUCCESS after ~5 s
+241066000099Moov Gabonfails, insufficient funds
+23566000001Airtel ChadSUCCESS
+23566000002Airtel ChadFAILED
+23566000003Airtel Chadpending, then SUCCESS after ~5 s
+23566000099Airtel Chadfails, insufficient funds
+23590000001Moov ChadSUCCESS
+23590000002Moov ChadFAILED
+23590000003Moov Chadpending, then SUCCESS after ~5 s
+23590000099Moov Chadfails, insufficient funds
+23672000001Orange Central African RepublicSUCCESS
+23672000002Orange Central African RepublicFAILED
+23672000003Orange Central African Republicpending, then SUCCESS after ~5 s
+23672000099Orange Central African Republicfails, insufficient funds
+242066000001MTN CongoSUCCESS
+242066000002MTN CongoFAILED
+242066000003MTN Congopending, then SUCCESS after ~5 s
+242066000099MTN Congofails, insufficient funds
+242055000001Airtel CongoSUCCESS
+242055000002Airtel CongoFAILED
+242055000003Airtel Congopending, then SUCCESS after ~5 s
+242055000099Airtel Congofails, insufficient funds
+240555000001Muni Dinero (Equatorial Guinea)SUCCESS
+240555000002Muni Dinero (Equatorial Guinea)FAILED
+240555000003Muni Dinero (Equatorial Guinea)pending, then SUCCESS after ~5 s
+240555000099Muni Dinero (Equatorial Guinea)fails, insufficient funds
+22360000001Moov MaliSUCCESS
+22360000002Moov MaliFAILED
+22360000003Moov Malipending, then SUCCESS after ~5 s
+22360000099Moov Malifails, insufficient funds
+22660000001Moov Burkina FasoSUCCESS
+22660000002Moov Burkina FasoFAILED
+22660000003Moov Burkina Fasopending, then SUCCESS after ~5 s
+22660000099Moov Burkina Fasofails, insufficient funds
+22665000001Orange Burkina FasoSUCCESS
+22665000002Orange Burkina FasoFAILED
+22665000003Orange Burkina Fasopending, then SUCCESS after ~5 s
+22665000099Orange Burkina Fasofails, insufficient funds
+22870000001TMoney (Togo)SUCCESS
+22870000002TMoney (Togo)FAILED
+22870000003TMoney (Togo)pending, then SUCCESS after ~5 s
+22870000099TMoney (Togo)fails, insufficient funds
+22897000001Moov TogoSUCCESS
+22897000002Moov TogoFAILED
+22897000003Moov Togopending, then SUCCESS after ~5 s
+22897000099Moov Togofails, insufficient funds
+2290164000001Moov BeninSUCCESS
+2290164000002Moov BeninFAILED
+2290164000003Moov Beninpending, then SUCCESS after ~5 s
+2290164000099Moov Beninfails, 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 PROCESSING until somebody clicks — like a real Wave payment, which waits for the payer.
  • Pay applies the outcome your test number asked for: +2250700000004 still 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_url with status and reference, 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 …01 or …02 number is settled in the response itself (SUCCESS or FAILED). A "pending" number first answers with no final outcome, then the payment moves to SUCCESS about 5 seconds later. transaction.* webhooks are sent to the sandbox environment's endpoints.
  • CARD requires card payments to be enabled on your account, as in live.
  • Payouts follow the same path as in live: they stay in AWAITING_APPROVAL until approved.
  • KYC ceilings do not apply in sandbox, and no WhatsApp receipt is sent.

Example Sandbox Payment

Create a Test 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

  1. complete KYC verification
  2. confirm your current limits in the dashboard (KYC page)
  3. configure production webhook endpoints
  4. rotate credentials if required by your deployment workflow
  5. 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