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

# Open a Virtual Account

> Record the terms acceptance, link the wallet, create the account, and get the bank details to show

This guide opens an EUR virtual account for one of your users. At the end you have an `active` account with an IBAN in the user's name, and every transfer to that IBAN arrives in the user's wallet as EURC or USDC. Opening the account moves no money. Money moves only when the user sends a transfer.

## Prerequisites

* **Verified user**: the user has passed KYC. See [User Onboarding and KYC](https://docs.crossmint.com/onramp/introduction/user-onboarding.md). For a user who has not, the create call is refused. See [When the User Is Not Eligible](#when-the-user-is-not-eligible).
* **Wallet**: a wallet on Solana or Base that the user controls, or the user's own Crossmint wallet. An exchange deposit address is not supported.
* **API Key**: a server API key with the `virtual-accounts.create`, `virtual-accounts.read`, and `users.create` scopes. In staging, all scopes are included by default.

## Integration Steps

![Open a virtual account in four steps: record the terms of service and privacy policy acceptance with the current version, link the wallet, create the account with POST /virtual-accounts, which returns 201 active with the bank details, 201 pending, or 403 not-eligible with what is missing, such as KYC or the terms, and when pending wait for the virtual\_accounts.status.updated webhook and read the account until it is active with the bank details](https://mintcdn.com/crossmint/2jd6Af-5zuDMpBOn/images/virtual-accounts/open-a-virtual-account/open-a-virtual-account-flow.png?fit=max\&auto=format\&n=2jd6Af-5zuDMpBOn\&q=85\&s=51d0ef9273ecbde347eb87a10caa8143)

**1. Record the Terms and Privacy Policy**

Before the user gives any KYC data, the first screen of your app shows one checkbox that accepts the Crossmint terms of service and acknowledges the Crossmint privacy policy. After the user ticks it, record each document with the [Accept Legal Document API](https://docs.crossmint.com/api-reference/users/accept-legal-document.md), one call per document. Crossmint records the latest version of the document.

```bash cURL theme={null}
curl --request PUT \
    --url 'https://staging.crossmint.com/api/2025-06-09/users/<USER_LOCATOR>/legal-documents' \
    --header 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
        "type": "crossmint-terms-of-service",
        "region": "eu",
        "acceptedAt": "2026-11-04T10:15:00Z"
    }'
```

```javascript Node.js theme={null}
const response = await fetch("https://staging.crossmint.com/api/2025-06-09/users/<USER_LOCATOR>/legal-documents", {
    method: "PUT",
    headers: {
        "X-API-KEY": "<YOUR_SERVER_API_KEY>",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        type: "crossmint-terms-of-service",
        region: "eu",
        acceptedAt: "2026-11-04T10:15:00Z",
    }),
});

const acceptance = await response.json();
```

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

response = requests.put(
    "https://staging.crossmint.com/api/2025-06-09/users/<USER_LOCATOR>/legal-documents",
    headers={"X-API-KEY": "<YOUR_SERVER_API_KEY>"},
    json={
        "type": "crossmint-terms-of-service",
        "region": "eu",
        "acceptedAt": "2026-11-04T10:15:00Z",
    },
)

acceptance = response.json()
```

```json Response theme={null}
{
    "acceptedAt": "2026-11-04T10:15:00.000Z"
}
```

EUR accounts use `region` `eu`. For the privacy policy, send the same call with `type` `crossmint-privacy-policy` and no `region`.

**2. Link the Wallet**

Link the wallet that deposits go to, on Solana or Base, to the user with the [Link Wallet API](https://docs.crossmint.com/api-reference/users/link-wallet.md), and send the `proof` that verifies ownership. Skip this step for the user's own Crossmint wallet.

```bash cURL theme={null}
curl --request PUT \
    --url 'https://staging.crossmint.com/api/2025-06-09/users/<USER_LOCATOR>/linked-wallets/7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px' \
    --header 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
        "chain": "solana",
        "proof": "<SIGNATURE>"
    }'
```

```js Node.js theme={null}
const response = await fetch(
    "https://staging.crossmint.com/api/2025-06-09/users/<USER_LOCATOR>/linked-wallets/7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px",
    {
        method: "PUT",
        headers: {
            "X-API-KEY": "<YOUR_SERVER_API_KEY>",
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            chain: "solana",
            proof: "<SIGNATURE>",
        }),
    }
);

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

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

response = requests.put(
    "https://staging.crossmint.com/api/2025-06-09/users/<USER_LOCATOR>/linked-wallets/7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px",
    headers={"X-API-KEY": "<YOUR_SERVER_API_KEY>"},
    json={
        "chain": "solana",
        "proof": "<SIGNATURE>",
    },
)

print(response.json())
```

Without `proof`, the call answers with a `verificationChallenge`. The user signs it with the wallet, and you send the call again with the signature as `proof`. [Onramp to Non-Crossmint Wallets](https://docs.crossmint.com/onramp/guides/onramp-to-external-wallets.md) shows the signing flow.

**3. Create the Account**

Send the user, the currency, and the destination. The destination is the `walletAddress` of the wallet and the `tokenLocator` of the token deposits arrive in.

```bash cURL theme={null}
curl --request POST \
    --url https://staging.crossmint.com/api/2026-09-16/virtual-accounts \
    --header 'X-API-KEY: <YOUR_SERVER_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
        "userLocator": "email:jane@example.com",
        "label": "EUR deposits",
        "source": {
            "currency": "eur"
        },
        "destination": {
            "walletAddress": "7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px",
            "tokenLocator": "solana:eurc"
        }
    }'
```

```js Node.js theme={null}
const response = await fetch("https://staging.crossmint.com/api/2026-09-16/virtual-accounts", {
    method: "POST",
    headers: {
        "X-API-KEY": "<YOUR_SERVER_API_KEY>",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        userLocator: "email:jane@example.com",
        label: "EUR deposits",
        source: {
            currency: "eur",
        },
        destination: {
            walletAddress: "7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px",
            tokenLocator: "solana:eurc",
        },
    }),
});

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

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

response = requests.post(
    "https://staging.crossmint.com/api/2026-09-16/virtual-accounts",
    headers={"X-API-KEY": "<YOUR_SERVER_API_KEY>"},
    json={
        "userLocator": "email:jane@example.com",
        "label": "EUR deposits",
        "source": {
            "currency": "eur",
        },
        "destination": {
            "walletAddress": "7vQ3mXk2Lp9RtYw4NcB8sHd6JfGa1ZeUoTq5Vr3k9Px",
            "tokenLocator": "solana:eurc",
        },
    },
)

print(response.json())
```

A new account returns `201`:

```json Response theme={null}
{
    "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-16T10:00:00.000Z",
    "updatedAt": "2026-11-16T10:00:04.000Z"
}
```

The response has no `source` block. Read the currency and the issuing country from `depositInstructions.bankAccount`.

When the user has not passed KYC, the call answers `403 payments:virtual-account.not-eligible`. Complete the verification, then send the call again. See [When the User Is Not Eligible](#when-the-user-is-not-eligible).

Creating the account is safe to retry. A request with the same user, currency, and destination returns the open account with `200`, as it is, and never opens a second IBAN. A different `label` on the repeat is ignored.

**4. Wait for the Bank Details**

When the banking partner has not issued the bank details by the time the create call responds, the account returns `201` with `status` `pending` and `depositInstructions` set to `null`. A `pending` account is open: the same create call returns it with `200`. Crossmint keeps asking the banking partner for the bank details in the background, so you do not need to send the create call again.

Subscribe to the `virtual_accounts.status.updated` webhook, and read the account when it arrives:

```bash cURL theme={null}
curl --request GET \
    --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: "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/7c2e9a41-3b5d-4f8e-a6c1-2d9b0e4f7a35",
    headers={"X-API-KEY": "<YOUR_SERVER_API_KEY>"},
)

print(response.json())
```

The response is the account object of the create call. When `status` is `active`, show the bank details to the user. When it is `failed`, create the account again. See [Account Statuses](https://docs.crossmint.com/virtual-accounts/guides/manage-virtual-accounts.md#account-statuses) for every status and [Handle Account Status Changes](https://docs.crossmint.com/virtual-accounts/guides/handle-webhooks.md#handle-account-status-changes) for the event payload.

## Request Fields

| Field | Required | Description |
| :- | :- | :- |
| `userLocator` | Yes | An `email:`, `userId:`, `phoneNumber:`, `twitter:`, or `x:` locator of the user. Returned as sent |
| `label` | No | A name for the account. Returned as sent |
| `source.currency` | Yes | The lowercase ISO 4217 code of a market's currency, such as `eur` |
| `destination.walletAddress` | Yes | An address valid on the chain of `tokenLocator`. Returned as sent |
| `destination.tokenLocator` | Yes | The chain and token deposits arrive in, as `chain:token`. For EUR: `solana:eurc`, `base:eurc`, `solana:usdc`, or `base:usdc` |

Opening an account never creates a wallet. The request takes no amount, payment method, or line items.

## When the User Is Not Eligible

When the user has not passed KYC, or the banking partner cannot open an account for the user, the create call answers `403 payments:virtual-account.not-eligible` and opens nothing:

```json Response theme={null}
{
    "error": true,
    "message": "The customer has not passed full onramp identity verification.",
    "code": "payments:virtual-account.not-eligible"
}
```

The `message` says which case applies.

| `message` | What it means | What to do |
| :- | :- | :- |
| `The customer has not passed full onramp identity verification.` | The user has not passed KYC, or the `userLocator` matches no user of your project | Complete the user's KYC, then send the same create call again. See [User Onboarding and KYC](https://docs.crossmint.com/onramp/introduction/user-onboarding.md) |
| `The bank account provider cannot open an account for this customer yet.` | The banking partner did not accept the user | The user cannot open an account for now |

## Errors

Every refusal has the body `error`, `message`, and `code`. Some also carry `parameters`.

### Fix the Request

| Code | Status | When | What to do |
| :- | :- | :- | :- |
| `payments:virtual-account.invalid-request` | 400 | Invalid JSON, or a required field is missing | Send valid JSON with every required field |
| `payments:virtual-account.unsupported-currency` | 400 | `source.currency` has no market | Use a supported currency, such as `eur` |
| `payments:virtual-account.unsupported-destination` | 400 | The chain or token is not a destination of the market | Use a chain and token of the market. See [Request Fields](#request-fields) |
| `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 |
| `ADDON_REQUIRED` | 400 | Virtual accounts are not enabled for the project | [Contact Crossmint](https://www.crossmint.com/contact/sales) to enable them |

### User and Wallet Checks

| Code | Status | When | What to do |
| :- | :- | :- | :- |
| `payments:virtual-account.not-eligible` | 403 | The user has not passed KYC, or the banking partner did not accept the user | Read `message`. See [When the User Is Not Eligible](#when-the-user-is-not-eligible) |
| `payments:virtual-account.wallet-ownership-not-verified` | 403 | The wallet is not linked to the user with ownership verified | Link the wallet, then send the create call 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 wallet did not pass screening | Use a different wallet |

### Conflicts and Retries

| Code | Status | When | What to do |
| :- | :- | :- | :- |
| `payments:virtual-account.limit-reached` | 409 | The user already has an open account in the currency. `parameters.virtualAccountId` names it when it belongs to your project | Use the existing account |
| `payments:virtual-account.wallet-screening-unavailable` | 503 | The wallet could not be screened | Send the same request again |

## Next Steps

> [card] [Manage Virtual Accounts](https://docs.crossmint.com/virtual-accounts/guides/manage-virtual-accounts.md)
>
> List accounts, change the wallet or token, and close an account

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