The VirtualAccount class provides methods for interacting with Paystack’s Dedicated Virtual Account API. Virtual accounts allow you to receive payments via bank transfers with automatically generated account numbers.
Overview
The VirtualAccount class allows you to:
- Create dedicated virtual accounts for customers
- Assign virtual accounts to existing customers
- List and fetch virtual account details
- Manage splits on virtual accounts
- Requery accounts for new transactions
- Deactivate virtual accounts
- Fetch available bank providers
Methods
create
Creates a dedicated virtual account.
async create(input: VirtualAccountCreateInput): Promise<VirtualAccountCreateResponse>
The preferred bank slug for the virtual account
Subaccount code to assign to the virtual account
Split code to assign to the virtual account
The generated virtual account number
Whether the account is assigned
Whether the account is active
Customer details including id, email, and customer_code
const { data, error } = await paystack.virtualAccount.create({
customer: "CUS_abc123",
preferred_bank: "wema-bank"
});
if (data) {
console.log(data.data.account_number);
}
assign
Assigns a dedicated virtual account to a customer.
async assign(input: VirtualAccountAssignInput): Promise<GenericResponse>
Customer’s account number for validation (Nigeria only)
Customer’s Bank Verification Number (Nigeria only)
Subaccount code to assign
const { data, error } = await paystack.virtualAccount.assign({
email: "customer@example.com",
first_name: "John",
last_name: "Doe",
phone: "+2348012345678",
country: "NG",
bvn: "12345678901"
});
if (data) {
console.log(data.message);
}
list
Lists dedicated virtual accounts.
async list(input: VirtualAccountListInput): Promise<VirtualAccountListResponse>
currency
'NGN' | 'USD' | 'GHS' | 'ZAR' | 'KES' | 'XOF'
required
Filter by currency (defaults to NGN)
Filter by customer ID or code
Array of virtual account objectsBank details (name, id, slug)
Whether the account is assigned
Whether the account is active
Associated customer details
Pagination metadata including total, page, perPage, and pageCount
const { data, error } = await paystack.virtualAccount.list({
active: true,
currency: "NGN",
customer: "CUS_abc123"
});
if (data) {
console.log(`Found ${data.meta.total} virtual accounts`);
}
fetch
Retrieves details of a dedicated virtual account.
async fetch(dedicated_account_id: string): Promise<VirtualAccountFetchResponse>
The ID of the dedicated virtual account
Bank details (name, id, slug)
Whether the account is assigned
Whether the account is active
Full customer details including metadata and phone
The split configuration if any
const { data, error } = await paystack.virtualAccount.fetch("12345");
if (data) {
console.log(data.data.account_number);
}
requery
Requeries a dedicated virtual account for new transactions.
async requery(input: VirtualAccountRequeryInput): Promise<GenericResponse>
The virtual account number
ISO date to check for transactions (optional)
const { data, error } = await paystack.virtualAccount.requery({
account_number: "0123456789",
provider_slug: "wema-bank",
date: "2024-01-15"
});
if (data) {
console.log(data.message);
}
deactivate
Deactivates a dedicated virtual account.
async deactivate(dedicated_account_id: string): Promise<VirtualAccountDeleteResponse>
The ID of the dedicated virtual account to deactivate
The deactivated virtual account details with active status set to false
const { data, error } = await paystack.virtualAccount.deactivate("12345");
if (data) {
console.log(`Account ${data.data.account_number} deactivated`);
}
addSplit
Adds a split to a dedicated virtual account.
async addSplit(input: VirtualAccountAddSplitInput): Promise<VirtualAccountAddSplitResponse>
Updated virtual account with split_config containing the split_code
const { data, error } = await paystack.virtualAccount.addSplit({
customer: "CUS_abc123",
split_code: "SPL_xyz789"
});
if (data) {
console.log(data.data.split_config.split_code);
}
removeSplit
Removes a split from a dedicated virtual account.
async removeSplit(input: VirtualAccountRemoveSplitInput): Promise<VirtualAccountRemoveSplitResponse>
The virtual account number
Empty object indicating split has been removed
const { data, error } = await paystack.virtualAccount.removeSplit({
account_number: "0123456789"
});
if (data) {
console.log("Split removed successfully");
}
fetchBanks
Fetches available bank providers for dedicated virtual accounts.
async fetchBanks(): Promise<FetchBanksResponse>
Array of available bank providers const { data, error } = await paystack.virtualAccount.fetchBanks();
if (data) {
data.data.forEach(bank => {
console.log(`${bank.bank_name}: ${bank.provider_slug}`);
});
}
