> For the complete documentation index, see [llms.txt](https://ivorypay.gitbook.io/ivorypay-on-off-ramp-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ivorypay.gitbook.io/ivorypay-on-off-ramp-documentation/api-reference-virtual-accounts/create.md).

# Create Virtual Account

Create a dedicated virtual bank account for receiving fiat deposits.

Creates a permanent virtual bank account that can receive fiat deposits. Deposits are automatically settled into crypto.

## Endpoint

```
POST /v1/virtual-accounts
```

## Authentication

**API key only (JWT not accepted).** This route uses the API-key guard exclusively.

| Header          | Value       |
| --------------- | ----------- |
| `Authorization` | `<api_key>` |

## Request body

| Field            | Type   | Required | Description                                                                                                                      |
| ---------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `email`          | string | Yes      | Customer's email address                                                                                                         |
| `identityType`   | string | Yes      | Identity verification type: `bvn`, `nin`, or `cac`                                                                               |
| `identityNumber` | string | Yes      | Identity number corresponding to the identity type                                                                               |
| `currency`       | string | Yes      | Fiat currency for the account. See [Supported Currencies](/ivorypay-on-off-ramp-documentation/resources/supported-currencies.md) |

## Example request

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://ramp-api.ivorypay.io/api/v1/virtual-accounts \
  -H "Authorization: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "merchant-user@example.com",
    "identityType": "bvn",
    "identityNumber": "22222222222",
    "currency": "NGN"
  }'
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const response = await fetch("https://ramp-api.ivorypay.io/api/v1/virtual-accounts", {
  method: "POST",
  headers: {
    "Authorization": "your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "merchant-user@example.com",
    identityType: "bvn",
    identityNumber: "22222222222",
    currency: "NGN",
  }),
});

const data = await response.json();
console.log(data);
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

response = requests.post(
    "https://ramp-api.ivorypay.io/api/v1/virtual-accounts",
    headers={
        "Authorization": "your_api_key",
        "Content-Type": "application/json",
    },
    json={
        "email": "merchant-user@example.com",
        "identityType": "bvn",
        "identityNumber": "22222222222",
        "currency": "NGN",
    },
)

print(response.json())
```

{% endtab %}

{% tab title="Go" %}

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]string{
		"email":          "merchant-user@example.com",
		"identityType":   "bvn",
		"identityNumber": "22222222222",
		"currency":       "NGN",
	})

	req, _ := http.NewRequest("POST", "https://ramp-api.ivorypay.io/api/v1/virtual-accounts", bytes.NewBuffer(body))
	req.Header.Set("Authorization", "your_api_key")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}
```

{% endtab %}
{% endtabs %}

## Example response

```json
{
  "success": true,
  "message": "Virtual account created",
  "data": {
    "id": "9b1a3e6f-7c2d-4e5a-8f12-1234567890ab",
    "businessId": "1c2b3a4d-5e6f-7081-9203-abcdef012345",
    "customerIdentifier": "8e8b6f5a-1234-4abc-9def-0fedcba98765",
    "email": "merchant-user@example.com",
    "customerName": "Amina Okafor",
    "identityType": "bvn",
    "identityNumber": "22222222222",
    "accountNumber": "9900123456",
    "accountName": "IvoryPay - Merchant User",
    "bankCode": "101",
    "bankName": "Providus Bank",
    "currency": "NGN",
    "processor": "providus",
    "status": "ACTIVE",
    "context": "LIVE",
    "createdAt": "2026-03-26T12:00:00.000Z",
    "updatedAt": "2026-03-26T12:00:00.000Z"
  }
}
```

## Response fields

| Field                | Type   | Description                                                  |
| -------------------- | ------ | ------------------------------------------------------------ |
| `id`                 | string | Virtual account UUID (local record)                          |
| `businessId`         | string | Owning business UUID                                         |
| `customerIdentifier` | string | Customer UUID linked to the VA                               |
| `email`              | string | Customer email supplied at creation                          |
| `customerName`       | string | Customer's full name (derived from `firstName` + `lastName`) |
| `identityType`       | string | `bvn`, `nin`, or `cac`                                       |
| `identityNumber`     | string | Identity number supplied at creation                         |
| `accountNumber`      | string | The virtual account number — share this with your user       |
| `accountName`        | string | Account name displayed to senders                            |
| `bankCode`           | string | Bank code of the virtual account provider                    |
| `bankName`           | string | Bank name                                                    |
| `currency`           | string | Fiat currency                                                |
| `processor`          | string | Underlying payment processor identifier                      |
| `status`             | string | `BasicStatus` enum — `ACTIVE` or `INACTIVE`                  |
| `context`            | string | Environment (`TEST` or `LIVE`)                               |
| `createdAt`          | string | ISO 8601 creation timestamp                                  |
| `updatedAt`          | string | ISO 8601 last-update timestamp                               |

## Identity types

| Type  | Description                                        | Example             |
| ----- | -------------------------------------------------- | ------------------- |
| `bvn` | Bank Verification Number (Nigeria)                 | 11-digit number     |
| `nin` | National Identification Number (Nigeria)           | 11-digit number     |
| `cac` | Corporate Affairs Commission (Nigeria, businesses) | Registration number |