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:

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.

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

Headers

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

Request to be encrypted (plain)

NGN (Individual)

{
   "firstName": "John",
   "lastName": "Doe",
   "currency": "NGN",
   "email": "[email protected]"
}

NGN (Business)

Name	Type	Description
firstName*	String	account first name
lastName*	String	account last name
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"
}

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;

200: OK (NGN)

{
    "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": "[email protected]",
    "profileHash": null,
    "blockReason": null,
    "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": "8573777620",
        "bankName": "WEMA BANK",
        "orderRef": "HsKRPDlemp7XBKvgO1HE",
        "txRef": "klasha-fund-wallet-banktransfer-steph-AJDcN6app",
        "flwRef": "URF_1Qw8TF2ZN1KkIdsqyHYI",
        "businessId": 5,
        "enabled": true,
        "accountName": "Forrest Green",
        "email": "[email protected]",
        "createdAt": "2023-07-04 17:02:59",
        "updatedAt": "2023-07-04 17:02:59"
    }
]

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)

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": "[email protected]",
        "phone": null,
        "createdAt": "2023-07-04 20:11:05",
        "updatedAt": "2023-07-04 20:11:05"
    }
}