> For the complete documentation index, see [llms.txt](https://developers.klasha.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.klasha.com/bank-account-collection/virtual-account-creation.md).

# Virtual Account Creation

## Summary

Our Virtual Accounts service lets you create Nigerian account number for your customers which allow your customers to receive payment from their customers.

When you create a VA for a customer, all bank transfers to that account will automatically be recorded as transactions from that customer and displayed on your dashboard.

### Coverage

| Country | currency |
| ------- | -------- |
| Nigeria | NGN      |
| Ghana   | GHS      |

#### Integration steps

You can generate a VA and start receiving money in 3 easy steps:

{% stepper %}
{% step %}
Prepare and encrypt the payload (fields include: first name, last name, currency and email)
{% endstep %}

{% step %}
Initiate VA creation
{% endstep %}

{% step %}
Get instant response
{% endstep %}
{% endstepper %}

***

## Create a virtual account

> <mark style="color:yellow;">**POST**</mark>  - <mark style="color:$primary;">`{{env_url}}/wallet/virtual/v3/business/create/account`</mark>

Encrypt the plain request using the encryption algorithm specified [here](https://developers.klasha.com/accepting-payments/payments-api#java). Then send the encrypted data as the request body as shown below.&#x20;

#### Headers

{% hint style="info" %}
You are required to set the *x-auth-token* and *Authorization* values in the request headers.
{% endhint %}

| Key                                             | Value                                                                                                                        |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| x-auth-token<mark style="color:red;">\*</mark>  | Your merchant public key                                                                                                     |
| Authorization<mark style="color:red;">\*</mark> | Bearer \<token> ([generated here](https://developers.klasha.com/~/revisions/6QchOxP4kiu4Tx13lWtV/overview/token-generation)) |

#### Request to be encrypted (plain)

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

```json
{
   "firstName": "John",
   "lastName": "Doe",
   "currency": "NGN",
   "email": "test@klasha.com"
}
```

{% endtab %}

{% tab title="Business" %}

```json
{
   "currency": "NGN",
   "email": "test@klasha.com"
}
```

{% endtab %}
{% endtabs %}

| Name                                       | Type   | Description                                                          |
| ------------------------------------------ | ------ | -------------------------------------------------------------------- |
| currency<mark style="color:red;">\*</mark> | String | must be one of the supported currencies in the [coverage](#coverage) |
| email<mark style="color:red;">\*</mark>    | String | email to be linked to the VA                                         |

#### **Final Request Body (encrypted)**

```json
{
   "message": "encrypted-message"
}
```

{% hint style="info" %}
The encrypted payload must be used with the create virtual account endpoint as seen above.
{% endhint %}

#### Response

When you create a Virtual Account (VA), please allow a few seconds for processing. The `accountName` will be the `first` and `last name` for a personal account, or the business name for a corporate account. Below are sample responses;

{% tabs %}
{% tab title="200: OK (NGN) " %}

```json
{
    "id": 1,
    "accountNumber": "8571529225",
    "bankName": "WEMA BANK",
    "orderRef": "HsKRPDlemp7XBKvgO1HE",
    "txRef": "klasha-virtual-account-banktransfer-Business owner-999",
    "flwRef": "URF_vK8el9541NEy0j66imFD",
    "currency": "NGN",
    "businessId": 999,
    "bankCode": "120937",
    "enabled": true,
    "accountName": "Business owner",
    "email": "test@business.com",
    "createdAt": "2025-09-29 13:32:59",
    "updatedAt": "2025-09-29 13:32:59"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```json
{
    "message": "There is no identity available for this bvn.",
    "error": "Operation not allowed"
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```json
{
    "message": "Bvn name mismatch.",
    "error": "Operation not allowed"
}
```

{% endtab %}
{% endtabs %}

## Requery VA

> <mark style="color:green;">**GET**</mark> - <mark style="color:$primary;">`{{env_url}}/wallet/virtual/v2/account/{{email}}`</mark>

In case of network downtime or failures during VA creation, the virtual account can be re-queried with the user’s email. This can be fetched using the email specified during the initial VA creation.

#### Headers

| Key                                                 | Value           |
| --------------------------------------------------- | --------------- |
| Authorization<mark style="color:$danger;">\*</mark> | Bearer \<token> |

{% tabs %}
{% tab title="200: OK " %}

```json
[
    {
        "accountNumber": "8571529225",
        "bankName": "WEMA BANK",
        "orderRef": "HsKRPDlemp7XBKvgO1HE",
        "txRef": "klasha-virtual-account-banktransfer-Business owner-999",
        "flwRef": "URF_vK8el9541NEy0j66imFD",
        "businessId": 999,
        "enabled": true,
        "accountName": "Business Owner",
        "email": "test@business.com",
        "createdAt": "2023-07-04 17:02:59",
        "updatedAt": "2023-07-04 17:02:59"
    }
]
```

{% endtab %}
{% endtabs %}

## VA Transactions notification

When payments are received in the VA, we would send a webhook with the details of the transaction to your callback URL. (see webhook details [here](https://developers.klasha.com/~/revisions/H5FGFkMO860BT4FVTiB5/misc/webhook))

## Polling transaction status

> <mark style="color:yellow;">**POST**</mark> - <mark style="color:$primary;">`{{env_url}}/nucleus/tnx/collection/status`</mark>

To know the status of a transaction, you can fetch the transaction using the Transaction Status API on the Postman collection. Make use of the session id received from the bank. See an example below:

#### Request Body

| Name                                      | Type   | Description                                                      |
| ----------------------------------------- | ------ | ---------------------------------------------------------------- |
| gateRef<mark style="color:red;">\*</mark> | String | session id received from the bank (e.g. 10043509483902847574822) |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "destinationCurrency": "NGN",
    "sourceAmount": 2500.000000,
    "sourceCurrency": "NGN",
    "status": "successful",
    "destinationAmount": 2500.000000,
    "customer": {
        "id": 53603,
        "name": "Last Name",
        "email": "test@steph.com",
        "phone": null,
        "createdAt": "2023-07-04 20:11:05",
        "updatedAt": "2023-07-04 20:11:05"
    }
}
```

{% endtab %}
{% endtabs %}