Virtual Account
Create temporary bank accounts to receive payments via bank transfer. When a customer transfers money to a virtual account, the payment is automatically matched and settled to your account.
Required permission: virtual_account
Create Virtual Account
POST /v1/checkout/virtual-accountAuthentication
Requires a secret key (sk_*).
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
amount | string | Yes | Expected amount in naira (e.g., "5000.00") |
validity_minutes | integer | No | How long the account stays active. Default: 4320 (72h). Max: 4320 |
amount_validation | string | No | Amount validation rule. See Dynamic PayID amount rules. Default: provider default |
metadata | object | No | Custom key-value data stored with the account |
Settlement
Payments received on this virtual account are settled to your API key's configured settlement ledger. To change where payments are settled, update your API key's settlement configuration in the dashboard.
Example request
bash
curl -X POST https://api.zevpaycheckout.com/v1/checkout/virtual-account \
-H "Content-Type: application/json" \
-H "x-api-key: sk_test_your_secret_key" \
-d '{
"amount": "5000.00",
"validity_minutes": 1440,
"metadata": {
"order_id": "ORD-12345"
}
}'javascript
const response = await fetch(
"https://api.zevpaycheckout.com/v1/checkout/virtual-account",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": "sk_test_your_secret_key",
},
body: JSON.stringify({
amount: "5000.00",
validity_minutes: 1440,
metadata: { order_id: "ORD-12345" },
}),
}
);
const data = await response.json();Response
json
{
"success": true,
"data": {
"public_id": "abc123def456ghi78",
"account_number": "4601234567",
"merchant_name": "My Business",
"provider": "vfd",
"reference": "ZVP-VA-1772906868046-d5aa1c",
"amount": "5000.00",
"status": "pending",
"expires_at": "2026-03-09T12:00:00.000Z",
"completed_at": null,
"source": "api",
"created_at": "2026-03-08T12:00:00.000Z"
}
}The account_number is the bank account number your customer should transfer to. The bank is VFD Microfinance Bank.
List Virtual Accounts
GET /v1/checkout/virtual-accountQuery parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
page_size | integer | 20 | Items per page (max 100) |
status | string | — | Filter: "pending", "completed", "expired", "cancelled" |
Example request
bash
curl "https://api.zevpaycheckout.com/v1/checkout/virtual-account?status=pending&page_size=10" \
-H "x-api-key: sk_test_your_secret_key"Response
json
{
"success": true,
"data": {
"items": [
{
"public_id": "abc123def456ghi78",
"account_number": "4601234567",
"merchant_name": "My Business",
"provider": "vfd",
"reference": "ZVP-VA-1772906868046-d5aa1c",
"amount": "5000.00",
"status": "pending",
"expires_at": "2026-03-09T12:00:00.000Z",
"completed_at": null,
"source": "api",
"created_at": "2026-03-08T12:00:00.000Z"
}
],
"total": 1,
"page": 1,
"page_size": 10,
"total_pages": 1
}
}Get Virtual Account
GET /v1/checkout/virtual-account/:publicIdPath parameters
| Parameter | Type | Description |
|---|---|---|
publicId | string | Virtual account public ID |
Example request
bash
curl https://api.zevpaycheckout.com/v1/checkout/virtual-account/abc123def456ghi78 \
-H "x-api-key: sk_test_your_secret_key"Status lifecycle
| Status | Description |
|---|---|
pending | Account is active and awaiting payment |
completed | Payment received and settled |
expired | Account expired without receiving payment |
cancelled | Account creation failed at the provider |
Response fields
| Field | Type | Description |
|---|---|---|
public_id | string | Unique public identifier |
account_number | string|null | Bank account number (assigned by provider) |
merchant_name | string|null | Your business name displayed on the account |
provider | string | Banking provider (e.g., "vfd") |
reference | string | Unique internal reference |
amount | string|null | Expected payment amount (naira) |
status | string | Account status (see lifecycle) |
expires_at | string|null | ISO 8601 expiry timestamp |
completed_at | string|null | ISO 8601 completion timestamp |
source | string | Creation source ("api", "dashboard", etc.) |
created_at | string | ISO 8601 creation timestamp |
Try it — Create Virtual Account
API Playground
Try it — List Virtual Accounts
API Playground