Skip to main content

​
Overview

Sandbox is designed to help you test real production behaviors in a safe environment. In particular, you can trigger a mock deposit for an NGN or crypto funding account:

​
What it validates

  • Your deposit lifecycle UI/state machine
  • Your webhook endpoint (signature verification + idempotency + retries)
  • Your handling of edge cases like deposits that require review

​
Flagging behavior (important)

Sandbox follows the same rules engine as production. As a result, simulated deposits may require review automatically:
  • Rate expired: If the quote/rate tied to the funding account is expired, the deposit will be flagged.
  • Re-used temporary NGN account: If a deposit has already been created for the same temporary receive instruction, subsequent simulated deposits may be flagged.
If you want a clean happy path test, create a fresh funding account, then trigger the sandbox deposit immediately. For crypto funding accounts, you can either use this helper with funding_account_id or send testnet USDC/USDT to the returned address.

​
Sandbox Bank Accounts

When testing crypto funding accounts with NGN_PAYOUT settlement, use the following test bank accounts:
FieldValue
Bank code044
Account numbers0690000031, 0690000032, 0690000033, …
Increment the last digit of the account number to generate additional test accounts. Resolve them with POST /v1/banks/resolve before use — just like production.

​
NGN receive instruction

  1. Call GET /v1/rates?side=BUY to get a fresh rate_id
  2. Create a sandbox NGN funding account with rail: NGN_VIRTUAL_ACCOUNT
  3. Call POST /v1/sandbox/deposits with the returned funding account id as funding_account_id
  4. Observe status progression and confirm you receive the expected webhooks (deposit.received, then deposit.completed / deposit.failed / deposit.requires_review)

​
Crypto funding account

  1. Call POST /v1/banks/resolve to verify the test bank account
  2. Call GET /v1/rates?side=SELL to get a fresh rate_id
  3. Call POST /v1/funding-accounts with rail: CRYPTO_ADDRESS, asset, chain, and NGN_PAYOUT settlement
  4. Call POST /v1/sandbox/deposits with the returned funding account id as funding_account_id, or send test crypto to the returned address
  5. Observe deposit webhook events (deposit.received, then deposit.completed / deposit.failed / deposit.requires_review)

​
Getting Testnet USDC

To test crypto deposits in sandbox, you need testnet USDC. Use the Circle faucet to get free testnet USDC:

Circle USDC Faucet

Get free testnet USDC to send to your sandbox crypto funding account addresses

​
Next Steps

Webhooks Overview

Ensure your webhook endpoint is receiving deposit events

Webhook Verification

Verify signatures correctly and handle retries safely