Create Static Virtual Account

The Static Virtual Account endpoint allows merchants to create a permanent, reusable virtual account number for their customers to enable them to carry out transactions.

Requirements

To use this endpoint, ensure that:

Your API key is active and IP whitelisting is correctly configured.
The user has a valid Bank Verification Number (BVN).
You provide a unique reference value for each creation request to ensure idempotency.

Endpoint

POST /v1/virtual-account

Headers

Header	Type	Description	Required
`Content-Type`	String	Must be `application/json`.	✅ Yes
`x-api-key`	String	Your API key for authentication.	✅ Yes

Supported Currencies for Virtual Account

S/N	Country	Country Code	Currency
1	Nigeria 🇳🇬	NG	NGN
2	Malawi 🇲🇼	MW	MWK

💡

You can change the currency and country values in your request to match any of the supported options.

Sample Request

curl --location '({{baseURL}}/v1/virtual-account)' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY_HERE' \
--data-raw '{
    "currency": "NGN",
    "country": "NG",
    "firstName": "Jumoke",
    "lastName": "Dumebi",
    "email": "example@email.com",
    "phoneNumber": "+23481345XXXX",
    "bvn": "12345678901",
    "reference": "00006597506292872311029472",
    "accountName": "Jumoke Dumebi"
}'

Request Body

Field	Type	Description	Required
`currency`	String	Currency code (e.g., `NGN`).	✅ Yes
`country`	String	Country code (e.g., `NG`).	✅ Yes
`firstName`	String	The customer's first name.	✅ Yes
`lastName`	String	The customer's last name.	✅ Yes
`email`	String	The customer's email address.	✅ Yes
`phoneNumber`	String	The customer's phone number.	✅ Yes
`bvn`	String	The customer's 11-digit Bank Verification Number.	✅ Yes
`reference`	String	A unique reference for the request (max 30 characters).	✅ Yes
`accountName`	String	The desired name for the virtual account.	✅ Yes

Responses

A successful request returns a 200 OK status and the virtual account details.

Response (200 OK)

{
  "message": "virtual account created successfully",
  "status": "success",
  "data": {
    "id": "e21f7365-4fc9-4669-a9d9-xxxxxxxxxxxxx",
    "firstName": "Jumoke",
    "lastName": "Dumebi",
    "email": "example@email.com",
    "phoneNumber": "+234813456XXXXX",
    "bvn": "********",
    "reference": "00006597506292872311029472",
    "account": {
      "name": "Jumoke Dumebi",
      "bankName": "Mock BANK",
      "sortCode": null,
      "number": "881725XXXXX"
    },
    "status": "ACTIVE",
    "currency": "NGN",
    "country": "NG",
    "created": "2025-05-15T13:39:57.405491181"
  }
}

Response Body Breakdown

Virtual Account Data

This object contains the details of the successfully created static virtual account.

Field	Type	Description
`id`	String	Unique identifier for the virtual account resource.
`firstName`	String	First name of the virtual account holder.
`lastName`	String	Last name of the virtual account holder.
`email`	String	Email address associated with the account holder.
`phoneNumber`	String	Phone number of the account holder.
`bvn`	String	Bank Verification Number, masked for security.
`reference`	String	The unique reference passed during account creation.
`account.name`	String	The name on the generated virtual account.
`account.bankName`	String	The name of the bank providing the virtual account.
`account.sortCode`	String	The sort code of the bank (may be `null`).
`account.number`	String	The generated virtual account number.
`status`	String	The current status of the virtual account (e.g., `ACTIVE`).
`currency`	String	The currency code for the account.
`country`	String	ISO 3166-1 alpha-2 country code.
`created`	String	ISO 8601 timestamp of when the account was created.

Webhooks

While creating a static virtual account does not trigger a webhook, payments made to the account do.

virtualaccount.completed: Sent when a payment to the account is successful.
virtualaccount.failed: Sent when a payment to the account fails.

Refer to the main Webhooks documentation for detailed payload structures.

Important Notes:

The bvn is always masked in the response for security.

The reference must be unique per request to ensure idempotency.

The returned account.number can be used to receive payments through the listed bankName.

Always validate the status field before considering the account ready for use.

Virtual Account Dynamic Virtual Account