# Virtual Account Creation

## Summary

Create Virtual Accounts (VA) on demand, receive funds from customers via these accounts and get notification on its usage.

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.

### Coverage

| Country | currency |
| ------- | -------- |
| Nigeria | NGN      |

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

**NB**: You are required to set the *x-auth-token* and *Authorization* in the request headers.

#### Headers

| 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 |
| email<mark style="color:red;">\*</mark>    | String | email to be linked to the VA                            |

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

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

**NB**: The encrypted payload must be used with the create virtual account endpoint as seen above.

#### 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": 6451,
    "walletId": null,
    "accountNumber": "8571529225",
    "bankName": "WEMA BANK",
    "orderRef": "7uIyXachQYC9hcTpgWOZ",
    "txRef": "klasha-virtual-account-banktransfer-Business owner-133",
    "flwRef": "URF_vK8el9541NEy0j66imFD",
    "currency": "NGN",
    "userId": null,
    "businessId": 1133,
    "bankCode": null,
    "enabled": true,
    "accountName": "Business owner",
    "email": "test@klasha.com",
    "profileHash": null,
    "blockReason": null,
    "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 | Bearer \<token> |

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

```json
[
    {
        "accountNumber": "8573777620",
        "bankName": "WEMA BANK",
        "orderRef": "HsKRPDlemp7XBKvgO1HE",
        "txRef": "klasha-fund-wallet-banktransfer-steph-AJDcN6app",
        "flwRef": "URF_1Qw8TF2ZN1KkIdsqyHYI",
        "businessId": 5,
        "enabled": true,
        "accountName": "Forrest Green",
        "email": "test@klasha.com",
        "createdAt": "2023-07-04 17:02:59",
        "updatedAt": "2023-07-04 17:02:59"
    }
]
```

{% endtab %}
{% endtabs %}

## VA Transactions notification

When payments are received from your users, 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 %}