Virtual Account API

The Virtual Account API allows you to create a virtual bank account for a user. This account can be used to receive payments.

Endpoint

POST https://{{baseURL}}/v1/virtual-account

Headers

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

Request Body

Field	Type	Description	Required
`currency`	String	Currency code (e.g., `NGN`)	✅ Yes
`country`	String	Country code (e.g., `NG`)	✅ Yes
`firstName`	String	User's first name	✅ Yes
`lastName`	String	User's last name	✅ Yes
`email`	String	User's email address	✅ Yes
`phoneNumber`	String	User's phone number	✅ Yes
`bvn`	String	Bank Verification Number	✅ Yes
`reference`	String	Unique reference for the request	✅ Yes
`narration`	String	Transaction description	✅ Yes

Sample `cURL` Request

curl --location 'https://{{baseURL}}/v1/virtual-account' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API_KEY_SANDBOX:YOUR_API_KEY' \
--data-raw '{
    "currency": "NGN",
    "country": "NG",
    "firstName": "Lunce",
    "lastName": "Harry",
    "email": "harry@malinator.com",
    "phoneNumber": "+2348123456787",
    "bvn": "90223465239",
    "reference": "REF_YERT8JPLI48",
    "narration": "Harry Barry"
}'

Success Response (200K)

{
  "message": "virtual account created successfully",
  "status": "success",
  "data": {
    "id": "ff469678-52df-4f7c-afd9-61eb34454435",
    "firstName": "Lunce",
    "lastName": "Harry",
    "email": "harry@malinator.com",
    "phoneNumber": "+2348123456787",
    "bvn": "********",
    "reference": "4567893HTTIWINN6",
    "account": {
      "bankName": "Mock Bank",
      "sortCode": null,
      "number": "0067100155"
    },
    "status": "ACTIVE",
    "currency": "NGN",
    "country": "NG",
    "created": "2025-04-14T10:03:52.793105033"
  }
}

Response Breakdown — Create Virtual Account

Upon a successful request to the Create Virtual Account endpoint, the API returns a structured JSON response containing metadata about the operation and details of the newly generated virtual account.

General Information

This section describes the high-level response fields present in every API response, regardless of the operation outcome.

Field	Type	Description
`message`	String	Human-readable message describing the result of the API call (e.g., `"virtual account created successfully"`).
`status`	String	The outcome of the API call. Typically `"success"` or `"error"`.

Virtual Account Data

This section provides detailed information about the virtual account that was successfully created. It is found under the data field in the response.

Field	Type	Description
`id`	String	Unique identifier for the virtual account resource.
`firstName`	String	First name of the individual or entity tied to the virtual account.
`lastName`	String	Last name of the account holder.
`email`	String	Email address associated with the account holder.
`phoneNumber`	String	Phone number of the account holder, including country code.
`bvn`	String	Bank Verification Number, masked for security purposes.
`reference`	String	A unique reference string passed during account creation for traceability.
`account.bankName`	String	Name of the financial institution providing the virtual account.
`account.sortCode`	String	Sort code of the bank (nullable depending on provider or region).
`account.number`	String	The virtual account number assigned to the user.
`status`	String	Current status of the virtual account (e.g., `ACTIVE`, `INACTIVE`).
`currency`	String	Currency code for transactions (e.g., `NGN`).
`country`	String	ISO 3166-1 alpha-2 country code (e.g., `NG` for Nigeria).
`created`	String	ISO 8601 formatted timestamp indicating when the virtual account was created.

Example Response (200 OK)

{
  "message": "virtual account created successfully",
  "status": "success",
  "data": {
    "id": "ff469678-52df-4f7c-afd9-61eb34454435",
    "firstName": "Lunce",
    "lastName": "Harry",
    "email": "harry@malinator.com",
    "phoneNumber": "+2348123456787",
    "bvn": "********",
    "reference": "4567893HTTIWINN6",
    "account": {
      "bankName": "Mock Bank",
      "sortCode": null,
      "number": "0067100155"
    },
    "status": "ACTIVE",
    "currency": "NGN",
    "country": "NG",
    "created": "2025-04-14T10:03:52.793105033"
  }
}

✅ Notes

bvn is always masked in the response for compliance and security.
The value of reference should 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 assuming the account is active or ready to use.

Get Transactions