NUBAN (Nigerian Uniform Bank Account Number) Algorithm

This repo contains the algorithm for generating and validating a NUBAN (Nigeria Uniform Bank Account Number) in Javascript. The algorithm is based on this here CBN specification for the 10-digit NUBAN. 10-digit is stated because CBN announced not too long ago that it's considering updating the specification for a NUBAN; which might see the NUBAN getting up to 16-digits in length.

Setting up

• Clone the repo.
• Navigate to the project root folder via terminal.
• Assuming node is installed on your computer:
  • Restore the node packages which the application depends on using npm install.
  • Run node index.js.

API Endpoints

1. Get Account Banks

Given any 10-digit Nigerian bank account number, this endpoint returns a JSON array of banks where that account number could be valid.

A common application of this algorithm in Nigeria today is to cut down the list of banks on USSD interfaces from about 23 to less than 5 after the user enters their bank account number (NUBAN). This comes in handy because a USSD screen can display at most, 160 characters at a time.

Specification

GET /accounts/{10-digit-NUBAN}/banks

Sample request

GET /accounts/5050114930/banks

Sample response

[
  {
    "name": "PROVIDUS BANK",
    "code": "101"
  },
  {
    "name": "STANDARD CHARTERED BANK",
    "code": "068"
  },
  {
    "name": "WEMA BANK",
    "code": "035"
  },
  {
    "name": "ZENITH BANK",
    "code": "057"
  }
]

Bank model

• name: The name of the Nigerian bank.
• code: The CBN unique identifier for the Nigerian Bank. This is a 3-digit literal.

2. Generate Bank Account

Given any 9-digit number (account serial number) and a 3-digit Nigerian bank code, this endpoint returns the full account number. Here is a list of Nigerian bank codes you can use to test this.

Specification

POST /banks/{3-digit bank code}/accounts

{
    "serialNumber"
}

** serialNumber should be 9-digits or less. If less than 9-digits, it will be left zero-padded.

Sample request

Generate a GTBank account number with serial number: '1656322'

POST /accounts/058/banks (058 is bank code for GTBank)

{
  "serialNumber": "1656322"
}

Sample response

{
  "serialNumber": "001656322",
  "nuban": "0016563228",
  "name": "Hafiz Adewuyi's GTBank account number. Donations are invited!",
  "bankCode": "058",
  "bank": {
    "name": "GUARANTY TRUST BANK",
    "code": "058"
  }
}

To-do

• List of banks to be implemented such that it's never out-of-date. It's currently an in-memory list defined within the source code. It's better to fetch this list from a reliable and always up-to-date source of Nigerian bank information on application start. This repo seems like a good start.

• Build an SPA which offers the following features:

  • Generate a valid account number for any Nigerian bank

  • Give me the first 9-digits of your NUBAN and I'll tell you your name 👻👻👻

  • Upload a list of NUBAN + bank codes for validation

    Account number	Bank Code	Valid
    0010020030	001	Yes
    0010020030	005	Yes
    0010020030	050	No
    0010020030	061	Yes

• Enhance the 'Generate Bank Account' endpoint to generate a serial number itself and return the corresponding NUBAN when the request body is empty or does not contain a valid serialNumber.

• Write unit tests. I think a good unit test would be to run at least, 10,000 real bank accounts ({ accountNumber, bankCode }) from various banks in Nigeria through the code and verify that for each account, the list of banks returned contains the actual bank.

• Deploy the application to a free Heroku container.