Building a NUBAN Account Number Classifier with Spring Boot

Summary

Have you ever wondered how when you use an application that involves you entering your account number, it gives a short list of banks that your account number could possibly belong to? It achieves this to a high level of accuracy, rather than returning a list of all the banks in operation.

In this article, we will discuss how this precise classification is achieved, and implement this in code using Java. We are also going to demonstrate the relevance of this classification in building USSD applications that are enabled to perform financial transactions.

Requirements

1. A rudimentary understanding of Java language.
2. A text editor of choice.
3. Postman (to test endpoints from our classification algorithm).

Introduction

In 2010, the Central Bank of Nigeria (CBN) released guidelines to achieve a uniform customer bank account numbering structure for all money deposit banks. This was also known as the Nigeria Uniform Bank Account Number(NUBAN) scheme. These deposit banks were given 9 months to implement this new classification strategy.

The aim of this scheme was to tackle financial problems relating to electronic payments, as a result of beneficiary bank accounts being wrongly misclassified.

In response to the directives of the CBN, the Cheques and ACH Working Group (CAWG) met and deliberated on these issues and recommended an approach to tackle the classification issue.

The NUBAN Algorithm

After the deliberations of the CAWG, the following steps were approved for developing the NUBAN algorithm:

Step 1 — Approving the NUBAN format ABC-DEFGHIJKL-M, where ABC is the unique 3 digit bank code conferred on the bank by the CBN. A list of banks and their unique bank codes can be found here.

DEFGHIJKL is the NUBAN account serial number.

M is the check digit. The check digit is required for the account number validation and classification.

Step 2 — Calculating the check digit using the following steps:

1. Calculating the value of A*3+B*7+C*3+D*3+E*7+F*3+G*3+H*7+I*3+J*3+K*7+L*3.
2. Calculating modulo 10 of the value above, which is simply the remainder after dividing by 10.
3. Subtracting the result of the modulo from 10, in order to get the check digit value.
4. If the result is 10, then 0 is used as the check digit.

In case you are interested in reading more about the NUBAN algorithm, you can check here for more details and examples.

Application of the NUBAN Algorithm

We explained how the NUBAN algorithm works in the last section. How then does this algorithm help us? How do we use this algorithm to classify bank account numbers to a high degree of accuracy? These questions will be answered in this section.

As seen above in the NUBAN format, the NUBAN serial number (DEFGHIJKL) is 9 digits long which are then followed by by the check digit number M. That makes DEFGHIJKLM, which is 10 digits; the same number of digits in a bank account number.

If we split a bank account number into its serial number and check digit (last number in the account number), we can use the NUBAN algorithm on a combination of the serial number, with various banks and their unique bank codes. By doing this, we calculate a check digit which we compare to the already know last number of the bank account.

If both values match, then the account number could belong to the bank whose unique code was used in the computation.

The algorithm is shown in the diagram below

From the diagram above, the account number is split into a 9 digit serial number and the 1 digit check digit. This is then passed into the NUBAN algorithm. For each bank object in the bank list, the NUBAN algorithm check digit is computed, after which it is compared to the check digit of the account number entered into the algorithm.

If these digits are the same, the bank is added to the list of possible banks.

Putting the Algorithm to code

First thing I did was to create a Bank class, containing the bank name and its unique CBN code, as shown below

After this was done, I created a method that would return the list of all banks in operation in Nigeria. This method accesses a JSON file that contains the bank data for all the banks. After it does this, it parses the contents of the JSON file into a Java list of BankDataDto objects.

Next thing I did after this was to create a method that would return a list of possible banks that the account number belong to after making the necessary computations and checks, as shown below.

I also made provisions for testing with Postman, and also for third parties to be able to use this service by creating an endpoint.

The full code to the NUBAN algorithm implemented in Java can be accessed here.

Testing the NUBAN Algorithm

Step 1 — Run the Spring boot Application

In order to test our code logic and confirm it works as expected, we first run the Spring boot application that houses the NUBAN algorithm. In order to do this, the first step is to clone the application source code from here.

Ensure you have Java 11 installed.

After this is done, navigate to the root file containing the code and run the following code in the terminal

./mvnw spring-boot:run

The photo below shows the terminal output when the application runs successfully.

Step 2- Test the application with Postman

When testing the application endpoint, the endpoint to be used is given below:

GET {{base_url}}/api/v1/bank-list/{accountNumber}

So if we wanted to see the bank list that 3093255991 belonged to, we would put the account number into the endpoint as follows:

GET {{base_url}}/api/v1/bank-list/3093255991

The result would be a an array of bank objects containing the name and bank codes, as shown below:

{
  "code": 200,
  "message": "Successful call",
  "data": [
    {
      "bankName": "Access Bank",
      "uniqueCbnBankCode": "044"
    },
    {
      "bankName": "EcoMobile",
      "uniqueCbnBankCode": "307"
    },
    {
      "bankName": "Fidelity Mobile",
      "uniqueCbnBankCode": "318"
    },
    {
      "bankName": "First Bank",
      "uniqueCbnBankCode": "011"
    },
    {
      "bankName": "Omoluabi Mortgage Bank",
      "uniqueCbnBankCode": "990"
    },
    {
      "bankName": "PayAttitude Online",
      "uniqueCbnBankCode": "329"
    },
    {
      "bankName": "UBA",
      "uniqueCbnBankCode": "033"
    }
  ]
}

Applying this Application To USSD Applications

Just in case you are wondering what is USSD means, according to Wikipedia,

Unstructured, Supplementary Service Data (USSD) sometimes referred to as “Quick Codes” or “Feature Codes” is a communications protocol used by GSM cellular telephones to communicate with the mobile network operator’s computers.

The USSD can be used for a lot of services, including making financial transactions. Assuming you wanted to perform a financial transaction where you entered your account number, the algorithm we built above would narrow down the list of possible banks your account number could belong from almost 80 banks to 7 banks.

This might not seem significant, but it actually is, because the number of characters that can be displayed on a USSD application interface at a particular time is 160. The NUBAN algorithm addresses this problem efficiently.

An example of such is shown in the photos below. I incorporated the NUBAN algorithm in a USSD application I built recently.

Conclusion

The aim of this article was to explain the NUBAN algorithm and give a real life application of it. I hope it was helpful and most importantly explanatory. Thank you for reading this far.

The code for the application can be found in my GitHub repository here.

Thank you!!!