# Sandbox for the Accounts API

Build and test against simulated accounts with a test key, covering opening a test account, making money arrive, holding and returning an arrival, the events it sends, what works like live, and the sandbox's limits.

Source: https://vezmo.com/docs/developers/accounts-api-sandbox


## Overview

The sandbox is a simulation beside your real accounts. A **test key** reads it: you open test accounts, make money
arrive from a payer you name, and read the balances, transactions, statements and events it makes, exactly as you
would read your real ones. No real money moves.

The sandbox needs the Accounts API on for your business and a test key with Accounts API permissions. See
[Keys and permissions for the Accounts API](/docs/developers/accounts-api-keys).

## The key picks the sandbox

- Test and live use the same base URL. A test key (`vzm_test_…`) always reads the sandbox; a live key always reads your
  real accounts. There is no switch or header.
- The simulation endpoints work only with a test key. A live key gets `404`.
- Sandbox events carry `livemode: false` and go only to webhook endpoints set to **Test**.

## Try it

(Diagram: Open a test account with POST /simulations/accounts. Make money arrive with POST /simulations/incoming. It is credited, booked and sent as events. Then read balances, transactions, statements and events with the same test key.)

1. **Get a token with your test key**
Swap the test key for an access token with `POST /oauth/token`, as for live.

2. **Open a test account**
`POST /simulations/accounts` with a `currency`: `USD`, `EUR`, `GBP` or `AED`. You get the account as `GET /accounts`
shows it. There is one test account per currency: asking again gives you the same one.

3. **Make money arrive**
`POST /simulations/incoming` with the `accountId` and the `amount` in the smallest unit. You can also send the
`payerName`, the `payerCountry` and the `rail` (`ach`, `wire`, `swift`, `sepa` or `local_transfer`).

4. **Read what it made**
`GET /balances`, `GET /transactions`, `GET /events` and `GET /statements` now show it. A test webhook endpoint that
listens to Accounts events gets them too.

## Choose what happens to the money

Send `outcome` with the arrival to see each path your integration must handle:

| `outcome` | What happens | Events sent |
| --- | --- | --- |
| `credited` (the default) | The money reaches the balance and a line is booked. | `incoming.received`, then `incoming.credited` and `transaction.posted` |
| `held` | It waits, as when we review an arrival. | `incoming.received`, then `incoming.held` |
| `returned` | It never reaches the balance. | `incoming.received`, then `incoming.returned` |

A held arrival moves on with `POST /simulations/incoming/{id}/advance` and `to` set to `credited` or `returned`. It
sends that event. An arrival that isn't held, or was already moved on, answers `409`.

## What is different from live

- Sandbox money has no fee.
- Statements come as JSON or CSV only. Sandbox statements aren't made as PDFs, so a made-up balance never looks like a
  real statement.
- A test account has no bank name.
- The simulation endpoints allow 5 requests a second and 60 a minute per key on each endpoint, and 500 simulated
  arrivals a day per business.
- A sandbox nobody uses for 90 days is deleted, with its test accounts and simulated money.
- A test key whose secret was found in public code can no longer run simulations. It still reads test data until you
  revoke it: make a new test key.
- Test webhook endpoints get 5 seconds per attempt and 3 attempts.
- Everything else behaves as live: permissions, versions, paging, errors and the statement limits.

Requests and answers with examples are in the
[sandbox section of the Accounts API reference](https://user.vezmo.com/docs/v1/accounts-api/sandbox).

## Related

- [Accounts API](/docs/developers/accounts-api)
- [Webhooks for Accounts](/docs/developers/accounts-api-webhooks)
- [Test mode for developers](/docs/developers/test-mode)

Vezmo is a financial technology company, not a bank. Banking, stablecoin and card services are provided by regulated
partners.
