rexedge/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

| Method | Endpoint | Description | | --- | --- | --- | | POST | /dedicated_account | Create DVA for existing customer | | POST | /dedicated_account/assign | Create customer + assign DVA in one step | | GET | /dedicated_account | List dedicated accounts | | GET | /dedicated_account/:id | Fetch a dedicated account | | GET | /dedicated_account/requery | Requery for new transactions | | DELETE | /dedicated_account/:id | Deactivate a dedicated account | | POST | /dedicated_account/split | Add split to DVA transactions | | DELETE | /dedicated_account/split | Remove split from DVA | | GET | /dedicated_account/available_providers | List available bank providers |

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

| Param | Type | Required | Description | | --- | --- | --- | --- | | customer | string | Yes | Customer ID or code | | preferred_bank | string | No | Bank slug (e.g. wema-bank, access-bank) | | subaccount | string | No | Subaccount code for split payments | | split_code | string | No | Split code for multi-party splits | | first_name | string | No | Customer first name | | last_name | string | No | Customer last name | | phone | string | No | Customer phone number |

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.

| Param | Type | Required | Description | | --- | --- | --- | --- | | email | string | Yes | Customer email | | first_name | string | Yes | First name | | last_name | string | Yes | Last name | | phone | string | Yes | Phone number | | preferred_bank | string | Yes | Bank slug | | country | string | Yes | NG or GH | | account_number | string | No | Customer's account number | | bvn | string | No | Bank Verification Number (Nigeria) | | bank_code | string | No | Customer's bank code | | subaccount | string | No | Subaccount code for split | | split_code | string | No | Split code for multi-party split |

await paystackRequest("/dedicated_account/assign", {
  method: "POST",
  body: JSON.stringify({
    email: "[email protected]",
    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

| Param | Type | Required | Description | | --- | --- | --- | --- | | active | boolean | No | Filter by active status | | currency | string | No | NGN or GHS | | provider_slug | string | No | Bank slug filter | | bank_id | string | No | Bank ID filter | | customer | string | No | Customer ID filter |

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: "[email protected]",
    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