Dedicated NUBAN
Learn how to create Nigerian bank accounts for your customers to pay you with.
Feature Availability
What is Dedicated NUBAN?
The Dedicated NUBAN feature on the Paystack Dashboard and API lets you create dedicated Nigerian bank accounts for your customers to pay you with.
When you create a Dedicated NUBAN for a customer, all bank transfers to that account will automatically be recorded as transactions from that customer.
Creating a Dedicated NUBAN
To create a Dedicated NUBAN for a customer, send a POST
request to our Create Dedicated AccountAPI endpoint.
Bank Availabilty
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": "wema-bank" }'5-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",32 "customer_code": "CUS_kpb3qj71u1m0rw8",33 "phone": "+2349053267565",34 "risk_action": "default"35 }36 }37 }
Account naming
When creating a Dedicated NUBAN you need to take note of the following:
- The customer's identification details must be validated.
- Your integration must have webhooks set.
- You have a default limit of 1000 NUBANs
The customer's identification details must be validated
For compliance reasons, you 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
Your integration must have webhooks set
Because bank transfers happen offline, 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 NUBAN 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 }
You have a default limit of 1000 NUBANs
By default, you can generate up to 1000 dedicated bank accounts for your customers. This limit can be increased upon review of your business and use-case. To increase the limit for your business, please send an email to [email protected]
Get a Customer's Dedicated NUBAN
If you want to retrieve a customer's dedicated NUBAN, call the Fetch CustomerAPI endpoint. You can retrieve the Dedicated NUBAN 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}
Split payment on Dedicated NUBAN
Split payment for Dedicated NUBAN allows you to automatically split funds received into a Dedicated NUBAN between your main settlement bank account and another bank account.
Prerequisite
There are two ways to add split payment on Dedicated NUBAN:
Add a subaccount when creating a dedicated NUBAN
You can add a subaccount code to the payload when you create a Dedicated NUBAN 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 NUBAN
When updating an already existing dedicated NUBAN, 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 NUBAN
Remove Split
This allows you to remove a subaccount code assigned to any dedicated NUBAN, 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}