Base URL:
https://sandbox.api.afriex.com, with a sandbox API key.
Deposits, payouts, and virtual accounts can all be tested on every payment method and currency your business supports.See the hosted checkout in 30 seconds
Try the sandbox demo, no API key or code required. Pick a currency and amount, click Proceed to payment, and walk through mobile money or bank transfer as your customers would. The demo is sandbox-only and uses the real hosted checkout page under the hood.
When a transaction settles
A sandbox deposit or payout completes on its own about 5 minutes after it is created, and your webhook receives the final status exactly as in production. When you need it sooner:- Include
SIMULATE_INSTANTanywhere inmeta.referencewhen you create the transaction, and it completes in about 30 seconds. - Or call Simulate Transaction Outcome with
{"outcome": "success"}or{"outcome": "failed"}to finalize it immediately.
TRANSACTION.UPDATED webhook is sent when the transaction settles.
Choosing the outcome with the last 4 digits
The last four digits of the account number, the phone number, or the card number decide what happens. Everything else about the account is up to you, so you can build one payment method per outcome and reuse it across tests. A payment method with none of these to key off (an email or a wallet address, for example) simply succeeds unless you complete it with/simulate.
Cards are hosted-checkout only. The “Card deposit” column above applies to card payments made through a checkout session; Create Payment Method does not accept
CARD as a channel.A phone number must still be a valid mobile number for its country, so keep the country prefix and change only the last digits. For example
+254712340002 in Kenya. Account name lookups against a sandbox account return Sandbox Test Account.Simulating a pending transaction
Any payment method ending in0003 puts the transaction in PENDING and holds it there until you tell the sandbox what to do. Call Simulate Transaction Outcome:
{"outcome": "failed"} to test your failure path. The result arrives by the TRANSACTION.UPDATED webhook shortly after this call returns.
You can use the same endpoint to complete any pending sandbox transaction early, not just ones ending in 0003. The transaction must still be PENDING, PROCESSING, or UNKNOWN; a deposit waiting on OTP (CUSTOMER_ACTION_REQUIRED) has to be authorized first.
OTP-required mobile money deposits
A mobile-money deposit from a wallet ending in0002 returns CUSTOMER_ACTION_REQUIRED. Complete it with Authorize Transaction using the sandbox OTP 123456:
OTP_INCORRECT, so you can test the wrong-OTP path too. After authorization the deposit completes on the normal sandbox timeline (or you can accelerate it via /simulate).
Simulating an incoming bank transfer
Sandbox virtual accounts receive no money on their own. Pay into one with Simulate Virtual Account Transfer:amount), also pass the reference the account was issued with. Pass "outcome": "failed" to simulate a failed inflow. The credit lands as a transaction and is reported by webhook.
Testing cards
Cards are only collected through a hosted checkout session, never through Create Payment Method. To test a card deposit:1
Create a checkout session
Call Create Checkout Session with
channels including "CARD". Redirect the payer to the returned checkoutUrl.2
Enter a test card
On the hosted page, use a test card whose last four digits pick the outcome from the table above (
0001 fails, 0003 stays pending, and so on). The hosted page pre-fills a valid test card in read-only form on sandbox, so you can click Pay without typing anything.3
Observe the transaction
The card deposit lands as a
DEPOSIT transaction and settles on the sandbox timeline described above. Use /simulate to finalize a 0003 pending card deposit on demand.Hosted checkout in sandbox
A checkout session started with a sandbox API key opens the hosted page in test mode, with helpers built in so you don’t have to memorize the test values above:- A Test mode badge in the page header.
- The mobile-money test numbers (
0001fails,0002asks for an OTP,0005is declined) are listed on the mobile-money screen. - The OTP hint (
123456) is shown when an OTP is required. - Simulate transfer / Simulate failed transfer buttons on the bank-transfer screen finalize the deposit without you needing to leave the page.
- Card fields are pre-filled with a valid test card in read-only form.
Funding your sandbox balance
Payouts and swaps need funds in your sandbox wallets. Call Top Up Sandbox Balance whenever you need more:"walletType": "FEE" (the wallet that settles transaction fees) or "walletType": "DEPOSIT" (the Collection wallet). Read the result back with Get Balance and the same walletType.
The topup endpoint only works in sandbox; production returns 403.
Drilling your webhook handler
Verify signatures, retries, and downstream handling with a synthetic event from Trigger Test Webhook. Configure your webhook URL in the Dashboard first.Checklist before going live
Once you’re comfortable in sandbox:1
Exercise every branch
Run a
success, a failed, an OTP flow (0002), and a 0003 pending flow. Confirm your webhook handler branches correctly on each.2
Verify signatures
Trigger a test webhook and confirm you reject a tampered body and accept a valid one.
3
Reconcile by reference
Look up transactions with List Transactions and
?reference=, the meta.reference you sent. Confirm that a retry with the same idempotency key returns 409 and creates nothing. See Idempotency.4
Switch to production settings
Your code stays the same, but these settings differ between sandbox and production:
- Base URL. Use
https://api.afriex.cominstead ofhttps://sandbox.api.afriex.com. - API key. Create a key in Live mode, with only the permissions your integration needs.
- Webhook public key. Production signs webhooks with a different key. Copy it from Developer → Webhook in live mode, or every signature check fails.
- Webhook IP address. Production webhooks come from
34.197.33.100, not the sandbox address. Allow it on your firewall. See Afriex IP addresses. - API allowlist. If you use an IP allowlist, add your production servers’ public addresses. Allow all IPs isn’t available in live mode.
Something behaving differently?
Sandbox and production run the same code paths. If you see divergence, email
support@afriex.com with the request’s x-request-id response header and we’ll dig in. See Request IDs.