Virtual Account Creation

Summary

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

Dedicated Virtual Accounts (DVAs) is a service that lets you create nigerian virtual accounts for your customers. These accounts allow your customers to receive payment from their customers.

When you create a Dedicated Virtual Account (DVA) 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 some sample responses you can expect.

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 here>

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"
    }
]

Transaction Webhook

When payments are received from your users, we would send a webhook with the details of the transaction to your callback URL.

{
  "data": {
    "createdAt": "2023-07-14T19:28:18.585",
    "narration": "Bank Transfer",
    "destinationCurrency": "NGN",
    "sourceAmount": 2000,
    "sourceCurrency": "NGN",
    "virtualAccount":"0987654321",
    "tnxRef": "reference_322123243",
    "status": "successful",
    "destinationAmount": 2000,
    "originatorAccountName":"Stephen Oj",
    "bankName": "Access Bank",
    "originatorAccountNumber":"1234456211",
    "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"
    }
  },
  "event": "charge.completed"
}

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"
    }
}