Skip to main content
POST
Afriex SDK

Supported currencies

You can create virtual accounts in NGN, GHS, KES, and USD. The currency decides who can hold the account: More currencies are on the way. See Supported currencies for every country and rail, including what is coming soon.
Customers can hold NGN and GHS accounts. Requesting any other currency with a customerId returns UNSUPPORTED_VIRTUAL_ACCOUNT_CURRENCY with 422. To create a KES, USD, or other supported currency account, omit customerId so the account is minted for the business itself.
Some currencies offer only one account type, either permanent (label) or one-time (amount). Requesting a type that is not offered for the currency returns UNSUPPORTED_VIRTUAL_ACCOUNT_TYPE with 422.
Testing in sandbox. You can create virtual accounts in sandbox for the currencies available in production, and no real money moves. A sandbox account receives nothing on its own, so use Simulate Virtual Account Transfer to pay into it. See Testing in Sandbox.

Static vs dynamic virtual accounts

You choose between two flavours of virtual account by what you pass alongside currency and customerId.

Static (label)

Pass a label to group static virtual accounts by purpose. Static accounts are permanently assigned to the customer and never expire. The same account number remains valid for repeated funding. Allowed labels: SALES, OPERATIONS, PAYROLL, COLLECTIONS, VENDOR_PAYMENTS, TAX, REFUNDS, MARKETING, TREASURY, GENERAL. Use static accounts when you want stable, long-lived account numbers a customer can top up over time, organised by purpose.

Dynamic (amount)

Pass an amount to mint a dynamic (ephemeral) virtual account tied to that specific amount. Dynamic accounts expire after a short window. The amount must be greater than 0 and at most 5,000,000. Use dynamic accounts when you need to collect a specific, known amount within a defined window, like a one-time payment for a particular order.
label and amount are mutually exclusive. Supplying both is rejected at validation.

BVN requirement for NGN static virtual accounts

For NGN static virtual accounts (label-based, Nigeria), the customer must have a Bank Verification Number (BVN) on file. This is a regulatory requirement for permanently assigned accounts in Nigeria. If the BVN is missing, the API returns 400 with VIRTUAL_ACCOUNT_BVN_REQUIRED. You can supply a BVN when creating a new customer or add it to an existing customer at any time using the Update Customer KYC endpoint.
NGN static virtual accounts will fail if the customer has not provided their BVN. This requirement does not apply to dynamic virtual accounts or to virtual accounts in other currencies.

Limits

Creation is subject to a per-(business, customer, currency) cap. Requests that would exceed the cap return VIRTUAL_ACCOUNT_LIMIT_REACHED with 403. Call List Virtual Accounts first to check what already exists for the customer.

Authorizations

x-api-key
string
header
required

Static business API key issued from the dashboard. A business can provision multiple API keys, each scoped to a configurable set of permissions (e.g. read transactions, create deposits, etc). Permissions are chosen per key at creation time in the dashboard and may be revoked by deleting the key. Manage your keys and their permissions under Developer → API keys in the dashboard.

A request whose key does not carry the permission the target endpoint requires is rejected with 401 Unauthorized, the same response an unrecognised, malformed, revoked or disabled key returns. The API does not distinguish the two cases on the wire.

See the Permissions reference for the permission each endpoint requires.

Headers

x-api-version
string

API version in ISO 8601 format. The only supported version is 2026-05-18, which is also the default when the header is omitted. Any other value is rejected with a 400 Bad Request.

x-api-signature
string

Signature of the request payload, used for request authentication where payload signing is enabled for your business.

Body

application/json
currency
enum<string>
required

The 3-letter ISO 4217 currency code for the virtual account. The listed values are the supported currencies; other valid currency codes pass validation and fail later in the request.

Available options:
NGN,
GHS,
KES,
USD
customerId
string

Optional customer ID. When supplied, the VA is created for that customer. When omitted, it is created for the business owner.

amount
number

Optional amount for a dynamic (ephemeral) virtual account. Mutually exclusive with label.

Required range: x <= 5000000
label
enum<string>

Optional label that groups static virtual accounts by purpose. Mutually exclusive with amount.

Available options:
SALES,
OPERATIONS,
PAYROLL,
COLLECTIONS,
VENDOR_PAYMENTS,
TAX,
REFUNDS,
MARKETING,
TREASURY,
GENERAL

Response

Virtual account created successfully, or (empty data) requested and pending with the issuing bank.

data
object

A payment method. Empty fields are omitted. Account-shaped channels (BANK_ACCOUNT, MOBILE_MONEY, SWIFT, etc.) populate accountName, accountNumber, and institution; the CARD channel instead populates last4, brand, expiration, and cardName.