Create Single Virtual Account

Create Virtual Account

Generate a virtual bank account number for a customer. Transfers into the account are credited to your BudPay wallet.

🇳🇬

Nigeria Only: This feature is only available to businesses in Nigeria.

Bank Codes: Call Fetch Bank List to get the bankCode values available to your integration.

Create Virtual Account

Endpoint: POST https://api.budpay.com/api/v2/collection/virtual-account

Parameters

This section details the header information required for creating a virtual account.

Field Name	Description
URL	`https://api.budpay.com/api/v2/collection/virtual-account`
Method	`POST`
Authorization	`Bearer YOUR_SECRET_KEY` (Replace with your actual BudPay secret key)
Content-Type	`application/json`

Request Parameters

Parameter	Type	Required	Description
`reference`	String	Yes	Your unique reference for the virtual account
`accountType`	String	Yes	`reserved` or `checkout` (see Account Types)
`accountName`	String	Yes	Name to display on the virtual account
`bankCode`	String	Yes	Code of the partner bank, from Fetch Bank List
`firstName`	String	Yes	Customer's first name
`lastName`	String	Yes	Customer's last name
`customerEmail`	String	Yes	Customer's email address
`amount`	Number	Yes	Amount the account should receive. Must be `0` for `reserved` accounts
`expiryInMinutes`	Integer	Yes	Minutes until the account expires. Must be `0` for `reserved` accounts

Account Types

Type	Use Case	`amount`	`expiryInMinutes`
`reserved`	Permanent account a customer can pay into repeatedly	Must be `0`	Must be `0`
`checkout`	Temporary account for a single payment of a fixed amount	Greater than `0`	Greater than `0`

Sample Request

Endpoint: POST https://api.budpay.com/api/v2/collection/virtual-account

1curl -X POST 'https://api.budpay.com/api/v2/collection/virtual-account' \2  -H 'Content-Type: application/json' \3  -H 'Authorization: Bearer YOUR_SECRET_KEY' \4  -d '{5  "reference": "2026e3431VA0000001",6  "amount": 0,7  "accountType": "reserved",8  "accountName": "Test Customer Surname",9  "bankCode": "000027",10  "firstName": "Test Customer",11  "lastName": "Surname",12  "customerEmail": "a@b.com",13  "expiryInMinutes": 014}'

{  "status": true,  "message": "Virtual account generated",  "data": {    "accountNumber": "9888145123",    "accountName": "Test Customer Surname",    "bankCode": "000027",    "bankName": "Globus Bank",    "domain": "live",    "accountType": "reserved",    "accountStatus": "active",    "expiryInMinutes": 0,    "reference": "2026e3431VA0000001",    "createdAt": "2026-10-21T16:29:02.6555552Z"  }}

Response Fields

Field	Description
`accountNumber`	Virtual account number the customer pays into
`accountName`	Name on the virtual account
`bankCode`	Code of the partner bank
`bankName`	Name of the partner bank
`domain`	Environment (`test` or `live`)
`accountType`	`reserved` or `checkout`
`accountStatus`	Account status (e.g. `active`)
`expiryInMinutes`	Minutes until the account expires (`0` for reserved accounts)
`reference`	The reference you supplied
`createdAt`	Time the account was created (UTC)

Fetch Bank List Fetch by Reference