docs
Cancel

No result found for:

Dedicated NUBAN

Learn how to create Nigerian bank accounts for your customers to pay you with.

Feature Availability
This feature is only available to registered businesses in Nigeria that have successfully completed the go-live process.

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.

Supported banks
Wema Bank is the only bank currently available, and we're already integrating with more banking partners. You can get available banks using the Fetch ProvidersAPI endpoint.
Show Response
1curl https://api.paystack.co/dedicated_account
2-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",
31        "email": "[email protected]",
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, it would be in the format: Product or Business Name / Customer Name.

Before creating a Dedicated NUBAN you need to take note of the following:

  1. The customer must have a name and phone number
  2. Some business categories are required to provide BVN of their customers
  3. Your integration must have webhooks set.
  4. You have a default limit of 1000 NUBANs

The customer must have a name and phone number

To create a bank account we need the customer's name, so you can only assign dedicated NUBANs to customers with first_name, last_name and phone set. For customers created without these details, you can update the customer record using the Update customerAPI endpoint.

Some business categories are required to provide BVN of their customers

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
Generating a dedicated NUBAN requires personal customer information, and should only be used with a customer's express consent, not by default.

Your integration must have webhooks set

Because 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 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",
10    "email": "[email protected]",
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": 100043
34      }
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 one or more bank account(s).

Prerequisite
You need a basic knowledge of Split Payments or Multi-split Payments before proceeding with this section.

There are two ways to add split payment on Dedicated NUBAN:

  1. Add a subaccount when creating a dedicated NUBAN
  2. Add a subaccount to an existing dedicated NUBAN

For multi-split payment on Dedicated NUBAN:

  1. Add a split code when creating a dedicated NUBAN
  2. Add a split code to an existing 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

Show Response
1curl https://api.paystack.co/dedicated_account
2-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": null
27      },
28      "split_config": {"subaccount":"ACC_qwerty"},
29      "customer": {
30        "id": 17328,
31        "first_name": "YINKA",
32        "last_name": "ADE",
33        "email": "[email protected]",
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.

Show Response
1curl https://api.paystack.co/dedicated_account/split
2-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
You can also use this endpoint to edit an existing subaccount on any Dedicated NUBAN. If a Dedicated NUBAN has a subaccount, using this endpoint updates the subaccount to the new subaccount.

Add a split code when creating a dedicated NUBAN

You can add a split code to the payload when you create a Dedicated NUBAN for the customer

Show Response
1curl https://api.paystack.co/dedicated_account
2-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": null
27      },
28      "split_config": {"split_code":"SPL_e7jnRLtzla"},
29      "customer": {
30        "id": 17328,
31        "first_name": "YINKA",
32        "last_name": "ADE",
33        "email": "[email protected]",
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 NUBAN

When updating an already existing dedicated NUBAN, you can pass a split code as one of the parameters.

Show Response
1curl https://api.paystack.co/dedicated_account/split
2-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 NUBAN
You can also use this endpoint to edit an existing split code on any Dedicated NUBAN. If a Dedicated NUBAN has a split code, using this endpoint updates the split code to the new spliit code.

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

Show Response
1curl https://api.paystack.co/dedicated_account/split
2-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}