Sandbox
What the Gravv sandbox can and cannot produce for each product today, and which recipe tests a deposit, a card, a payout, a verification or a USDC send.
Sandbox runs the same API as live, with test money. These recipes show, product by product, what you can and cannot produce in sandbox today. Where sandbox cannot produce a result, test those screens with recorded webhook payloads instead.
A money example. You simulate a 50,000 NGN deposit into a sandbox NGN account. The real deposit pipeline runs. Gravv credits the account, writes a transaction row, and sends transfer.inflow.completed to your sandbox webhook URL. Then you pay 20,000 NGN to a Nigerian bank payee, and the payout completes in about 3 minutes.
To run these flows without writing code first, use the Gravv CLI. gravv try wallet makes a customer and a wallet and pays 20 test USDC into it. With --curl, it prints each call as curl.
How sandbox differs from live
| Sandbox | Live | |
|---|---|---|
| How you choose it | A key that starts with grvSec_sandbox_ |
Any other key |
| Host | https://api.gravv.xyz |
The same |
| Data | Separate. A sandbox id returns "not found" with a live key, and a live id returns "not found" with a sandbox key | Separate from sandbox |
| Webhook URL and secret | Their own, set in the Dashboard in Sandbox mode | Their own |
| Request rules | The same validation, permissions, Idempotency-Key rules and rate limits |
The same |
| Release timing | Changes reach sandbox first, so sandbox can be a few days ahead of live | Changes reach live after sandbox |
What you can produce today
| Product | Status in sandbox | Recipe |
|---|---|---|
| A deposit into an NGN account | Available | Make a test deposit land |
| A deposit into a USD, EUR or GBP account | Not yet available. Those accounts do not open in sandbox today | Make a test deposit land |
| A returned or failed deposit | Not yet available | No recipe |
| Issuing a virtual card, reading it, freezing it, changing its limit | Available, for an already verified cardholder | Test a card in sandbox |
| Card purchases and declines | Not yet available | Test a card in sandbox |
| Withdrawing from a new card, physical cards | Not yet available | Test a card in sandbox |
| A naira bank payout, some mobile-wallet payouts | Available | Run a test payout |
| A payout that fails, returns or pauses on purpose | Not yet available | Run a test payout |
| A customer's verification completing | Not yet available for new customers | Verify a customer in sandbox |
| A same-network USDC send between wallets | Available, from a wallet that holds test dollars | Send USDC in sandbox |
| A cross-network USDC send, a failed crypto send | Not yet available | Send USDC in sandbox |
| An FX quote or order | Not yet available. Sandbox has no OTC rates | Foreign exchange |
| Collections from a payer | Not yet available in these recipes | No recipe |
| Reading limits | Available. The sandbox policy only records breaches, so nothing pauses | Check what a sender can still send |
| Webhooks: storing, retrying, history, resend | Available, as in live | Trace a transfer and resend a webhook |
Rules every recipe relies on
- Every POST needs its own new
Idempotency-Key, as in live. Gravv replays a 4xx response for 24 hours under its key, so use a new key after you fix a request. - The deposit simulator,
POST /v2/accounts/simulate/deposit, is the only sandbox-only route. A live key gets 403 from it, so it can never move real money. - Never add
_simulate_web3to a transfer. If you do, the transfer never completes. - Sandbox wallets are test-network wallets. On EVM networks the
USDCbalance is the sandbox test dollar, a test token that stands for US dollars. USDC from a public faucet does not show in that balance. - Keep uploaded documents under 500 KB. From about 600 KB, sandbox returns 413.
- Never use a sandbox result as evidence for a live customer or payout.
For the known sandbox issues, see Environments.