Getting Started

Create a virtual account for a customer. The response returns the account number they can pay into.

Endpoint

Request Body

reference must be unique to you and acts as the idempotency key. NGN is currently the only supported currency.

This is the most common reason a virtual account request fails, so get it right before you call.

We are required to verify the identity behind every naira account, so the customer record has to carry all of the following before we can issue one:

field	notes
first_name
last_name
email
phone_number
date_of_birth	must be 18 or over
id_type	must be "bvn"
id_number	the 11 digit BVN

The BVN lives on the customer, not on the virtual account request. Set it when you create the customer, or patch an existing one:

Customer

We verify the BVN against the national registry when the account is created. A BVN that does not match the customer's details is rejected.

Every detail must match the BVN

The name and date of birth you send must be the ones registered against the BVN. If either differs, verification fails even when the BVN itself is valid.

If anything is missing you get one error naming every missing field at once, so you can fix them in a single pass rather than discovering them one at a time:

Error

The error names customer record fields

The error refers to the customer record fields, not the fields in the request you just sent. There’s nothing wrong with your virtual account payload. Please update the customer record and try again.

method	path	purpose
GET	/api/virtual-accounts	List your accounts
GET	/api/virtual-accounts/:id	Fetch one
GET	/api/virtual-accounts/:id/transactions	Deposits into that account
PATCH	/api/virtual-accounts/:id/alias	Change the display name
GET	/api/virtual-accounts/supported-currencies	Currently returns NGN

In sandbox, POST /api/virtual-accounts/:id/simulate-deposit fakes an inbound transfer so you can test without moving real money. It is rejected in production.