Sign in

Payments

Create and Assign Dedicated Virtual Accounts

View as Markdown

In a nutshell

How to create a customer-linked dedicated virtual account on Paystack.

Copy linkSet up webhook handling first

  1. Configure your webhook URL before creating live Dedicated Virtual Accounts (DVAs).
  2. Listen for charge.success so inbound transfers to the account can be recorded as completed payments.
  3. Also prepare to receive account-assignment events such as dedicatedaccount.assign.success, dedicatedaccount.assign.failed, and, where required, customer identification events.

Here's a sample charge.success authorization object for a payment into a DVA:

{
  "authorization": {
    "authorization_code": "AUTH_0ozsafcpdf",
    "channel": "dedicated_nuban",
    "card_type": "transfer",
    "bank": "Titan Paystack",
    "country_code": "NG",
    "brand": "Managed Account",
    "reusable": false,
    "sender_bank": "First City Monument Bank",
    "sender_bank_account_number": "XXXXXX0011",
    "sender_country": "NG",
    "sender_name": "JOHN DOE",
    "narration": "NIP: JOHN DOE -1123344343/44343231232",
    "receiver_bank_account_number": "9930000737",
    "receiver_bank": "Titan Paystack"
  }
}

Copy linkCreate or update the customer

  1. Create the customer record with email, first_name, last_name, and phone.
  2. If the customer already exists, make sure those fields are present before you assign the account.
  3. Update the customer first if any of those identity details are missing.

Copy linkValidate the customer where compliance requires it

  1. Check whether your business category requires identity validation.
  2. Collect customer consent before using personal data for DVA assignment.
For businesses in the Betting, Financial Services, or General Services categories, validate the customer's identity before generating the account.

There are two ways to assign a DVA to a customer: a multi-step flow where you control each stage yourself, or a single-step flow where Paystack creates the customer, runs any required validation, and assigns the DVA in one request.

Copy linkCreate the DVA (multi-step)

Call the DVA creation endpoint with the customer's code and preferred provider:

POSTapi.paystack.co/dedicated_account

curl https://api.paystack.co/dedicated_account \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "CUS_358xertt55",
    "preferred_bank": "titan-paystack"
  }'
const response = await fetch('https://api.paystack.co/dedicated_account', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_SECRET_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customer: 'CUS_358xertt55',
    preferred_bank: 'titan-paystack'
  })
})

const data = await response.json()
console.log(data)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.paystack.co/dedicated_account",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    "customer" => "CUS_358xertt55",
    "preferred_bank" => "titan-paystack"
  ]),
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer YOUR_SECRET_KEY",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
{
  "status": true,
  "message": "NUBAN successfully created",
  "data": {
    "bank": {
      "name": "Titan Paystack",
      "id": 20,
      "slug": "titan-paystack"
    },
    "account_name": "PAYSTACK/RHODA CHURCH",
    "account_number": "9930000737",
    "assigned": true,
    "currency": "NGN",
    "metadata": null,
    "active": true,
    "id": 253,
    "created_at": "2019-12-12T12:39:04.000Z",
    "updated_at": "2020-01-06T15:51:24.000Z",
    "assignment": {
      "integration": 100043,
      "assignee_id": 7454289,
      "assignee_type": "Customer",
      "expired": false,
      "account_type": "PAY-WITH-TRANSFER-RECURRING",
      "assigned_at": "2020-01-06T15:51:24.764Z"
    },
    "customer": {
      "id": 7454289,
      "first_name": "Rhoda",
      "last_name": "Church",
      "email": "[email protected]",
      "customer_code": "CUS_kpb3qj71u1m0rw8",
      "phone": "+2349053267565",
      "risk_action": "default"
    }
  }
}
For test mode, use `test-bank` as `preferred_bank` when creating a test DVA.

Supported providers

Use the Fetch Providers endpoint to confirm the providers currently available on your account before setting preferred_bank.

Copy linkAssign a DVA in one step (single-step)

Copy linkRequired compliance

If your business category requires identity validation, include the customer's bank account and identification details in the same request:

POSTapi.paystack.co/dedicated_account/assign

curl https://api.paystack.co/dedicated_account/assign \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+2348100000000",
    "preferred_bank": "titan-paystack",
    "country": "NG",
    "account_number": "0123456789",
    "bvn": "20012345678",
    "bank_code": "007"
  }'
const response = await fetch('https://api.paystack.co/dedicated_account/assign', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_SECRET_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: '[email protected]',
    first_name: 'Jane',
    last_name: 'Doe',
    phone: '+2348100000000',
    preferred_bank: 'titan-paystack',
    country: 'NG',
    account_number: '0123456789',
    bvn: '20012345678',
    bank_code: '007'
  })
})

const data = await response.json()
console.log(data)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.paystack.co/dedicated_account/assign",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    "email" => "[email protected]",
    "first_name" => "Jane",
    "last_name" => "Doe",
    "phone" => "+2348100000000",
    "preferred_bank" => "titan-paystack",
    "country" => "NG",
    "account_number" => "0123456789",
    "bvn" => "20012345678",
    "bank_code" => "007"
  ]),
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer YOUR_SECRET_KEY",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
{
  "status": true,
  "message": "Assign dedicated account in progress"
}

This triggers a customer identification step before the account is assigned. You'll receive a customeridentification.success or customeridentification.failed event first:

{
  "event": "customeridentification.success",
  "data": {
    "customer_id": 9387490384,
    "customer_code": "CUS_xnxdt6s1zg1f4nx",
    "email": "[email protected]",
    "identification": {
      "country": "NG",
      "type": "bvn",
      "value": "200*****677"
    }
  }
}
{
  "event": "customeridentification.failed",
  "data": {
    "customer_id": 82796315,
    "customer_code": "CUS_xxxxxxxxxxxxxxx",
    "email": "[email protected]",
    "identification": {
      "country": "NG",
      "type": "bank_account",
      "bvn": "123*****456",
      "account_number": "012****345",
      "bank_code": "999991"
    },
    "reason": "Account number or BVN is incorrect"
  }
}

Copy linkOptional compliance

If your business category doesn't require identity validation, pass only the customer's details and preferred provider:

POSTapi.paystack.co/dedicated_account/assign

curl https://api.paystack.co/dedicated_account/assign \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+2348100000000",
    "preferred_bank": "titan-paystack",
    "country": "NG"
  }'
const response = await fetch('https://api.paystack.co/dedicated_account/assign', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_SECRET_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: '[email protected]',
    first_name: 'Jane',
    last_name: 'Doe',
    phone: '+2348100000000',
    preferred_bank: 'titan-paystack',
    country: 'NG'
  })
})

const data = await response.json()
console.log(data)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.paystack.co/dedicated_account/assign",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    "email" => "[email protected]",
    "first_name" => "Jane",
    "last_name" => "Doe",
    "phone" => "+2348100000000",
    "preferred_bank" => "titan-paystack",
    "country" => "NG"
  ]),
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer YOUR_SECRET_KEY",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
{
  "status": true,
  "message": "Assign dedicated account in progress"
}

Copy linkWait for assignment events

  1. Treat the response as the start of an asynchronous process.
  2. Wait for the relevant success event before marking the DVA as active in your system.
  3. Handle failure events by keeping the customer record unassigned and surfacing the reason internally.
{
  "event": "dedicatedaccount.assign.success",
  "data": {
    "customer": {
      "id": 100110,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]",
      "customer_code": "CUS_hp05n9khsqcesz2",
      "phone": "+2348100000000",
      "metadata": {},
      "risk_action": "default"
    },
    "dedicated_account": {
      "bank": {
        "name": "Titan Paystack",
        "id": 20,
        "slug": "titan-paystack"
      },
      "account_name": "PAYSTACK/JANE DOE",
      "account_number": "1234567890",
      "assigned": true,
      "currency": "NGN",
      "active": true,
      "id": 987654,
      "assignment": {
        "integration": 100123,
        "assignee_id": 100110,
        "assignee_type": "Customer",
        "expired": false,
        "account_type": "PAY-WITH-TRANSFER-RECURRING",
        "assigned_at": "2022-08-12T14:02:51.614Z"
      }
    },
    "identification": {
      "status": "success"
    }
  }
}
{
  "event": "dedicatedaccount.assign.failed",
  "data": {
    "customer": {
      "id": 100110,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]",
      "customer_code": "CUS_hcekca0j0bbg2m4",
      "phone": "+2348100000000",
      "metadata": {},
      "risk_action": "default"
    },
    "dedicated_account": null,
    "identification": {
      "status": "failed"
    }
  }
}

Copy linkStore the assigned account details

  1. Save the DVA information against the customer record after assignment succeeds.
  2. Use the returned account details as the customer's reusable transfer destination.
  3. Expect future transfers into that account to be attributed automatically to the same customer.

You can also retrieve a customer's DVA later by calling Fetch Customer and reading the dedicated_account object from the response:

{
  "status": true,
  "message": "Customer retrieved",
  "data": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "+2348100000000",
    "customer_code": "CUS_358xertt55",
    "dedicated_account": {
      "bank": {
        "name": "Titan Paystack",
        "id": 20,
        "slug": "titan-paystack"
      },
      "id": 173,
      "account_name": "PAYSTACK/JANE DOE",
      "account_number": "9930000737",
      "currency": "NGN",
      "active": true,
      "assigned": true,
      "assignment": {
        "assignee_id": 1530104,
        "assignee_type": "Customer",
        "account_type": "PAY-WITH-TRANSFER-RECURRING",
        "integration": 100043
      }
    }
  }
}

Copy linkRequery only when necessary

  1. Requery the DVA when a customer says they transferred but your system has not yet received the transaction.
  2. Wait at least 10 minutes between requery attempts for the same account.

GETapi.paystack.co/dedicated_account/requery

curl "https://api.paystack.co/dedicated_account/requery?account_number=9930000737&provider_slug=titan-paystack&date=2024-06-01" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
const response = await fetch('https://api.paystack.co/dedicated_account/requery?account_number=9930000737&provider_slug=titan-paystack&date=2024-06-01', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_SECRET_KEY'
  }
})

const data = await response.json()
console.log(data)
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.paystack.co/dedicated_account/requery?account_number=9930000737&provider_slug=titan-paystack&date=2024-06-01",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer YOUR_SECRET_KEY"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
{
  "status": true,
  "message": "We are checking the status of your transfer. We will send you a notification once it is confirmed"
}

Rate limit

You can only requery a DVA once every 10 minutes. Requests within that window are not processed.

Was this page helpful?