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

​
Testing specific deposit outcomes

Use scenario with POST /v1/sandbox/deposits when you need to trigger a specific lifecycle state.
Supported scenarios:
If you omit scenario, sandbox runs the default processing flow. Use the default flow when you want to test production-like behavior and natural intermediate states, and use scenario when you want deterministic state testing.
PROCESSING and COMPLETED scenarios still use the funding account’s active settlement destination. Make sure the funding account is active, has an active settlement destination, and includes any required rate_id, destination wallet, or destination bank details before triggering those outcomes.

​
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: 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