Skip to main content
POST
/
api
/
v1
/
payment-method
/
virtual-account
curl --request POST \
  --url https://sandbox.api.afriex.com/api/v1/payment-method/virtual-account \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "currency": "NGN",
  "customerId": "68e6717848e1f632e9686460",
  "label": "SALES"
}
'
{
  "data": {
    "paymentMethodId": "690cc5bbe2a1143ff6070119",
    "channel": "VIRTUAL_BANK_ACCOUNT",
    "customerId": "68e6717848e1f632e9686460",
    "institution": {
      "institutionName": "FIDELITY BANK"
    },
    "accountName": "Lily New",
    "accountNumber": "3820404958",
    "countryCode": "NG"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.afriex.com/llms.txt

Use this file to discover all available pages before exploring further.

Creates a new virtual account for the resolved customer-or-owner and currency. Pass customerId to mint the virtual account for a specific end-user, or omit it to mint one for the business owner. Important: Virtual accounts are only active in production and do not work on staging/dev.

​
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. 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 an error. 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 400. Call List Virtual Accounts first to check what already exists for the customer.

Authorizations

​
x-api-key
string
header
required

Static business API key from the dashboard

Body

application/json
​
currency
enum<string>
required

The 3-letter ISO 4217 currency code for the virtual account.

Available options:
USD,
NGN,
GBP,
EUR
​
customerId
string

Optional customer ID. When supplied, the virtual account 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: 0 <= 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.

​
data
object