> ## 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.
# Create Virtual Account
> Creates a new virtual account for the resolved customer-or-owner and
currency. Pass `customerId` to mint the VA for a specific end-user;
omit it to mint one for the business owner.
Subject to a per-(business, customer, currency) limit. Requests that
would exceed the limit return `VIRTUAL_ACCOUNT_LIMIT_REACHED`.
**Label vs amount:** `label` groups static virtual accounts by
purpose (e.g. `SALES`, `OPERATIONS`). It is **mutually exclusive
with `amount`**, which routes to a dynamic (ephemeral) virtual
account. Supplying both is rejected at validation.
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](/api-reference/endpoint/customers/update-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](/api-reference/endpoint/payment-methods/virtual-account) first to check what already exists for the customer.
## OpenAPI
````yaml POST /api/v1/payment-method/virtual-account
openapi: 3.1.0
info:
title: Afriex Business API
version: 1.0.8
description: >-
Welcome to the Afriex Business API. This API allows you to manage customers,
process payments, handle payouts, and receive real-time notifications via
webhooks.
For detailed guidance on authentication, pagination, error handling, and
webhooks, please refer to the [dedicated guides](https://docs.afriex.com) in
the top bar. The guide provides a step-by-step instructions to help you
integrate seamlessly.
termsOfService: https://www.afriex.com/terms-and-condition
contact:
name: Afriex API Support
email: eng@afriex.co
url: https://docs.afriex.com
license:
name: Proprietary
url: https://www.afriex.com/terms-and-condition
servers:
- url: https://sandbox.api.afriex.com
description: Staging Base URL
- url: https://api.afriex.com
description: Production Base URL
security:
- ApiKey: []
tags:
- name: Customers
description: Create and manage your customers.
- name: Payment Methods
description: Register and resolve customer payout and collection methods.
- name: Transactions
description: Create and track deposits, withdrawals, and swaps.
- name: Balance
description: View and top up your business wallet balances.
- name: Rates
description: Fetch real-time exchange rates.
- name: Checkout Sessions
description: Create hosted checkout sessions.
- name: Webhooks
description: Webhook event payloads and sandbox webhook testing.
paths:
/api/v1/payment-method/virtual-account:
parameters:
- $ref: '#/components/parameters/x-api-version'
post:
tags:
- Payment Methods
summary: Create a virtual account payment method
description: |
Creates a new virtual account for the resolved customer-or-owner and
currency. Pass `customerId` to mint the VA for a specific end-user;
omit it to mint one for the business owner.
Subject to a per-(business, customer, currency) limit. Requests that
would exceed the limit return `VIRTUAL_ACCOUNT_LIMIT_REACHED`.
**Label vs amount:** `label` groups static virtual accounts by
purpose (e.g. `SALES`, `OPERATIONS`). It is **mutually exclusive
with `amount`**, which routes to a dynamic (ephemeral) virtual
account. Supplying both is rejected at validation.
operationId: createVirtualAccount
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- currency
properties:
currency:
type: string
description: The 3-letter ISO 4217 currency code for the virtual account.
enum:
- USD
- NGN
- GBP
- EUR
customerId:
type: string
description: |
Optional customer ID. When supplied, the VA is created
for that customer. When omitted, it is created for the
business owner.
amount:
type: number
description: |
Optional amount for a dynamic (ephemeral) virtual
account. Mutually exclusive with `label`.
minimum: 0
maximum: 5000000
label:
type: string
description: |
Optional label that groups static virtual accounts by
purpose. Mutually exclusive with `amount`.
enum:
- SALES
- OPERATIONS
- PAYROLL
- COLLECTIONS
- VENDOR_PAYMENTS
- TAX
- REFUNDS
- MARKETING
- TREASURY
- GENERAL
examples:
staticWithLabel:
summary: Static virtual account grouped by label
value:
currency: NGN
customerId: 68e6717848e1f632e9686460
label: SALES
dynamicWithAmount:
summary: Dynamic (ephemeral) virtual account tied to an amount
value:
currency: NGN
customerId: 68e6717848e1f632e9686460
amount: 50000
businessOwner:
summary: Virtual account for the business owner (no customerId)
value:
currency: USD
label: TREASURY
responses:
'201':
description: Virtual account created successfully.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/PaymentMethod'
examples:
ngnVirtualAccount:
summary: NGN dedicated virtual bank account
value:
data:
paymentMethodId: 690cc5bbe2a1143ff6070119
channel: VIRTUAL_BANK_ACCOUNT
customerId: 68e6717848e1f632e9686460
institution:
institutionName: FIDELITY BANK
accountName: Lily New
accountNumber: '3820404958'
countryCode: NG
'400':
description: |
Invalid request (e.g. `label` and `amount` both supplied) or
virtual account limit reached.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
labelAndAmount:
summary: Both label and amount supplied
value:
code: VALIDATION_ERROR
error: >-
Failed to parse request. Issues: 'label' and 'amount' are
mutually exclusive
details: {}
limitReached:
summary: Per-(business, customer, currency) cap reached
value:
code: VIRTUAL_ACCOUNT_LIMIT_REACHED
error: Virtual account limit reached
details:
errorMessage: Virtual account limit reached
friendlyMessage: >-
You have reached the maximum number of virtual accounts
for this customer and currency.
missingCurrency:
summary: Missing currency
value:
code: VALIDATION_ERROR
error: 'Failed to parse request. Issues: ''currency'' is required'
details: {}
'401':
description: Unauthorized - Invalid business API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingApiKey:
summary: Missing API key
value:
code: AUTHENTICATION_ERROR
error: Authorization header is missing
details: {}
invalidApiKey:
summary: Invalid API key
value:
code: AUTHENTICATION_ERROR
error: Invalid authorization header
details: {}
'500':
description: Server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
serverError:
summary: Unexpected server error
value:
code: INTERNAL_SERVER_ERROR
error: It's not you, it's us, please reach out to support
details: {}
x-codeSamples:
- lang: TypeScript
label: Afriex SDK
source: |
const account = await afriex.paymentMethods.createVirtualAccount({
currency: "USD",
label: "SALES",
customerId: "optional-customer-id",
});
components:
parameters:
x-api-version:
name: x-api-version
in: header
required: false
description: >-
API version in ISO 8601 format (e.g. 2025-12-28). Defaults to latest
stable.
schema:
type: string
schemas:
PaymentMethod:
type: object
description: >-
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.
properties:
paymentMethodId:
type: string
description: The unique identifier for the payment method.
customerId:
$ref: '#/components/schemas/customerId'
reference:
type: string
description: Identifier to reconcile incoming deposits against.
institution:
$ref: '#/components/schemas/PaymentMethodInstitution'
transaction:
$ref: '#/components/schemas/PaymentMethodTransaction'
recipient:
$ref: '#/components/schemas/PaymentMethodRecipient'
channel:
type: string
enum:
- BANK_ACCOUNT
- MOBILE_MONEY
- SWIFT
- INTERAC
- UPI
- WE_CHAT
- ALIPAY
- CARD
- CRYPTO
- VIRTUAL_BANK_ACCOUNT
- POOL_ACCOUNT
- ACH_BANK_ACCOUNT
- PAYBILL_TILL
- RFP
- VIRTUAL_CARD
description: The payment method channel.
countryCode:
type: string
description: The ISO 3166-1 alpha-2 country code.
currency:
type: string
description: >-
The payment method's currency (ISO 4217). Use this instead of
inferring currency from countryCode, which is ambiguous (e.g. a USD
account in a non-US country).
capabilities:
type: array
items:
type: string
description: >-
The operations this payment method is enabled for (e.g. DEPOSIT,
WITHDRAW). Use it to select deposit-capable vs withdraw-capable
methods. Also filterable via the `capabilities` query parameter.
accountName:
type: string
description: Name of the account holder. Present for account-shaped channels.
accountNumber:
type: string
description: Account number. Present for account-shaped channels.
routingNumber:
type: string
description: >-
Bank routing number. Present for account-shaped channels that carry
one (e.g. ACH bank accounts).
status:
type: string
enum:
- active
- pending
- deleted
- expired
- blocked
description: Lifecycle status of the payment method.
last4:
type: string
description: Last 4 digits of the card. CARD channel only.
brand:
type: string
enum:
- Visa
- MasterCard
- Discover
- American Express
- JCB
- Diners Club
- Eftpos Australia
- UnionPay
- Unknown
description: Card brand. CARD channel only.
expiration:
type: object
description: Card expiration. CARD channel only.
properties:
month:
type: integer
year:
type: integer
cardName:
type: string
description: Name on the card. CARD channel only.
expiresInMinutes:
type: integer
description: Minutes until a dynamic virtual account expires, when applicable.
amount:
type: number
description: Requested amount for a dynamic virtual account, when applicable.
extra:
type: object
description: Additional channel-specific properties.
additionalProperties: true
meta:
type: object
description: Optional meta data you attached to the payment method.
ErrorResponse:
type: object
properties:
code:
type: string
description: Machine-readable error code.
error:
type: string
description: Human-readable error message.
details:
$ref: '#/components/schemas/ErrorDetails'
customerId:
type: string
description: The unique identifier of the customer.
PaymentMethodInstitution:
type: object
properties:
institutionId:
type: string
description: >-
The unique identifier of the bank or mobile money provider if
required.
institutionName:
type: string
description: The name of the bank or mobile money provider if required.
institutionCode:
type: string
description: The code of the bank or mobile money provider.
institutionAddress:
type: string
description: The address of the bank or mobile money provider if required.
PaymentMethodTransaction:
type: object
properties:
transactionInvoice:
type: string
description: The invoice for the transaction in base64 string.
transactionNarration:
type: string
description: The optional reason for the transaction.
PaymentMethodRecipient:
type: object
properties:
recipientEmail:
type: string
format: email
description: The email address of the recipient if needed.
recipientPhone:
type: string
description: The phone number of the recipient in E.164 format.
recipientAddress:
type: string
description: The address of the recipient if needed.
recipientName:
type: string
description: The name of the recipient if needed.
ErrorDetails:
type: object
properties:
errorMessage:
type: string
description: Detailed/technical error message.
friendlyMessage:
type: string
description: User-facing error message safe to display.
data:
type: object
description: >-
Optional caller-safe context for the error. On a customer-create
uniqueness conflict (EMAIL_ALREADY_EXISTS /
PHONE_NUMBER_ALREADY_EXISTS) this carries the existing customer's
id, so you can adopt it without a follow-up lookup.
properties:
customerId:
type: string
description: Id of the existing customer (on a create conflict).
securitySchemes:
ApiKey:
type: apiKey
in: header
name: x-api-key
description: >-
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. Requests made with a key that does not
include the permission required by the target endpoint will be rejected
with a `403 Forbidden` response; an unrecognised, malformed or revoked
key returns `401 Unauthorized`. Manage your keys and their permissions
under **Developer → API keys** in the dashboard.
````