Virtual Account

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>

string

required

Customer ID or code

string

The preferred bank slug for the virtual account

string

Subaccount code to assign to the virtual account

string

Split code to assign to the virtual account

string

Customer’s first name

string

Customer’s last name

string

Customer’s phone number

object

string

The bank name

number

The bank ID

string

The bank slug

string

The account name

string

The generated virtual account number

boolean

Whether the account is assigned

string

The account currency

boolean

Whether the account is active

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>

string

required

Customer’s email address

string

required

Customer’s first name

string

required

Customer’s last name

string

required

Customer’s phone number

'NG' | 'GH'

required

Customer’s country code

string

Customer’s account number for validation (Nigeria only)

string

Customer’s Bank Verification Number (Nigeria only)

string

Customer’s bank code

string

Subaccount code to assign

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>

boolean

required

Filter by active status

'NGN' | 'USD' | 'GHS' | 'ZAR' | 'KES' | 'XOF'

required

Filter by currency (defaults to NGN)

string

Filter by provider slug

string

Filter by bank ID

string

Filter by customer ID or code

array

Array of virtual account objects

object

Bank details (name, id, slug)

string

The account name

string

The account number

boolean

Whether the account is assigned

boolean

Whether the account is active

object

Associated customer details

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>

string

required

The ID of the dedicated virtual account

object

Bank details (name, id, slug)

string

The account name

string

The account number

boolean

Whether the account is assigned

string

The currency

boolean

Whether the account is active

object

Full customer details including metadata and phone

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>

string

required

The virtual account number

string

required

The provider slug

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>

string

required

The ID of the dedicated virtual account to deactivate

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>

string

required

Customer ID or code

string

Subaccount code

string

Split code

string

Preferred bank slug

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>

string

required

The virtual account number

object

number

The account ID

object

Empty object indicating split has been removed

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>

array

Array of available bank providers

string

The provider slug

number

The bank ID

string

The bank name

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}`);
  });
}

Core

Modules

Overview

Methods

create

assign

list

fetch

requery

deactivate

addSplit

removeSplit

fetchBanks

​Overview

​Methods

​create

​assign

​list

​fetch

​requery

​deactivate

​addSplit

​removeSplit

​fetchBanks

​Related Resources

Overview

Methods

create

assign

list

fetch

requery

deactivate

addSplit

removeSplit

fetchBanks

Related Resources