Dedicated Accounts API

Dedicated Virtual Accounts (DVA) allow you to assign permanent bank account numbers to your customers for receiving payments.

Dedicated Virtual Accounts API https://paystack.com/docs/api/dedicated-virtual-account/

class djpaystack.api.dedicated_accounts.DedicatedAccountAPI(client)

Bases: BaseAPI

Paystack Dedicated Virtual Accounts API

Create and manage bank accounts for your customers. Bank transfers to these accounts are automatically recorded as transactions from that customer. Available to registered businesses in Nigeria and Ghana.

create(customer: str, preferred_bank: str | None = None, subaccount: str | None = None, split_code: str | None = None, first_name: str | None = None, last_name: str | None = None, phone: str | None = None) → Dict[str, Any]

Create a dedicated virtual account (multi-step flow).

The customer must already exist. For Nigerian businesses in Betting/Financial/General services categories, the customer must be validated first.

Parameters:

• customer – Customer ID or code

• preferred_bank – Bank slug (e.g. ‘wema-bank’, ‘titan-paystack’, ‘test-bank’)

• subaccount – Subaccount code for split payments

• split_code – Split code for multi-split payments

• first_name – Customer’s first name

• last_name – Customer’s last name

• phone – Customer’s phone number

Returns:

Dedicated account details

assign(email: str, first_name: str, last_name: str, phone: str, preferred_bank: str, country: str = 'NG', middle_name: str | None = None, account_number: str | None = None, bvn: str | None = None, bank_code: str | None = None, subaccount: str | None = None, split_code: str | None = None) → Dict[str, Any]

Create and assign a dedicated virtual account in a single step.

Handles customer creation, optional validation, and DVA assignment. For businesses in Betting/Financial/General services categories, account_number, bvn, and bank_code are required for compliance.

Parameters:

• email – Customer’s email address

• first_name – Customer’s first name

• last_name – Customer’s last name

• phone – Customer’s phone number

• preferred_bank – Bank slug (e.g. ‘wema-bank’, ‘titan-paystack’, ‘test-bank’)

• country – Customer’s country (default: ‘NG’)

• middle_name – Customer’s middle name

• account_number – Customer’s bank account number (compliance)

• bvn – Customer’s BVN (compliance)

• bank_code – Customer’s bank code (compliance)

• subaccount – Subaccount code for split payments

• split_code – Split code for multi-split payments

Returns:

Assignment response (listen for dedicatedaccount.assign.success webhook)

list(active: bool | None = None, currency: str | None = None, per_page: int = 50, page: int | None = None) → Dict[str, Any]

List dedicated accounts

fetch(dedicated_account_id: str) → Dict[str, Any]

Fetch dedicated account

requery(account_number: str, provider_slug: str, date: str | None = None) → Dict[str, Any]

Requery a dedicated account for pending transactions.

Rate limited to once every 10 minutes per account.

Parameters:

• account_number – Virtual account number

• provider_slug – Provider slug

• date – Date to check in YYYY-MM-DD format

Returns:

Requery response

deactivate(dedicated_account_id: str) → Dict[str, Any]

Deactivate dedicated account

split(account_number: str, subaccount: str | None = None, split_code: str | None = None) → Dict[str, Any]

Add or update a subaccount/split on an existing dedicated virtual account.

Parameters:

• account_number – The dedicated virtual account number

• subaccount – Subaccount code for split payments

• split_code – Split code for multi-split payments

Returns:

Updated split configuration

remove_split(account_number: str) → Dict[str, Any]

Remove split from dedicated account

available_providers() → Dict[str, Any]

Get available dedicated account providers (banks)

Quick Reference

from djpaystack import PaystackClient
client = PaystackClient()

# Single-step assignment (create customer + assign account)
client.dedicated_accounts.assign(
    email='customer@example.com',
    first_name='John',
    last_name='Doe',
    phone='+2348012345678',
    preferred_bank='wema-bank',
)

# Create DVA for existing customer
client.dedicated_accounts.create(customer='CUS_xxxxx', preferred_bank='wema-bank')

# List / Fetch
client.dedicated_accounts.list()
client.dedicated_accounts.fetch(dedicated_account_id=123)

# Requery for recent transactions
client.dedicated_accounts.requery(account_number='1234567890', provider_slug='wema-bank')

# Split DVA payments
client.dedicated_accounts.split(
    account_number='1234567890',
    subaccount='ACCT_xxxxx',
    split_code='SPL_xxxxx',
)

# Remove split
client.dedicated_accounts.remove_split(account_number='1234567890')

# Deactivate
client.dedicated_accounts.deactivate(dedicated_account_id=123)

Webhook Events

• dedicatedaccount.assign.success — DVA assigned successfully

• dedicatedaccount.assign.failed — DVA assignment failed