Virtual Account Creation

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

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:

1

Prepare and encrypt the payload (fields include: first name, last name, currency and email)

2

Initiate VA creation

3

Get instant response

---

Create a virtual account

POST - {{env_url}}/wallet/virtual/v3/business/create/account

Encrypt the plain request using the encryption algorithm specified here. Then send the encrypted data as the request body as shown below.

Headers

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

Key	Value
x-auth-token*	Your merchant public key
Authorization*	Bearer <token> (generated here)

Request to be encrypted (plain)

Individual

{
   "firstName": "John",
   "lastName": "Doe",
   "currency": "NGN",
   "email": "[e-mail]"
}

Business

Name	Type	Description
currency*	String	must be one of the supported currencies in the coverage
email*	String	email to be linked to the VA

Final Request Body (encrypted)

{
   "message": "encrypted-message"
}

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;

200: OK (NGN)

{
    "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": "[e-mail]",
    "createdAt": "2025-09-29 13:32:59",
    "updatedAt": "2025-09-29 13:32:59"
}

400: Bad Request

400: Bad Request

Requery VA

GET - {{env_url}}/wallet/virtual/v2/account/{{email}}

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>

200: OK

[
    {
        "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": "[e-mail]",
        "createdAt": "2023-07-04 17:02:59",
        "updatedAt": "2023-07-04 17:02:59"
    }
]

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)

Polling transaction status

POST - {{env_url}}/nucleus/tnx/collection/status

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*	String	session id received from the bank (e.g. 10043509483902847574822)

200: OK

{
    "destinationCurrency": "NGN",
    "sourceAmount": 2500.000000,
    "sourceCurrency": "NGN",
    "status": "successful",
    "destinationAmount": 2500.000000,
    "customer": {
        "id": 53603,
        "name": "Last Name",
        "email": "[e-mail]",
        "phone": null,
        "createdAt": "2023-07-04 20:11:05",
        "updatedAt": "2023-07-04 20:11:05"
    }
}