Dedicated Virtual Account
A collection of endpoints for creating and managing payment accounts for customers
Copy link List Dedicated Accounts
List dedicated virtual accounts available on your integration.
Query Parameters
Status of the dedicated virtual account
The customer's ID
The currency of the dedicated virtual account
EnumNGNGHS
The bank's slug in lowercase, without spaces
The bank's ID
The number of records to fetch per request
The offset to retrieve data from
Response
200
5 object properties
GET
/dedicated_accountcurl https://api.paystack.co/dedicated_account \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dedicatedVirtualAccount.dedicatedAccountList({
active: true,
customer: 297346561
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dedicated_virtual_account.dedicated_account_list({
active: true,
customer: 297346561
})
puts response.dataResponse
{
"status": true,
"message": "Managed accounts successfully retrieved",
"data": [
{
"customer": {
"id": 1530104,
"first_name": "yinka",
"last_name": "Ojo",
"email": "[email protected]",
"customer_code": "CUS_dy1r7ts03zixbq5",
"phone": "+2348123456789",
"risk_action": "default",
"international_format_phone": null
},
"bank": {
"name": "Paystack-Titan",
"id": 629,
"slug": "titan-paystack"
},
"id": 173,
"account_name": "KAROKART/A YINKA",
"account_number": "9930020212",
"created_at": "2019-12-09T13:31:38.000Z",
"updated_at": "2020-06-11T14:04:28.000Z",
"currency": "NGN",
"split_config": {
"subaccount": "ACCT_xdrne0tcvr5jkei"
},
"active": true,
"assigned": true
}
],
"meta": {
"total": 1,
"skipped": 0,
"perPage": 50,
"page": 1,
"pageCount": 1
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Create Dedicated Account
Create a dedicated virtual account for an existing customer
Request Body
The code for the previously created customer
The bank slug for preferred bank. To get a list of available banks, use the List Providers endpoint
Subaccount code of the account you want to split the transaction with
Split code consisting of the lists of accounts you want to split the transaction with
Response
200
12 object properties
3 object properties
7 object properties
9 object properties
POST
/dedicated_accountcurl https://api.paystack.co/dedicated_account \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer": "CUS_bo732eugpb2qrg6"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dedicatedVirtualAccount.dedicatedAccountCreate({
customer: "CUS_bo732eugpb2qrg6"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dedicated_virtual_account.dedicated_account_create({
customer: "CUS_bo732eugpb2qrg6"
})
puts response.dataResponse
{
"status": true,
"message": "NUBAN successfully created",
"data": {
"bank": {
"name": "Paystack-Titan",
"id": 629,
"slug": "titan-paystack"
},
"account_name": "KAROKART / 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": "+2348123456789",
"risk_action": "default"
}
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Assign Dedicated Account
With this endpoint, you can create a customer, validate the customer, and assign a DVA to the customer.
Request Body
Customer's email address
Customer's first name
Customer's last name
Customer's phone name
The bank slug for preferred bank. To get a list of available banks,
use the List Banks endpoint, passing `pay_with_bank_transfer=true` query parameter
The two letter code country
EnumNGGH
Customer's account number
Customer's Bank Verification Number
Customer's bank code
Subaccount code of the account you want to split the transaction with
Split code consisting of the lists of accounts you want to split the transaction with
Response
200Request successful
POST
/dedicated_account/assigncurl 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": "+2348123456789",
"preferred_bank": "titan-paystack",
"country": "NG"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dedicatedVirtualAccount.dedicatedAccountAssign({
email: "[email protected]",
first_name: "Jane",
last_name: "Doe",
phone: "+2348123456789",
preferred_bank: "titan-paystack",
country: "NG"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dedicated_virtual_account.dedicated_account_assign({
email: "[email protected]",
first_name: "Jane",
last_name: "Doe",
phone: "+2348123456789",
preferred_bank: "titan-paystack",
country: "NG"
})
puts response.dataResponse
{
"status": true,
"message": "Assign dedicated account in progress"
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Fetch Dedicated Account
Get details of a dedicated virtual account on your integration.
Path Parameters
ID of dedicated virtual account
Response
200
11 object properties
9 object properties
3 object properties
GET
/dedicated_account/{id}curl https://api.paystack.co/dedicated_account/DEDICATED_VIRTUAL_ACCOUNT_ID \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dedicatedVirtualAccount.dedicatedAccountFetch("DEDICATED_VIRTUAL_ACCOUNT_ID");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dedicated_virtual_account.dedicated_account_fetch("DEDICATED_VIRTUAL_ACCOUNT_ID")
puts response.dataResponse
{
"status": true,
"message": "Managed account successfully retrieved",
"data": {
"customer": {
"id": 42200598,
"first_name": "Rose",
"last_name": "Sharon",
"email": "[email protected]",
"customer_code": "CUS_lfq5hi7rsnub7gl",
"phone": "+2348123456789",
"metadata": {
"calling_code": "+234"
},
"risk_action": "default",
"international_format_phone": null
},
"bank": {
"name": "Paystack-Titan",
"id": 629,
"slug": "titan-paystack"
},
"id": 1234553,
"account_name": "BOOMBOOMINDUS/Sharon Rose",
"account_number": "1234709987",
"created_at": "2021-02-13T00:29:50.000Z",
"updated_at": "2021-03-30T10:03:54.000Z",
"currency": "NGN",
"split_config": "{\"subaccount\":\"ACCT_f651f39t7x9a9c6\"}",
"active": true,
"assigned": true
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Deactivate Dedicated Account
Deactivate a dedicated virtual account on your integration.
Path Parameters
ID of dedicated virtual account
Response
200
11 object properties
3 object properties
5 object properties
DELETE
/dedicated_account/{id}curl https://api.paystack.co/dedicated_account/DEDICATED_VIRTUAL_ACCOUNT_ID \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-X DELETEimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dedicatedVirtualAccount.dedicatedAccountDeactivate("DEDICATED_VIRTUAL_ACCOUNT_ID");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dedicated_virtual_account.dedicated_account_deactivate("DEDICATED_VIRTUAL_ACCOUNT_ID")
puts response.dataResponse
{
"status": true,
"message": "Managed Account Successfully Unassigned",
"data": {
"bank": {
"name": "Paystack-Titan",
"id": 629,
"slug": "titan-paystack"
},
"account_name": "KAROKART/A YINKA",
"account_number": "9930020212",
"assigned": false,
"currency": "NGN",
"metadata": null,
"active": true,
"id": 173,
"created_at": "2019-12-09T13:31:38.000Z",
"updated_at": "2020-08-28T10:04:25.000Z",
"assignment": {
"assignee_id": 1530104,
"assignee_type": "Integration",
"assigned_at": "2019-12-09T13:40:21.000Z",
"integration": 100043,
"account_type": "PAY-WITH-TRANSFER-RECURRING"
}
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Requery Dedicated Account
Requery Dedicated Virtual Account for new transactions
Query Parameters
Virtual account number to requery
The bank's slug in lowercase, without spaces.
The day the transfer was made
Response
200Request successful
GET
/dedicated_account/requerycurl https://api.paystack.co/dedicated_account/requery \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dedicatedVirtualAccount.dedicatedAccountRequery({
account_number: "0033322211",
provider_slug: "titan-paystack"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dedicated_virtual_account.dedicated_account_requery({
account_number: "0033322211",
provider_slug: "titan-paystack"
})
puts response.dataResponse
{
"status": true,
"message": "We are checking the status of your transfer. We will send you a notification once it is confirmed"
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Split Dedicated Account Transaction
Split a dedicated virtual account transaction with one or more accounts
Request Body
Valid Dedicated virtual account
Subaccount code of the account you want to split the transaction with
Split code consisting of the lists of accounts you want to split the transaction with
Response
200Request successful
POST
/dedicated_account/splitcurl https://api.paystack.co/dedicated_account/split \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"account_number": "0033322211"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dedicatedVirtualAccount.dedicatedAccountAddSplit({
account_number: "0033322211"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dedicated_virtual_account.dedicated_account_add_split({
account_number: "0033322211"
})
puts response.dataResponse
{
"status": true,
"message": "Request successful",
"data": {}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Remove Split from Dedicated Account
If you've previously set up split payment for transactions on a dedicated virtual account, you can remove it with this endpoint
Request Body
Valid Dedicated virtual account
Response
200Request successful
DELETE
/dedicated_account/splitcurl https://api.paystack.co/dedicated_account/split \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"account_number": "0033322211"
}' \
-X DELETEimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dedicatedVirtualAccount.dedicatedAccountRemoveSplit({
account_number: "0033322211"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dedicated_virtual_account.dedicated_account_remove_split({
account_number: "0033322211"
})
puts response.dataResponse
{
"status": "success",
"message": "Subaccount unassigned",
"data": {
"id": 22173,
"split_config": {},
"account_name": "KAROKART/YINKA ADE",
"account_number": "0033322211",
"currency": "NGN",
"assigned": true,
"active": true,
"createdAt": "2020-03-11T15:14:00.707Z",
"updatedAt": "2020-03-11T15:14:00.707Z"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Fetch Bank Providers
Get available bank providers for a dedicated virtual account
Response
200Request successful
GET
/dedicated_account/available_providerscurl https://api.paystack.co/dedicated_account/available_providers \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.dedicatedVirtualAccount.dedicatedAccountAvailableProviders();
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.dedicated_virtual_account.dedicated_account_available_providers()
puts response.dataResponse
{
"status": true,
"message": "Dedicated account providers retrieved",
"data": [
{
"provider_slug": "titan-paystack",
"bank_id": 629,
"bank_name": "Paystack-Titan",
"id": 9
},
{
"provider_slug": "wema-bank",
"bank_id": 20,
"bank_name": "Wema Bank",
"id": 5
}
]
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}