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. Payouts, mobile-money deposits, card deposits, and virtual accounts can all be tested in every currency your business supports.

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 bank account number, the mobile money 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.

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).

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.

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

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

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

​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

Funding your sandbox balance

Drilling your webhook handler

Checklist before going live