Sandbox Testing Guide

The NadaPay sandbox is a fully functional replica of the production API with no real money movement. This page covers what the sandbox does differently, how to simulate key scenarios, and how to use it effectively before going live.

What the sandbox does differently

Sandbox base URL

https://sandbox.api.nadapay.com/v1

Your sandbox API key begins with npk_sandbox_. Never use a production key against this URL.

Simulating a full payment flow

1. Create and auto-verify an organization

POST /v1/organizations
# → status: active (instant in sandbox)

2. Create an account and wallet

POST /v1/accounts
POST /v1/wallets { "currency": "USD" }

3. Fund the wallet with test funds

POST /v1/wallets/{wallet_id}/fund
{
  "amount": 10000,
  "currency": "USD",
  "reference": "sandbox-test-001"
}

This endpoint only exists in sandbox. There is no equivalent in production.

4. Create a beneficiary and resolve a bank account

POST /v1/payments/resolve-bank-account
POST /v1/beneficiaries
POST /v1/beneficiaries/{id}/accounts

In the sandbox, use any of the test account numbers listed below.

5. Generate a quote and execute the transaction

POST /v1/pricing/quote
POST /v1/transactions

Sandbox test account numbers

Use these account numbers in the sandbox to simulate specific outcomes:

Simulating transaction outcomes

Append a test_scenario field to your transaction request to simulate specific outcomes:

POST /v1/transactions
{
  "wallet_id": "wlt_01HXXXXXXXXXXXXXXXXXX",
  "beneficiary_account_id": "bac_01HXXXXXXXXXXXXXXXXXX",
  "quote_id": "qte_01HXXXXXXXXXXXXXXXXXX",
  "reference": "test-scenario-001",
  "test_scenario": "transaction_failed"
}

📘

The test_scenario field is ignored in production.

Testing webhooks in the sandbox

Webhook delivery works the same in sandbox and production. To test:

1. Deploy a local endpoint using a tunnel tool like ngrok or Cloudflare Tunnel
2. Register the public URL in Settings → Webhooks
3. Execute a sandbox transaction to trigger events
4. Inspect the event payload and verify your signature check

You can also replay any event from the Webhooks → Event Log section of the dashboard.

Sandbox data resets

Sandbox data may be periodically reset. Do not build your integration in a way that depends on sandbox data persisting indefinitely. Always be prepared to re-create test organizations, accounts, and beneficiaries from scratch.

Sandbox limitations

• Exchange rates are simulated and do not reflect live market conditions
• Some corridors available in production may be simulated or absent in sandbox
• The wallet.funded webhook is triggered immediately after the test fund call — production may take hours or days
• Data is not guaranteed to persist across resets

Ready to go live?

When your sandbox testing is complete, follow the Production Checklist before switching to the production environment.