Skip to main content

Documentation Index

Fetch the complete documentation index at: https://paystack-sdk.efobi.dev/llms.txt

Use this file to discover all available pages before exploring further.

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>
​
customer
string
required
Customer ID or code
​
preferred_bank
string
The preferred bank slug for the virtual account
​
subaccount
string
Subaccount code to assign to the virtual account
​
split_code
string
Split code to assign to the virtual account
​
first_name
string
Customer’s first name
​
last_name
string
Customer’s last name
​
phone
string
Customer’s phone number
​
data
object
​
bank
object
​
name
string
The bank name
​
id
number
The bank ID
​
slug
string
The bank slug
​
account_name
string
The account name
​
account_number
string
The generated virtual account number
​
assigned
boolean
Whether the account is assigned
​
currency
string
The account currency
​
active
boolean
Whether the account is active
​
customer
object
Customer details including id, email, and customer_code
Example: 
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>
​
email
string
required
Customer’s email address
​
first_name
string
required
Customer’s first name
​
last_name
string
required
Customer’s last name
​
phone
string
required
Customer’s phone number
​
country
'NG' | 'GH'
required
Customer’s country code
​
account_number
string
Customer’s account number for validation (Nigeria only)
​
bvn
string
Customer’s Bank Verification Number (Nigeria only)
​
bank_code
string
Customer’s bank code
​
subaccount
string
Subaccount code to assign
​
split_code
string
Split code to assign
Example: 
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>
​
active
boolean
required
Filter by active status
​
currency
'NGN' | 'USD' | 'GHS' | 'ZAR' | 'KES' | 'XOF'
required
Filter by currency (defaults to NGN)
​
provider_slug
string
Filter by provider slug
​
bank_id
string
Filter by bank ID
​
customer
string
Filter by customer ID or code
​
data
array
Array of virtual account objects
​
bank
object
Bank details (name, id, slug)
​
account_name
string
The account name
​
account_number
string
The account number
​
assigned
boolean
Whether the account is assigned
​
active
boolean
Whether the account is active
​
customer
object
Associated customer details
​
meta
object
Pagination metadata including total, page, perPage, and pageCount
Example: 
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>
​
dedicated_account_id
string
required
The ID of the dedicated virtual account
​
data
object
​
bank
object
Bank details (name, id, slug)
​
account_name
string
The account name
​
account_number
string
The account number
​
assigned
boolean
Whether the account is assigned
​
currency
string
The currency
​
active
boolean
Whether the account is active
​
customer
object
Full customer details including metadata and phone
​
split_config
string
The split configuration if any
Example: 
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>
​
account_number
string
required
The virtual account number
​
provider_slug
string
required
The provider slug
​
date
string
ISO date to check for transactions (optional)
Example: 
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>
​
dedicated_account_id
string
required
The ID of the dedicated virtual account to deactivate
​
data
object
The deactivated virtual account details with active status set to false
Example: 
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>
​
customer
string
required
Customer ID or code
​
subaccount
string
Subaccount code
​
split_code
string
Split code
​
preferred_bank
string
Preferred bank slug
​
data
object
Updated virtual account with split_config containing the split_code
Example: 
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>
​
account_number
string
required
The virtual account number
​
data
object
​
id
number
The account ID
​
split_config
object
Empty object indicating split has been removed
​
account_number
string
The account number
Example: 
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>
​
data
array
Array of available bank providers
​
provider_slug
string
The provider slug
​
bank_id
number
The bank ID
​
bank_name
string
The bank name
​
id
number
The provider ID
Example: 
const { data, error } = await paystack.virtualAccount.fetchBanks();

if (data) {
  data.data.forEach(bank => {
    console.log(`${bank.bank_name}: ${bank.provider_slug}`);
  });
}