# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.klasha.com/bank-account-collection/virtual-account-creation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.