Customer's legal first name. Combined with last_name to form the account_name a payer sees when confirming a transfer.

Customer's legal surname. Must match the name held against the BVN, or verification fails.

A valid, unique email address for the customer. Used to identify them on your account and for any notifications.

The customer's active phone number. Send the subscriber number and set dial_code alongside it, for example '8012345678' with '+234'. The forms '08012345678' and '+2348012345678' are also accepted, but the number is stored exactly as you send it and dial_code is never inferred from it, so set dial_code yourself if you want it recorded. A customer created without a phone number is accepted, but cannot be issued an account until you add one.

Date of birth as an ISO date, for example '1994-03-21'. The customer must be 18 or over, and it is checked against the BVN record.

The kind of identity document supplied. Must be 'bvn' for a Nigerian virtual account; no other value is accepted.

The customer's 11 digit Bank Verification Number. Checked against the national registry when the account is created, so a BVN that does not match the name and date of birth is rejected.

A unique, client-generated identifier for this account. Acts as the idempotency key: retrying with a reference you have already used returns the existing account rather than issuing a second one.

Currency the account should collect in. 'NGN' is the only accepted value today — call Supported Currencies for the live list.

The customer this account is issued to. Must already carry a BVN, date of birth and contact details, or the request fails naming the missing fields.

Display name for the account in your own systems. Defaults to the customer's account name when omitted, and can be changed later with Update Account Alias.

Bitnob's identifier for the virtual account. This is the :id you pass to every other endpoint in this section, so persist it against your customer record.

The company the account was issued under. Derived from the API key you authenticated with, not from anything you send.

The Nigerian bank account number your customer pays into. Show it alongside bank_name; together they are all a payer needs to send a transfer.

The name the account resolves to on the banking network. Taken from the customer's first and last name, so it is what a payer sees when they confirm the transfer.

The bank holding the account, for example 'Sandbox Bank'. Assigned by us at creation; you cannot choose it, and it may differ between accounts.

The reference you supplied on the request, echoed back. Use it to match the account to your own record without storing the Bitnob id first.

The customer this account was issued to. One customer can hold more than one account, so do not assume it is unique across the list.

Currency the account collects in. Always 'NGN' today — see Supported Currencies for the live list.

Whether the account can currently receive money. 'active' means it is live and payable.

Display name for your own dashboards. Defaults to the account name when you do not supply one, and is the only field Update Account Alias changes.

Mirrors the customer's type, for example 'individual'. Set from the customer record rather than the account request.

ISO 8601 timestamp of when the account was issued, in UTC.

ISO 8601 timestamp of the last change. Equal to created_at until something changes it, such as an alias update.

Whether another page of accounts follows this one. Use it to decide whether to request the next page rather than counting results yourself.

Whether a page precedes this one. False on the first page.

Total number of accounts your company holds, across every page rather than just this one.

Bitnob's identifier for this single deposit. Store it against your own record if you need to look the transaction up again later.

The account the money was paid into. Matches the :id on the request path, so you can attribute the deposit to the customer that account belongs to.

The banking provider's own reference for the transfer. Quote this when raising a query with support, since it is the identifier the bank recognises.

The matching entry on your Bitnob ledger. Use it to tie this deposit to the corresponding balance movement when you reconcile.

Amount received, in naira and as a string rather than a number. '100000' is one hundred thousand naira, not one thousand — naira is never expressed in kobo.

Currency of the deposit. Always 'NGN' today, since NGN is the only currency virtual accounts support.

Direction of the movement. 'credit' for money paid into the account.

Where the deposit sits in its lifecycle. 'completed' means it has settled and your balance has already moved.

Bitnob's own reference for the deposit, for example 'sbx-dep-3f8a2c14…'. This is not the reference you chose when creating the account.

Any extra data attached to the transaction, JSON-encoded as a string rather than returned as an object. Parse it before use; it is '{}' when empty.

Total transactions on the account, returned alongside 'limit' and 'offset'. Note this endpoint returns a flat count, unlike List Virtual Accounts which nests paging inside a page_info object.

The new display name for the account. Only this field and updated_at change; the account number, bank and customer are untouched.

The currency codes you can currently issue virtual accounts in.

How many currencies are supported, returned alongside limit and offset.

The account's balance after the simulated deposit, in naira as a string. Each call adds 100000, so repeated calls step it up predictably.