Get or Create Virtual Account
Retrieves an existing virtual account or creates a new one for the specified currency. Important: This endpoint is only active in production and does not work on staging/dev. Send a GET request with the required currency parameter and optional fields. The system will either return an existing virtual account (as a PaymentMethod object) or automatically create and return a new one if none exists for that currency/customer (or business if no customerId is provided).
Virtual account types:
-
VIRTUAL_ACCOUNT(default) — Creates or retrieves a dedicated virtual bank account for the customer.currencyis required;amount,customerId, andreferenceare optional. -
POOL_ACCOUNT— Assigns a shared business pool account for the customer’s country.country,amount,customerId, andreferenceare all required. The account currency is automatically derived from thecountrycode (e.g.NG→NGN,KE→KES); pass acurrencyvalue that matches the country’s native currency.
Retrieves an existing virtual account or creates a new one for the specified currency. Important: This endpoint is only active in production and does not work on staging/dev. Send a GET request with the required currency parameter and optional fields. The system will either return an existing virtual account (as a PaymentMethod object) or automatically create and return a new one if none exists for that currency/customer (or business if no customerId is provided). Important: This endpoint is only active in production and does not work on staging/dev.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.
https://dev.to/afriex/send-a-link-get-paid-building-payment-links-with-afriex-13ak
Virtual account types
This endpoint supports two distinct virtual account types, controlled by thetype parameter.
VIRTUAL_ACCOUNT (default)
Creates or retrieves a dedicated virtual bank account assigned to a specific customer. The behavior depends on whether you pass anamount.
Reserved virtual accounts
When you call this endpoint without anamount, the system creates a reserved virtual account. This account is permanently assigned to the customer and never expires. The same account number is returned on every subsequent call for that customer and currency. The customer can fund it at any time, for any amount.
Use this when you want a stable, long-lived account number for a customer: for example, a fixed deposit reference they can top up repeatedly.
Time-sensitive virtual accounts
When you call this endpoint with anamount, the system creates a time-sensitive (dynamic) virtual account. This account is tied to that specific amount and will expire after a set period. The response includes an expiresInMinutes field indicating how long the account is valid.
Use this when you need to collect a specific, known amount within a defined window. For example, a one-time payment for a particular order.
| Reserved | Time-sensitive | |
|---|---|---|
| Triggered by | Omitting amount | Passing amount |
| Expires | Never | Yes (expiresInMinutes in response) |
| Amount-specific | No (accepts any amount) | Yes (tied to the amount passed) |
| Reusable | Yes (same account returned on repeat calls) | No (new account each time) |
| BVN required (NGN) | Yes | No |
VIRTUAL_ACCOUNT. The distinction is controlled entirely by whether you include the amount parameter.BVN requirement for NGN reserved virtual accounts
For NGN reserved virtual accounts (Nigeria, noamount passed), 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.
POOL_ACCOUNT
Assigns a shared pool account to a customer for a specific transaction. The account number comes from a pool of Afriex-managed accounts and is tied to a particular amount and reference.currency,country,amount,customerId, andreferenceare all requiredamountmust be greater than 0. Limits vary by country.- The customer sends exactly that amount to the assigned account number
Virtual accounts are for end customers
Virtual accounts are designed for your customers as end users, meaning the people your business is acting on behalf of. Each virtual account is linked to acustomerId (or to the business if no customerId is provided). Payments received into a virtual account are attributed to the associated customer in your Afriex system.
Make sure you have created a Customer record before calling this endpoint if you intend to link the account to a specific person. See Create Customer.Authorizations
Static business API key from the dashboard
Query Parameters
The 3-letter ISO 4217 currency code for the virtual account. Required for VIRTUAL_ACCOUNT. For POOL_ACCOUNT, the currency is automatically derived from the country parameter — pass the native currency of the given country (e.g. NGN for NG, KES for KE).
USD, NGN, KES, GBP, EUR The type of virtual account to create or retrieve. Defaults to VIRTUAL_ACCOUNT if not specified.
VIRTUAL_ACCOUNT, POOL_ACCOUNT The ISO 3166-1 alpha-2 country code for the virtual account. Required when type is POOL_ACCOUNT. The account currency is automatically derived from this value — ensure the currency parameter matches the country's native currency.
"NG"
Optional expected transaction amount. Required when type is POOL_ACCOUNT. Must be greater than 0. Limits vary by country.
x >= 0Optional customer ID. If not provided, the account will be created for the business. Required when type is POOL_ACCOUNT.
Optional transaction reference. Required when type is POOL_ACCOUNT.
Response
Virtual account retrieved or created successfully.