> ## 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.

# Manage Virtual Accounts

> List a project's virtual accounts, change the wallet or token of an account, close it, and follow its status

This guide covers what you do with a virtual account after it opens: list accounts, change where deposits go, close an account, and read or react to its status. Every call returns the account object of [Open a Virtual Account](https://docs.crossmint.com/virtual-accounts/guides/open-a-virtual-account.md).

## Prerequisites

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

## List Accounts

List the accounts of your project. Add `userLocator` to list the accounts of one user.

```bash cURL theme={null}
curl --request GET \
    --url 'https://staging.crossmint.com/api/2026-09-16/virtual-accounts?currency=eur&limit=1' \
    --header 'X-API-KEY: <YOUR_SERVER_API_KEY>'
```

```js Node.js theme={null}
const response = await fetch("https://staging.crossmint.com/api/2026-09-16/virtual-accounts?currency=eur&limit=1", {
    method: "GET",
    headers: {
        "X-API-KEY": "<YOUR_SERVER_API_KEY>",
    },
});

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

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

response = requests.get(
    "https://staging.crossmint.com/api/2026-09-16/virtual-accounts?currency=eur&limit=1",
    headers={"X-API-KEY": "<YOUR_SERVER_API_KEY>"},
)

print(response.json())
```

```json Response theme={null}
{
    "data": [
        {
            "virtualAccountId": "7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35",
            "userLocator": "email:jane@example.com",
            "label": "EUR deposits",
            "status": "active",
            "statusReason": null,
            "depositInstructions": {
                "bankAccount": {
                    "iban": "MT00EXAMPLE0000000000000000000",
                    "bic": "EXAMPLEXXX",
                    "accountHolder": {
                        "name": "Jane Doe"
                    },
                    "entityType": "individual",
                    "institutionName": "OpenPayd Financial Services Malta Limited",
                    "institutionAddress": "Level 3, 137 Spinola Road, St Julian's STJ 3011, Malta",
                    "currency": "eur",
                    "country": "MT",
                    "rails": {
                        "supported": ["sct", "sct-inst"]
                    }
                }
            },
            "destination": {
                "walletAddress": "7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px",
                "tokenLocator": "solana:eurc"
            },
            "createdAt": "2026-11-20T10:00:00.000Z",
            "updatedAt": "2026-11-20T10:00:04.000Z"
        }
    ],
    "nextCursor": "Y3Vyc29yLWV4YW1wbGU"
}
```

`nextCursor` and `previousCursor` appear only when a page exists in that direction. Send the same filters when you follow a cursor.

| Query parameter | Default | Description |
| :- | :- | :- |
| `userLocator` | Every user | The locator of one user. A locator with no user returns an empty `data` |
| `currency` | Every currency | One or several currency codes, comma-separated, such as `eur` |
| `tokenLocator` | Every token | One or several token locators, comma-separated, such as `solana:eurc,solana:usdc` |
| `status` | Every status except `closed` and `failed` | One or several statuses, comma-separated |
| `limit` | `30` | From 1 to 100 |
| `sort` | `desc` | `desc` or `asc`, by creation date |
| `cursor` | None | A `nextCursor` or `previousCursor` from an earlier page |

Each filter takes up to 20 values and matches any of them. An account is listed when it matches every filter sent. A malformed value, more than 20 values, a `limit` outside 1 to 100, or an unknown cursor answers `400 payments:virtual-account.invalid-request`.

## Change the Wallet or Token

Only `destination` and `label` can change. Send `destination` whole, with the same rules as on create. For an EUR account, the token can switch between `eurc` and `usdc`, alone or together with the wallet and chain.

```bash cURL theme={null}
curl --request PATCH \
    --url https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35 \
    --header 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
        "label": "EUR deposits on Solana",
        "destination": {
            "walletAddress": "9xR2kLm7Pq4WtYz8NcB3sHd6JfGa1ZeUoTq5Vr2m4Lt",
            "tokenLocator": "solana:eurc"
        }
    }'
```

```js Node.js theme={null}
const response = await fetch("https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35", {
    method: "PATCH",
    headers: {
        "X-API-KEY": "<YOUR_SERVER_API_KEY>",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        label: "EUR deposits on Solana",
        destination: {
            walletAddress: "9xR2kLm7Pq4WtYz8NcB3sHd6JfGa1ZeUoTq5Vr2m4Lt",
            tokenLocator: "solana:eurc",
        },
    }),
});

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

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

response = requests.patch(
    "https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35",
    headers={"X-API-KEY": "<YOUR_SERVER_API_KEY>"},
    json={
        "label": "EUR deposits on Solana",
        "destination": {
            "walletAddress": "9xR2kLm7Pq4WtYz8NcB3sHd6JfGa1ZeUoTq5Vr2m4Lt",
            "tokenLocator": "solana:eurc",
        },
    },
)

print(response.json())
```

The response is the account with its new `destination`, `label`, and `updatedAt`. The bank details, the account holder, the `status`, and the `statusReason` stay as they are.

A change applies to deposits recorded after it. A deposit recorded before the change keeps the wallet, the token, and the rate on its order. When two changes reach the same account, the last to arrive wins, so read the account to confirm its destination.

A change to a different wallet address follows the wallet rules of create: the user proves they control the wallet first, and the wallet is screened. A change that keeps the address, such as a new label or token, needs no new proof.

**Fix the request**

| Code | Status | When | What to do |
| :- | :- | :- | :- |
| `payments:virtual-account.invalid-request` | 400 | Invalid JSON, or neither `destination` nor `label` was sent | Send valid JSON with `destination`, `label`, or both |
| `payments:virtual-account.field-not-editable` | 400 | A field other than `destination` or `label` was sent | Send only `destination` and `label` |
| `payments:virtual-account.invalid-destination` | 400 | `destination.walletAddress` is not a valid address on the chain of `tokenLocator` | Send an address that is valid on that chain |
| `payments:virtual-account.unsupported-destination` | 400 | The market does not deliver the token on the chain sent | Use a chain and token of the market. See [Request Fields](https://docs.crossmint.com/virtual-accounts/guides/open-a-virtual-account.md#request-fields) |
| `payments:virtual-account.not-found` | 404 | No account with this ID in the project | Check the account ID |

**Wallet checks**

| Code | Status | When | What to do |
| :- | :- | :- | :- |
| `payments:virtual-account.wallet-ownership-not-verified` | 403 | The user has not proved they control the new wallet | Link the wallet, then send the change again |
| `payments:virtual-account.wallet-not-owned` | 403 | The wallet is a Crossmint wallet of another user | Use a wallet of this user |
| `payments:virtual-account.wallet-not-allowed` | 403 | The new wallet did not pass screening | Use a different wallet |

**Conflicts**

| Code | Status | When | What to do |
| :- | :- | :- | :- |
| `payments:virtual-account.not-active` | 409 | The account is `closed` or `failed` | Open a new account |
| `payments:virtual-account.exists` | 409 | Another open account of the same user and currency already has this wallet, chain, and token | Use the other account, or choose a different destination |

## Close an Account

Closing is final: nothing reopens a closed account.

```bash cURL theme={null}
curl --request DELETE \
    --url https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35 \
    --header 'X-API-KEY: <YOUR_SERVER_API_KEY>'
```

```js Node.js theme={null}
const response = await fetch("https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35", {
    method: "DELETE",
    headers: {
        "X-API-KEY": "<YOUR_SERVER_API_KEY>",
    },
});

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

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

response = requests.delete(
    "https://staging.crossmint.com/api/2026-09-16/virtual-accounts/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35",
    headers={"X-API-KEY": "<YOUR_SERVER_API_KEY>"},
)

print(response.json())
```

The call closes an account that is `pending`, `active`, or `suspended`, and returns it with `status` `closed` and `statusReason` `client-closed`. On an account that is already `closed` or `failed`, it returns `200` with the account unchanged.

* A deposit recorded before the close still finishes: it is delivered, or it goes back to the sender if it fails a check.
* A deposit that arrives after the close is not delivered and goes back to the sender.
* The bank details stay readable on the closed account.
* After a close, the same create call opens a new account with new bank details.

## Account Statuses

Every account has a `status` and a `statusReason`. Treat both sets as extensible. See [Account Statuses](https://docs.crossmint.com/virtual-accounts/concepts/how-it-works.md#account-statuses) for what each status means and how an account moves between them.

`statusReason` is `null` unless the status is one of the three in the table.

| Status | `statusReason` | Meaning |
| :- | :- | :- |
| `suspended` | `compliance-suspended` | Crossmint Compliance suspended the account. Deposits go back until Compliance lifts the suspension |
| `suspended` | `wallet-not-allowed` | The destination wallet did not pass screening. Change the wallet to lift it |
| `suspended` | `provider-suspended` | The banking partner suspended the bank details |
| `failed` | `provider-rejected` | The banking partner refused the account |
| `failed` | `provider-timeout` | The bank details were not issued in time. Create the account again |
| `closed` | `client-closed` | You closed the account |
| `closed` | `provider-closed` | The banking partner closed the bank details |

When several causes suspend an account, `statusReason` shows the one listed first in the table. Once issued, the bank details stay readable in every status and are never given to another user.

## Follow Status Changes

Crossmint sends the `virtual_accounts.status.updated` webhook each time the `status` or the `statusReason` of an account changes. Read the account when it arrives. See [Handle Account Status Changes](https://docs.crossmint.com/virtual-accounts/guides/handle-webhooks.md#handle-account-status-changes) for the payload.

## Next Steps

> [card] [Track Deposits](https://docs.crossmint.com/virtual-accounts/guides/track-deposits.md)
>
> Follow each bank transfer as an order

> [card] [Test in Staging](https://docs.crossmint.com/virtual-accounts/guides/test-in-staging.md)
>
> Simulate deposits and force each outcome
