Paystack Dedicated Accounts

Paystack Dedicated Virtual Accounts

The Dedicated Virtual Account API lets you create and manage unique payment account numbers for your customers. Available for Nigerian and Ghanaian merchants.

Depends on: paystack-setup for the paystackRequest helper.
Related: paystack-subaccounts and paystack-splits for splitting DVA transactions.

Endpoints

Fetch Bank Providers

Always check available providers first:

const providers = await paystackRequest<Array<{
  provider_slug: string;
  bank_id: number;
  bank_name: string;
}>>("/dedicated_account/available_providers");
// e.g. [{ provider_slug: "wema-bank", bank_id: 20, bank_name: "Wema Bank" }]

Create DVA for Existing Customer

POST /dedicated_account

const dva = await paystackRequest<{
  bank: { name: string; slug: string };
  account_name: string;
  account_number: string;
  assigned: boolean;
  active: boolean;
}>("/dedicated_account", {
  method: "POST",
  body: JSON.stringify({
    customer: "CUS_dy1r7ts03zixbq5",
    preferred_bank: "wema-bank",
  }),
});
// dva.data.account_number → "9930000737"

Assign DVA (Create Customer + DVA)

POST /dedicated_account/assign — creates the customer, validates, and assigns a DVA in one step.

await paystackRequest("/dedicated_account/assign", {
  method: "POST",
  body: JSON.stringify({
    email: "janedoe@test.com",
    first_name: "Jane",
    last_name: "Doe",
    phone: "+2348100000000",
    preferred_bank: "wema-bank",
    country: "NG",
  }),
});
// Response: { status: true, message: "Assign dedicated account in progress" }

List Dedicated Accounts

GET /dedicated_account

const accounts = await paystackRequest("/dedicated_account?active=true&currency=NGN");

Fetch Dedicated Account

const account = await paystackRequest(`/dedicated_account/${dedicatedAccountId}`);

Requery for New Transactions

await paystackRequest(
  `/dedicated_account/requery?account_number=9930000737&provider_slug=wema-bank&date=2024-01-15`
);

Deactivate Dedicated Account

await paystackRequest(`/dedicated_account/${dedicatedAccountId}`, {
  method: "DELETE",
});

Split DVA Transactions

Add a split to DVA incoming payments:

await paystackRequest("/dedicated_account/split", {
  method: "POST",
  body: JSON.stringify({
    customer: "CUS_dy1r7ts03zixbq5",
    split_code: "SPL_e7jnRLtzla",
    // OR use subaccount instead of split_code:
    // subaccount: "ACCT_6uujpqtzmnufzkw",
  }),
});

Remove a split:

await paystackRequest("/dedicated_account/split", {
  method: "DELETE",
  body: JSON.stringify({
    account_number: "0033322211",
  }),
});

Full DVA Flow

// 1. Check available providers
const providers = await paystackRequest("/dedicated_account/available_providers");

// 2. Create customer first (or use existing)
const customer = await paystackRequest("/customer", {
  method: "POST",
  body: JSON.stringify({
    email: "user@example.com",
    first_name: "John",
    last_name: "Doe",
    phone: "+2348012345678",
  }),
});

// 3. Create DVA for the customer
const dva = await paystackRequest("/dedicated_account", {
  method: "POST",
  body: JSON.stringify({
    customer: customer.data.customer_code,
    preferred_bank: "wema-bank",
  }),
});

// 4. Display account details to user for bank transfer
console.log(`Pay to: ${dva.data.account_number} (${dva.data.bank.name})`);

// 5. Listen for charge.success webhook to confirm payment
// See paystack-webhooks skill for webhook handling