Testing in Sandbox

Every Afriex environment behaves the same way on the wire: your requests, responses, webhooks and error codes are identical between sandbox and production. Sandbox just refuses to move real money.

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_INSTANT anywhere in meta.reference when 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.

Either way the 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.

Ends in	Payout (`WITHDRAW`)	Mobile money deposit (`DEPOSIT`)	Card deposit (`DEPOSIT`, via checkout)
anything else	Succeeds	Succeeds	Succeeds
`0001`	Fails; your balance is refunded	Fails	Fails
`0002`	Succeeds	Waits for a one-time password (see OTP)	Succeeds
`0003`	Stays pending until you call `/simulate`	Stays pending until you call `/simulate`	Stays pending until you call `/simulate`
`0004`	Account name lookup (`/resolve`) fails	Succeeds	Succeeds
`0005`	Declined immediately	Declined immediately	Declined immediately

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 in 0003 puts the transaction in PENDING and holds it there until you tell the sandbox what to do. Call Simulate Transaction Outcome:

curl -X POST \
  -H "x-api-key: YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "success"}' \
  https://sandbox.api.afriex.com/api/v1/transaction/TRANSACTION_ID/simulate

Pass {"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 in 0002 returns CUSTOMER_ACTION_REQUIRED. Complete it with Authorize Transaction using the sandbox OTP 123456:

curl -X POST \
  -H "x-api-key: YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"OTP","otp":"123456"}' \
  https://sandbox.api.afriex.com/api/v1/transaction/TRANSACTION_ID/authorize

Any other OTP returns 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:

# Reusable virtual account (created without an amount)
curl -X POST \
  -H "x-api-key: YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accountNumber": "4821930275", "amount": 5000, "currency": "NGN"}' \
  https://sandbox.api.afriex.com/api/v1/payment-method/virtual-account/simulate-transfer

For a one-time virtual account (created with an 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:

Create a checkout session

Call Create Checkout Session with channels including "CARD". Redirect the payer to the returned checkoutUrl.

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.

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 (0001 fails, 0002 asks for an OTP, 0005 is 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.

Want to try the hosted checkout end to end without touching the API first? Open the sandbox demo, pick a currency and amount, and click Proceed to payment. All three channels are covered, allocated per currency: mobile money (KES, GHS and others), bank transfer (NGN), and card (USD). Use the same test values documented above to drive different outcomes.

Funding your sandbox balance

Payouts and swaps need funds in your sandbox wallets. Call Top Up Sandbox Balance whenever you need more:

curl -X POST \
  -H "x-api-key: YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency": "USD", "amount": 10000}' \
  https://sandbox.api.afriex.com/api/v1/org/balance/topup

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:

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.

Verify signatures

Trigger a test webhook and confirm you reject a tampered body and accept a valid one.

Reconcile with merchantReference

Look up transactions by merchantReference and confirm your idempotency keys behave as expected on retry.

Switch base URL and keys

Swap sandbox.api.afriex.com for api.afriex.com and your sandbox key for a production key. No other code changes are required.

Something behaving differently?

Sandbox and production run the same code paths. If you see divergence, email support@afriex.com with the request id and we’ll dig in.

Getting started

Core Concepts

Testing

See the hosted checkout in 30 seconds

When a transaction settles

Choosing the outcome with the last 4 digits

Simulating a pending transaction

OTP-required mobile money deposits

Simulating an incoming bank transfer

Testing cards

Hosted checkout in sandbox

Funding your sandbox balance

Drilling your webhook handler

Checklist before going live

Something behaving differently?

See the hosted checkout in 30 seconds

​When a transaction settles

​Choosing the outcome with the last 4 digits

​Simulating a pending transaction

​OTP-required mobile money deposits

​Simulating an incoming bank transfer

​Testing cards

​Hosted checkout in sandbox

​Funding your sandbox balance

​Drilling your webhook handler

​Checklist before going live

Something behaving differently?

When a transaction settles

Choosing the outcome with the last 4 digits

Simulating a pending transaction

OTP-required mobile money deposits

Simulating an incoming bank transfer

Testing cards

Hosted checkout in sandbox

Funding your sandbox balance

Drilling your webhook handler

Checklist before going live