post
https://api-staging.payline.co/api/virtual-accounts
Creates a virtual account (static or dynamic) for the authenticated business. Static accounts require full KYC details (middle name, phone, DOB, BVN, gender, address); dynamic accounts only require first/last name, email, currency, and reference.
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Two flavours are available:
- Static — long-lived, persistent account tied to a specific customer. Requires full KYC (name, DOB, BVN, address, gender, phone). Use this for recurring customer collections (rent, subscriptions, dedicated supplier accounts).
- Dynamic — short-lived, ephemeral account tied to a single payment. Requires only minimal customer info. Use this for one-shot transactions (checkout sessions, invoices).
Request Body
| Field | Type | Required? | Description |
|---|---|---|---|
type | string | Yes (always) | "static" or "dynamic". Determines which fields below are required. |
first_name | string | Yes (always) | Customer's first name. |
last_name | string | Yes (always) | Customer's last name. |
email | string | Yes (always) | Customer's email address. Must be a valid email format. |
currency | string | Yes (always) | ISO 4217 currency code (e.g. "NGN"). |
| account_type | string | No (default individual) | individual or business. |
| business_name | string | Required when account_type=business | Approved business name on the account. |
reference | string | Yes (always) | Your unique reference for this virtual account. Use it later to fetch the account. |
address | object | Yes (always) | Customer address — see address below. |
middle_name | string | Yes (static only) | Customer's middle name. |
phone_number | string | Yes (static only) | Customer's phone number. 1–11 characters. |
dob | string | Yes (static only) | Customer's date of birth (YYYY-MM-DD). |
bvn | string | Yes (static only) | Customer's Bank Verification Number. |
gender | string | Yes (static only) | "male" or "female". |
| Field | Type | Required | Description |
|---|---|---|---|
address_line1 | string | Yes | Street address line 1. |
address_line2 | string | Optional | Street address line 2 (apt, suite, etc.). |
city | string | Yes | City. |
state | string | Yes | State or region. |
postal_code | string | Yes | ZIP or postal code. |
country | string | Yes | Country (e.g. "NGA"). |
🚧 Business accounts are static-only
When account_type=business, type must be static, and business_name, phone_number (≤ 11 digits) and bvn are required. First/last name, DOB and gender are not used.
Example Requests
Dynamic virtual account (one-shot)
{
"type": "dynamic",
"first_name": "Jane",
"last_name": "Doe",
"email": "[email protected]",
"currency": "NGN",
"reference": "VA-INVOICE-2226",
"address": {
"address_line1": "12 Marina Road",
"city": "Lagos",
"state": "Lagos",
"postal_code": "101241",
"country": "NGA"
}
}Static virtual account (persistent, full KYC)
{
"type": "static",
"first_name": "Jane",
"middle_name": "Marie",
"last_name": "Doe",
"email": "[email protected]",
"phone_number": "08012345678",
"dob": "1990-04-21",
"bvn": "22198765432",
"gender": "female",
"currency": "NGN",
"reference": "VA-CUST-9381",
"address": {
"address_line1": "12 Marina Road",
"address_line2": "Apt 4B",
"city": "Lagos",
"state": "Lagos",
"postal_code": "101241",
"country": "NGA"
}
}Response Body
| Field | Type | Description |
|---|---|---|
id | string (UUID) | The Payline ID for this virtual account. |
currency | string | Currency the account accepts. |
status | string | Current status — "active" or "inactive". |
reference | string | Your merchant reference (echoed). |
customer | object | Account holder details — see customer below. |
| Field | Type | Description |
|---|---|---|
name | string | Full name of the account holder. |
account_number | string | The virtual bank account number to share with the payer. |
bank_code | string | Bank code of the issuing bank. |
email | string | Account holder email. |
reference | string | Customer reference. |
Example Responses
Dynamic virtual account
{
"id": "ba81f25c-1234-4f6a-9e8b-7c0d1a2b3c4d",
"currency": "NGN",
"status": "active",
"reference": "VA-INVOICE-2226",
"customer": {
"name": "Jane Doe",
"account_number": "",
"bank_code": "",
"email": "[email protected]",
"reference": "VA-INVOICE-2226"
}
}Static virtual account
{
"id": "e2c4d6f8-aabb-ccdd-eeff-001122334455",
"currency": "NGN",
"status": "active",
"reference": "VA-CUST-9381",
"customer": {
"name": "Jane Marie Doe",
"account_number": "9988776655",
"bank_code": "101",
"email": "[email protected]",
"reference": "VA-CUST-9381"
}
}Dynamic accounts return an
account_numberonly after a payment session attaches one to them at transaction time. Static accounts return the permanent account number immediately on creation.