Payments
Create and Assign Dedicated Virtual Accounts
In a nutshell
How to create a customer-linked dedicated virtual account on Paystack in Ghana.
Copy linkSet up webhook handling first
- Configure your webhook URL before creating live Dedicated Virtual Accounts (DVAs).
- Listen for
charge.successso inbound transfers to the account can be recorded as completed payments. - 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
- Create the customer record with
email,first_name,last_name, andphone. - If the customer already exists, make sure those fields are present before you assign the account.
- Update the customer first if any of those identity details are missing.
Copy linkValidate the customer where compliance requires it
- Check whether your business category requires identity validation.
- Collect customer consent before using personal data for DVA assignment.
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/AMA MENSAH",
"account_number": "9930000737",
"assigned": true,
"currency": "GHS",
"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": "Ama",
"last_name": "Mensah",
"email": "[email protected]",
"customer_code": "CUS_kpb3qj71u1m0rw8",
"phone": "+233541234567",
"risk_action": "default"
}
}
}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
- Treat the response as the start of an asynchronous process.
- Wait for the relevant success event before marking the DVA as active in your system.
- 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
- Save the DVA information against the customer record after assignment succeeds.
- Use the returned account details as the customer's reusable transfer destination.
- 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": "Ama",
"last_name": "Mensah",
"email": "[email protected]",
"phone": "+233541234567",
"customer_code": "CUS_358xertt55",
"dedicated_account": {
"bank": {
"name": "Titan Paystack",
"id": 20,
"slug": "titan-paystack"
},
"id": 173,
"account_name": "PAYSTACK/AMA MENSAH",
"account_number": "9930000737",
"currency": "GHS",
"active": true,
"assigned": true,
"assignment": {
"assignee_id": 1530104,
"assignee_type": "Customer",
"account_type": "PAY-WITH-TRANSFER-RECURRING",
"integration": 100043
}
}
}
}Copy linkRequery only when necessary
- Requery the DVA when a customer says they transferred but your system has not yet received the transaction.
- 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.