Dedicated Virtual Accounts
Learn how to create virtual accounts for your customers to pay you with.
Feature Availability
Introduction
Dedicated Virtual Accounts is a feature on the Paystack Dashboard and API that lets you create dedicated Nigerian bank accounts for your customers to pay you with.
When you create a dedicated virtual account for a customer, all bank transfers to that account will automatically be recorded as transactions from that customer.
To assign a dedicated virtual account to a customer, you need to:
Create a customer
A dedicated virtual account is tied to a customer so you need to create a customer by passing the email
, first_name
, last_name
and phone
to the Create customerAPI.
If the customer already exists on your platform, kindly ensure the customer's first_name
, last_name
and phone
are set. This is because we need the customer's details to create a bank account. For customers created without these details, you can update the customer record by passing first_name
, last_name
and phone
when creating the virtual account with Β Create Dedicated Virtual AccountAPI
Set up webhooks
Bank transfers happen from external sources and we only get notified after the transfer is complete. The only way to know when a payment has been done is through webhooks.
The charge.success
webhook event lets you know when you've received a bank transfer payment.
Here's a sample authorization object in the charge.success
event for a dedicated virtual account payment:
- JSON
1{2 ...3 "authorization": {4 "authorization_code": "AUTH_0ozsafcpdf",5 "bin": "413XXX",6 "last4": "X011",7 "exp_month": "01",8 "exp_year": "2020",9 "channel": "dedicated_nuban",10 "card_type": "transfer",11 "bank": "First City Monument Bank",12 "country_code": "NG",13 "brand": "Managed Account",14 "reusable": false,15 "signature": null,16 "sender_bank": "First City Monument Bank",17 "sender_bank_account_number": "XXXXXX0011",18 "sender_country": "NG",19 "sender_name": "RANDALL AKANBI HORTON",20 "narration": "NIP: RHODA CHURCH -1123344343/44343231232",21 "receiver_bank_account_number": "9930000902",22 "receiver_bank": "Wema Bank"23 },24 ...25 }
Validate a customer
For compliance reasons, businesses that offer their services under the business categories - Betting, Financial services, and General services can only generate bank account numbers for customers whose personal identity information has been validated. This information is then used in naming the bank account number. Here's how to validate a customer's identity.
Get Customer's Consent
Create a dedicated virtual account
To create a dedicated virtual account for a customer, send a POST
request to ourΒ Create Dedicated Virtual AccountAPI.
Supported banks
1curl https://api.paystack.co/dedicated_account2-H "Authorization: Bearer YOUR_SECRET_KEY"3-H "Content-Type: application/json"4-d '{ "customer": "CUS_358xertt55", "preferred_bank": "access-bank"}'5-X POST
1{2 "status": true,3 "message": "NUBAN successfully created",4 "data": {5 "bank": {6 "name": "Access Bank",7 "id": 1,8 "slug": "access-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",32 "customer_code": "CUS_kpb3qj71u1m0rw8",33 "phone": "+2349053267565",34 "risk_action": "default"35 }36 }37 }
Account naming
When the customer attempts to make a transfer to the created account number, the account name would be in the format:
- Access Bank - Product Name Customer Name.
- Wema Bank - Product Name / Customer Name.
Account Limit
Testing Dedicated Virtual Accounts
test-bank
as the preferred_bank
in the request body parameters. You can also make a transfer to the test virtual accounts using our demo bank app.Get a customer's dedicated virtual account
If you want to retrieve a customer's dedicated virtual account, call the Fetch CustomerAPI endpoint. You can retrieve the dedicated virtual account from the dedicated_account
object in the response:
- JSON
1{2 "status": true,3 "message": "Customer retrieved",4 "data": {5 "transactions": [],6 "subscriptions": [],7 "authorizations": [],8 "first_name": "Rhoda",9 "last_name": "Church",11 "phone": "08154211006",12 "domain": "live",13 "customer_code": "CUS_dy1r7ts03zstbq5",14 ...15 "dedicated_account": {16 "bank": {17 "name": "Wema Bank",18 "id": 20,19 "slug": "wema-bank"20 },21 "id": 173,22 "account_name": "KAROKART/RHODA CHURCH",23 "account_number": "9930020212",24 "created_at": "2019-12-09T13:31:38.000Z",25 "updated_at": "2019-12-09T16:04:25.000Z",26 "currency": "NGN",27 "active": true,28 "assigned": true,29 "assignment": {30 "assignee_id": 1530104,31 "assignee_type": "Integration",32 "account_type": "PAY-WITH-TRANSFER-RECURRING",33 "integration": 10004334 }35 }36 }37}
Requery a customer's dedicated virtual account
When a customer makes a transfer to a dedicated virtual account, a transaction is automatically created for the customer, and a webhook is sent to your server to notify you of the transaction. This typically happens within a few minutes.
However, in some cases, the notification could take longer to come in. When this happens, the customer might reach out to you that their account/wallet hasn't been credited, or they would try to refresh their balance in your application.
In this scenario, you can use the Requery Dedicated Virtual AccountAPI endpoint to check the virtual account for new transactions that haven't been processed yet. Calling this endpoint will trigger a background requery process, and if any pending transactions are found, the transaction will be created, and the webhook notification will be sent to your server.
1curl https://api.paystack.co/dedicated_account/requery?account_number={accountNumber}&provider_slug={provider_slug}&date={yyyy-mm-dd}2-H "Authorization: Bearer YOUR_SECRET_KEY"3-H "Content-Type: application/json"4-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}
Rate Limit
Split payment on dedicated virtual account
Split payment for dedicated virtual allows you to automatically split funds received into a dedicated virtual account between your main settlement bank account and one or more bank account(s).
Prerequisite
There are two ways to add split payment on dedicated virtual account:
- Add a subaccount when creating a dedicated virtual account
- Add a subaccount to an existing dedicated virtual account
For multi-split payment on dedicated virtual account:
- Add a split code when creating a dedicated virtual account
- Add a split code to an existing dedicated virtual account
Add a subaccount when creating a dedicated virtual account
You can add a subaccount code to the payload when you create a dedicated virtual account for the customer
1curl https://api.paystack.co/dedicated_account2-H "Authorization: Bearer YOUR_SECRET_KEY"3-H "Content-Type: application/json"4-d '{ "customer": 481193, "preferred_bank":"wema-bank",5 "subaccount": "SUB_ACCOUNTCODE"6 }'7-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": null27 },28 "split_config": {"subaccount":"ACC_qwerty"},29 "customer": {30 "id": 17328,31 "first_name": "YINKA",32 "last_name": "ADE",34 "customer_code": "CUS_xxxxxxxx",35 "phone": null,36 "metadata": null,37 "risk_action": "default"38 }39 }40 }
Add a subaccount to an existing dedicated virtual account
When updating an already existing dedicated virtual account, you can pass a subaccount code as one of the parameters.
1curl https://api.paystack.co/dedicated_account/split2-H "Authorization: Bearer YOUR_SECRET_KEY"3-H "Content-Type: application/json"4-d '{ "account_number": "0033322211", "subaccount": "SUB_ACCOUNTCODE" }'5-X POST
1{2 "status": true,3 "message": "Subaccount assigned",4 "data": {5 "id": 22495,6 "account_name": "KAROKART/YINKA ADE",7 "account_number": "0033322211",8 "assigned": 1,9 "currency": "NGN",10 "metadata": null,11 "active": 1,12 "last_assignment_id": 525,13 "createdAt": "2020-03-20T11:03:43.000Z",14 "updatedAt": "2020-03-20T11:03:43.000Z",15 "assignment_id": 525,16 "split_config": {17 "subaccount":"ACCT_4r33icuptxl40vv"18 }19 }20}
Updating existing subaccount on a dedicated virtual account
Add a split code when creating a dedicated virtual account
You can add a split code to the payload when you create a dedicated virtual account for the customer
1curl https://api.paystack.co/dedicated_account2-H "Authorization: Bearer YOUR_SECRET_KEY"3-H "Content-Type: application/json"4-d '{ "customer": 481193, "preferred_bank":"wema-bank",5 "split_code": "SPL_e7jnRLtzla"6 }'7-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": null27 },28 "split_config": {"split_code":"SPL_e7jnRLtzla"},29 "customer": {30 "id": 17328,31 "first_name": "YINKA",32 "last_name": "ADE",34 "customer_code": "CUS_xxxxxxxx",35 "phone": null,36 "metadata": null,37 "risk_action": "default"38 }39 }40 }
Add a split code to an existing dedicated virtual account
When updating an already existing dedicated virtual account, you can pass a split code as one of the parameters.
1curl https://api.paystack.co/dedicated_account/split2-H "Authorization: Bearer YOUR_SECRET_KEY"3-H "Content-Type: application/json"4-d '{ "account_number": "0033322211", "split_code": "SPL_e7jnRLtzla" }'5-X POST
1{2 "status": true,3 "message": "Subaccount assigned",4 "data": {5 "id": 22495,6 "account_name": "KAROKART/YINKA ADE",7 "account_number": "0033322211",8 "assigned": 1,9 "currency": "NGN",10 "metadata": null,11 "active": 1,12 "last_assignment_id": 525,13 "createdAt": "2020-03-20T11:03:43.000Z",14 "updatedAt": "2020-03-20T11:03:43.000Z",15 "assignment_id": 525,16 "split_config": {17 "split_code":"SPL_e7jnRLtzla"18 }19 }20}
Updating existing split code on a dedicated virtual account
Remove Split
This allows you to remove a subaccount code assigned to any dedicated virtual account, so that subsequent transactions received are fully settled into the main settlement account
1curl https://api.paystack.co/dedicated_account/split2-H "Authorization: Bearer YOUR_SECRET_KEY"3-H "Content-Type: application/json"4-d '{ "account_number": "0033322211" }'5-X DELETE
1{2 "status": "success",3 "message": "Subaccount unassigned",4 "data": {5 "id": 22173,6 "split_config": NULL,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}