Dedicated Virtual Accounts

The Dedicated Virtual Account API enables Nigerian merchants to manage unique payment accounts of their customers.

Create Dedicated Virtual Account

Create a dedicated virtual account for an existing customer

We currently support Wema Bank and Titan Paystack.

Headers
authorization String	Set value to `Bearer SECRET_KEY`
content-type String	Set value to `application/json`

Body Parameters
Show optional parameters
customer String	Customer ID or code
preferred_bank String	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
subaccount String	Subaccount code of the account you want to split the transaction with
split_code String	Split code consisting of the lists of accounts you want to split the transaction with
first_name String	Customer's first name
last_name String	Customer's last name
phone String	Customer's phone number

1#!/bin/sh
2url="https://api.paystack.co/dedicated_account"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ "customer": 481193, 
6        "preferred_bank":"wema-bank"
7      }'
8
9curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "NUBAN successfully created",
4  "data": {
5    "bank": {
6      "name": "Wema Bank",
7      "id": 20,
8      "slug": "wema-bank"
9    },
10    "account_name": "KAROKART / RHODA CHURCH",
11    "account_number": "9930000737",
12    "assigned": true,
13    "currency": "NGN",
14    "metadata": null,
15    "active": true,
16    "id": 253,
17    "created_at": "2019-12-12T12:39:04.000Z",
18    "updated_at": "2020-01-06T15:51:24.000Z",
19    "assignment": {
20      "integration": 100043,
21      "assignee_id": 7454289,
22      "assignee_type": "Customer",
23      "expired": false,
24      "account_type": "PAY-WITH-TRANSFER-RECURRING",
25      "assigned_at": "2020-01-06T15:51:24.764Z"
26    },
27    "customer": {
28      "id": 7454289,
29      "first_name": "RHODA",
30      "last_name": "CHURCH",
31      "email": "rhodachurch@email.com",
32      "customer_code": "CUS_kpb3qj71u1m0rw8",
33      "phone": "+2349053267565",
34      "risk_action": "default"
35    }
36  }
37}

Assign Dedicated Virtual Account

With this endpoint, you can create a customer, validate the customer, and assign a DVA to the customer.

We currently support Wema Bank and Titan Paystack.

Headers
authorization String	Set value to `Bearer SECRET_KEY`
content-type String	Set value to `application/json`

Body Parameters
Show optional parameters
email String	Customer email address
first_name String	Customer's first name
last_name String	Customer's last name
phone String	Customer's phone number
preferred_bank String	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
country String	Currently accepts `NG` only
account_number String	Customer's account number
bvn String	Customer's Bank Verification Number
bank_code String	Customer's bank code
subaccount String	Subaccount code of the account you want to split the transaction with
split_code String	Split code consisting of the lists of accounts you want to split the transaction with

1#!/bin/sh
2url="https://api.paystack.co/dedicated_account"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6      "email": "janedoe@test.com",
7      "first_name": "Jane",
8      "middle_name": "Karen",
9      "last_name": "Doe",
10      "phone": "+2348100000000",
11      "preferred_bank": "test-bank",
12      "country": "NG"
13    }'
14
15curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Assign dedicated account in progress"
4}

List Dedicated Virtual Accounts

List dedicated virtual accounts available on your integration.

Headers
authorization String	Set value to `Bearer SECRET_KEY`

Query Parameters
Show optional parameters
active Boolean	Status of the dedicated virtual account
currency String	The currency of the dedicated virtual account. Only `NGN` is currently allowed
provider_slug String	The bank's slug in lowercase, without spaces e.g. `wema-bank`
bank_id String	The bank's ID e.g. `035`
customer String	The customer's ID

1#!/bin/sh
2url="https://api.paystack.co/dedicated_account"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET

1{
2  "status": true,
3  "message": "Managed accounts successfully retrieved",
4  "data": [
5    {
6      "customer": {
7        "id": 1530104,
8        "first_name": "yinka",
9        "last_name": "Ojo",
10        "email": "hello@company.co",
11        "customer_code": "CUS_dy1r7ts03zixbq5",
12        "phone": "08154239386",
13        "risk_action": "default",
14        "international_format_phone": null
15      },
16      "bank": {
17        "name": "Wema Bank",
18        "id": 20,
19        "slug": "wema-bank"
20      },
21      "id": 173,
22      "account_name": "KAROKART/A YINKA",
23      "account_number": "9930020212",
24      "created_at": "2019-12-09T13:31:38.000Z",
25      "updated_at": "2020-06-11T14:04:28.000Z",
26      "currency": "NGN",
27      "split_config": {
28        "subaccount": "ACCT_xdrne0tcvr5jkei"
29      },
30      "active": true,
31      "assigned": true
32    }
33  ],
34  "meta": {
35    "total": 1,
36    "skipped": 0,
37    "perPage": 50,
38    "page": 1,
39    "pageCount": 1
40  }
41}

Fetch Dedicated Virtual Account

Get details of a dedicated virtual account on your integration.

Headers
authorization String	Set value to `Bearer SECRET_KEY`

Path Parameters
dedicated_account_id Integer	ID of dedicated virtual account

1#!/bin/sh
2url="https://api.paystack.co/dedicated_account/:dedicated_account_id"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET

1{
2  "status": true,
3  "message": "Customer retrieved",
4  "data": {
5    "transactions": [],
6    "subscriptions": [],
7    "authorizations": [],
8    "first_name": null,
9    "last_name": null,
10    "email": "rhode@chu.com",
11    "phone": null,
12    "metadata": null,
13    "domain": "live",
14    "customer_code": "CUS_h00a7ngn0xbzf2g",
15    "risk_action": "default",
16    "id": 17593,
17    "integration": 190972,
18    "createdAt": "2019-10-25T15:05:23.000Z",
19    "updatedAt": "2019-10-25T15:05:23.000Z",
20    "created_at": "2019-10-25T15:05:23.000Z",
21    "updated_at": "2019-10-25T15:05:23.000Z",
22    "total_transactions": 0,
23    "total_transaction_value": [],
24    "dedicated_account": {
25      "id": 59,
26      "account_name": "KAROKART/RHODA CHURCH",
27      "account_number": "9807062474",
28      "created_at": "2019-09-10T11:10:12.000Z",
29      "updated_at": "2019-10-25T15:05:24.000Z",
30      "currency": "NGN",
31      "active": true,
32      "assigned": true,
33      "provider": {
34        "id": 1,
35        "provider_slug": "wema-bank",
36        "bank_id": 20,
37        "bank_name": "Wema Bank"
38      },
39      "assignment": {
40        "assignee_id": 17593,
41        "assignee_type": "Customer",
42        "account_type": "PAY-WITH-TRANSFER-RECURRING",
43        "integration": 190972
44      }
45    }
46  }
47}

Requery Dedicated Account

Requery Dedicated Virtual Account for new transactions

Headers
authorization String	Set value to `Bearer SECRET_KEY`

Query Parameters
Show optional parameters
account_number String	Virtual account number to requery
provider_slug String	The bank's slug in lowercase, without spaces e.g. `wema-bank`
date String	The day the transfer was made in `YYYY-MM-DD` format

1#!/bin/sh
2accountNumber="1234567890"
3providerSlug="example-provider"
4date="2023-05-30"
5
6url="https://api.paystack.co/dedicated_account/requery?account_number=$accountNumber&provider_slug=$providerSlug&date=$date"
7authorization="Authorization: Bearer YOUR_SECRET_KEY"
8content_type="Content-Type: application/json"
9
10curl "$url" -H "$authorization" -H "$content_type" -X GET

1{
2  "status": true,
3  "message": "We are checking the status of your transfer. We will send you a notification once it is confirmed"
4}

Deactivate Dedicated Account

Deactivate a dedicated virtual account on your integration.

Headers
authorization String	Set value to `Bearer SECRET_KEY`

Path Parameters
dedicated_account_id Integer	ID of dedicated virtual account

1#!/bin/sh
2url="https://api.paystack.co/dedicated_account/:dedicated_account_id"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X DELETE

1{
2  "status": true,
3  "message": "Managed Account Successfully Unassigned",
4  "data": {
5    "bank": {
6      "name": "Wema Bank",
7      "id": 20,
8      "slug": "wema-bank"
9    },
10    "account_name": "KAROKART/A YINKA",
11    "account_number": "9930020212",
12    "assigned": false,
13    "currency": "NGN",
14    "metadata": null,
15    "active": true,
16    "id": 173,
17    "created_at": "2019-12-09T13:31:38.000Z",
18    "updated_at": "2020-08-28T10:04:25.000Z",
19    "assignment": {
20      "assignee_id": 1530104,
21      "assignee_type": "Integration",
22      "assigned_at": "2019-12-09T13:40:21.000Z",
23      "integration": 100043,
24      "account_type": "PAY-WITH-TRANSFER-RECURRING"
25    }
26  }
27}

Split Dedicated Account Transaction

Split a dedicated virtual account transaction with one or more accounts

Headers
authorization String	Set value to `Bearer SECRET_KEY`
content-type String	Set value to `application/json`

Body Parameters
Show optional parameters
customer String	Customer ID or code
subaccount String	Subaccount code of the account you want to split the transaction with
split_code String	Split code consisting of the lists of accounts you want to split the transaction with
preferred_bank String	The bank slug for preferred bank. To get a list of available banks, use the List Providers endpoint

1#!/bin/sh
2url="https://api.paystack.co/dedicated_account"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ "customer": 481193, 
6        "preferred_bank":"wema-bank", 
7        "split_code": "SPL_e7jnRLtzla" 
8      }'
9
10curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Assigned Managed Account Successfully Created",
4  "data": {
5    "bank": {
6      "name": "Wema Bank",
7      "id": 20,
8      "slug": "wema-bank"
9    },
10    "account_name": "KAROKART/YINKA ADE",
11    "account_number": "6731105168",
12    "assigned": true,
13    "currency": "NGN",
14    "metadata": null,
15    "active": true,
16    "id": 97,
17    "created_at": "2019-11-13T13:52:39.000Z",
18    "updated_at": "2020-03-17T07:52:23.000Z",
19    "assignment": {
20      "integration": 100043,
21      "assignee_id": 17328,
22      "assignee_type": "Customer",
23      "expired": false,
24      "account_type": "PAY-WITH-TRANSFER-RECURRING",
25      "assigned_at": "2020-03-17T07:52:23.023Z",
26      "expired_at": null
27    },
28    "split_config": {
29      "split_code": "SPL_e7jnRLtzla"
30    },
31    "customer": {
32      "id": 17328,
33      "first_name": "YINKA",
34      "last_name": "ADE",
35      "email": "yinka@testemail.com",
36      "customer_code": "CUS_xxxxxxxx",
37      "phone": null,
38      "metadata": null,
39      "risk_action": "default"
40    }
41  }
42}

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

Headers
authorization String	Set value to `Bearer SECRET_KEY`
content-type String	Set value to `application/json`

Body Parameters
account_number String	Dedicated virtual account number

1#!/bin/sh
2url="https://api.paystack.co/dedicated_account/split"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{
6 "account_number": "0033322211" 
7}'
8
9curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X DELETE
10
11

1{
2  "status": "success",
3  "message": "Subaccount unassigned",
4  "data": {
5    "id": 22173,
6    "split_config": {},
7    "account_name": "KAROKART/YINKA ADE",
8    "account_number": "0033322211",
9    "currency": "NGN",
10    "assigned": true,
11    "active": true,
12    "createdAt": "2020-03-11T15:14:00.707Z",
13    "updatedAt": "2020-03-11T15:14:00.707Z"
14  }
15}

Fetch Bank Providers

Get available bank providers for a dedicated virtual account

Headers
authorization String	Set value to `Bearer SECRET_KEY`

1#!/bin/sh
2url="https://api.paystack.co/dedicated_account/available_providers"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET

1{
2  "status": true,
3  "message": "Dedicated account providers retrieved",
4  "data": [
5    {
6      "provider_slug": "access-bank",
7      "bank_id": 1,
8      "bank_name": "Access Bank",
9      "id": 6
10    },
11    {
12      "provider_slug": "wema-bank",
13      "bank_id": 20,
14      "bank_name": "Wema Bank",
15      "id": 5
16    }
17  ]
18}

Dedicated Virtual Accounts

Create Dedicated Virtual Account

Bank Availability

Assign Dedicated Virtual Account

Bank Availability

List Dedicated Virtual Accounts

Fetch Dedicated Virtual Account

Requery Dedicated Account

Deactivate Dedicated Account

Split Dedicated Account Transaction

Remove Split from Dedicated Account

Fetch Bank Providers