> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Test Virtual Accounts in Staging

> Simulate deposits into a virtual account and force each outcome in staging

In staging, two calls make a deposit arrive in a virtual account and end the way you choose. No bank transfer is sent. From there the deposit follows the real path: one order, the same checks, statuses, fields, and webhooks, and the stablecoins delivered on the staging chain of the account.

Both calls work in staging only. In production they answer `403 payments:virtual-account.staging-only` and change nothing.

## Prerequisites

* **Account**: a virtual account in a staging project, opened as in [Open a Virtual Account](https://docs.crossmint.com/virtual-accounts/guides/open-a-virtual-account.md).
* **API Key**: a staging server API key with the `virtual-accounts.create` scope. In staging, all scopes are included by default.

## Simulate a Deposit

```bash cURL theme={null}
curl --request POST \
    --url https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35/simulate-deposit \
    --header 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
        "amount": "200.00",
        "sender": {
            "name": "JANE DOE"
        },
        "rail": "sct-inst",
        "outcome": "completed"
    }'
```

```js Node.js theme={null}
const response = await fetch("https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35/simulate-deposit", {
    method: "POST",
    headers: {
        "X-API-KEY": "<YOUR_SERVER_API_KEY>",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        amount: "200.00",
        sender: {
            name: "JANE DOE",
        },
        rail: "sct-inst",
        outcome: "completed",
    }),
});

console.log(await response.json());
```

```python Python theme={null}
import requests

response = requests.post(
    "https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35/simulate-deposit",
    headers={"X-API-KEY": "<YOUR_SERVER_API_KEY>"},
    json={
        "amount": "200.00",
        "sender": {
            "name": "JANE DOE",
        },
        "rail": "sct-inst",
        "outcome": "completed",
    },
)

print(response.json())
```

The call answers `202` at once:

```json Response theme={null}
{
    "simulationId": "5d8a1f3c-7e2b-4c9a-b6d0-3f1e8a2c4b57",
    "orderId": "c41e8a7d-2f5b-4d9e-b3a6-8e1f0c7d5b92",
    "virtualAccountId": "7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35",
    "amount": "200.00",
    "currency": "eur",
    "outcome": "completed"
}
```

Follow the deposit through its webhooks, or read the order. The order carries the same `simulationId`, so concurrent tests can match each webhook to its simulation.

| Field | Required | Description |
| :- | :- | :- |
| `amount` | Yes | A decimal greater than 0, in the currency of the account |
| `outcome` | Yes | One of the outcomes in the next section |
| `sender.name` | No | Defaults to the account holder's verified name. The outcome, not the name, decides what happens |
| `rail` | No | One of the `rails.supported` of the account. Defaults to the first |

Every check runs on the real state of the account, and `outcome` makes one check give the chosen result. A deposit into an account that is not `active` goes back with `virtual-account-not-active`, whatever the outcome.

## Outcomes

Every outcome starts with `orders.quote.created`. The events column lists what follows.

| `outcome` | Order at the end | Events |
| :- | :- | :- |
| `completed` | Delivered | `orders.payment.succeeded` `orders.delivery.initiated` `orders.delivery.completed` |
| `third-party-sender` | Sent back, with `third-party-sender` | `orders.payment.failed` `orders.payment.refund_sent` |
| `below-minimum` | Sent back, with `below-minimum`, whatever the amount | `orders.payment.failed` `orders.payment.refund_sent` |
| `above-maximum` | Sent back, with `above-maximum`, whatever the amount | `orders.payment.failed` `orders.payment.refund_sent` |
| `travel-rule-rejected` | Sent back, with `deposit-not-accepted` | `orders.payment.failed` `orders.payment.refund_sent` |
| `wallet-not-allowed` | Sent back, with `deposit-not-accepted`. The account becomes `suspended` with `wallet-not-allowed` | `orders.payment.failed` `orders.payment.refund_sent` |
| `conversion-failed` | Sent back, with `conversion-failed` | `orders.payment.succeeded` `orders.payment.failed` `orders.payment.refund_sent` |
| `delivery-failed` | Sent back, with `delivery-failed` | `orders.payment.succeeded` `orders.delivery.failed` `orders.payment.failed` `orders.payment.refund_sent` |
| `return-failed` | Return did not go through, with `third-party-sender` | `orders.payment.failed` `orders.payment.refund_failed` |
| `in-review` | In review | `orders.payment.in_review` |

See [Deposit States](https://docs.crossmint.com/virtual-accounts/guides/track-deposits.md#deposit-states) for the `phase`, `payment.status`, and `payment.returnStatus` of each end state.

## End a Review

A deposit simulated with `in-review` stays in review until you end it. The call works on any deposit in review on the account.

```bash cURL theme={null}
curl --request POST \
    --url https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35/simulate-review-end \
    --header 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
        "orderId": "c41e8a7d-2f5b-4d9e-b3a6-8e1f0c7d5b92",
        "action": "clear"
    }'
```

```js Node.js theme={null}
const response = await fetch("https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35/simulate-review-end", {
    method: "POST",
    headers: {
        "X-API-KEY": "<YOUR_SERVER_API_KEY>",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        orderId: "c41e8a7d-2f5b-4d9e-b3a6-8e1f0c7d5b92",
        action: "clear",
    }),
});

console.log(await response.json());
```

```python Python theme={null}
import requests

response = requests.post(
    "https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35/simulate-review-end",
    headers={"X-API-KEY": "<YOUR_SERVER_API_KEY>"},
    json={
        "orderId": "c41e8a7d-2f5b-4d9e-b3a6-8e1f0c7d5b92",
        "action": "clear",
    },
)

print(response.json())
```

```json Response theme={null}
{
    "orderId": "c41e8a7d-2f5b-4d9e-b3a6-8e1f0c7d5b92",
    "virtualAccountId": "7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35",
    "action": "clear"
}
```

| `action` | Order at the end | Events |
| :- | :- | :- |
| `clear` | Delivered | `orders.payment.succeeded` `orders.delivery.initiated` `orders.delivery.completed` |
| `expire` | Sent back, with `hold-expired` | `orders.payment.failed` `orders.payment.refund_sent` |
| `return` | Sent back, with `deposit-not-accepted` | `orders.payment.failed` `orders.payment.refund_sent` |

## Errors

| Code | Status | When |
| :- | :- | :- |
| `payments:virtual-account.invalid-request` | 400 | Invalid JSON, a missing field, an `amount` that is not a positive decimal, an unknown `outcome` or `action`, or a `rail` the account does not support |
| `payments:virtual-account.staging-only` | 403 | Either call, in production |
| `payments:virtual-account.not-found` | 404 | No account with this ID in the project, or no deposit with this `orderId` on the account |
| `payments:virtual-account.not-in-review` | 409 | `simulate-review-end` on a deposit that is not in review |

## Next Steps

> [card] [Track Deposits](https://docs.crossmint.com/virtual-accounts/guides/track-deposits.md)
>
> The states, events, and fields of each deposit

> [card] [Handle Virtual Account Webhooks](https://docs.crossmint.com/virtual-accounts/guides/handle-webhooks.md)
>
> Every event and its payload
