NUBAN Bank Predictor

Overview

In the Nigerian financial ecosystem, while many APIs provide account owner names based on bank and account number, there's a significant gap: the ability to suggest the corresponding bank solely from an account number. This library addresses that challenge by providing a robust solution to predict the likely bank(s) associated with a given NUBAN (Nigerian Uniform Bank Account Number) or identify fintech platforms based on phone numbers.

Problem Solved

Traditional bank account validation often requires both the bank code and the account number. This library fills a crucial need by allowing developers to determine potential banks when only the NUBAN is available, streamlining user experience and reducing friction in financial applications.

Features

• NUBAN to Bank Prediction: Accurately predicts possible banks for a given 10-digit NUBAN using the official NUBAN check digit algorithm.
• Fintech Identification (Phone Numbers): Identifies popular fintech platforms (like OPay, PalmPay, Moniepoint) when a valid Nigerian phone number is provided as input.
• Smart Prioritization: Intelligently prioritizes and orders suggested banks — Moniepoint for known prefixes, followed by popular banks.
• Flexible Bank List: Pass your own bank or fintech list; the built-in lists are optional defaults.
• Case-Insensitive Matching: Popular bank prioritization matches on the first word of the bank name, case-insensitively — so "Opay Microfinance Bank" in your custom list will still be ranked as a popular bank.
• TypeScript Support: Fully typed with .d.ts declarations included.

Installation

npm install nuban-prediction

Usage

Basic — NUBAN Prediction

const getPredictedBanks = require("nuban-prediction");

const result = getPredictedBanks("0088064294");
console.log(result);
// [
//   { name: 'ACCESS BANK', code: '044' },
//   { name: 'FIRST BANK OF NIGERIA', code: '011' },
//   ...
// ]

Basic — Phone Number (returns fintechs)

const result = getPredictedBanks("8012345678");
// [ { name: 'OPAY', code: '999992' }, { name: 'PalmPay', code: '999991' }, ... ]

const withMoniepoint = getPredictedBanks("9012345678");
// Same list + Moniepoint appended (90/81 prefixes)

Custom Bank List

Supply your own bank list via options.banks. The built-in list is ignored and only your entries are checked against the NUBAN algorithm.

const myBanks = [
  { name: "Opay Microfinance Bank", code: "999992" },
  { name: "Kuda Bank", code: "090267" },
  { name: "My Cooperative", code: "51244" },
];

const result = getPredictedBanks("0088064294", { banks: myBanks });

Popular bank prioritization still works with custom lists. Matching uses the first word of the bank name (case-insensitive), so:

| Your list entry | Matches popular slot | |---|---| | "Opay Microfinance Bank" | ✅ OPAY | | "Zenith Commercial" | ✅ ZENITH BANK | | "ACCESS BANK" | ✅ ACCESS BANK | | "My Local Coop" | ❌ (not popular — ranked after popular banks) |

Custom Fintech List

const myFintechs = [
  { name: "Opay", code: "999992" },
  { name: "My Wallet App", code: "88888" },
];

const result = getPredictedBanks("8012345678", { fintechs: myFintechs });
// Returns only your custom fintechs

Note: If Moniepoint is already in your custom fintech list, it will not be added again for 90/81 phone prefixes.

TypeScript

import getPredictedBanks from "nuban-prediction";

const result = getPredictedBanks("0088064294", {
  banks: [{ name: "Opay MFB", code: "999992" }],
});

Output Structure

[
  { name: "BANK NAME", code: "bank_code" },
  ...
]

Prioritization Logic

For NUBAN inputs:

1. Moniepoint prefix rule — If the NUBAN starts with 56, 54, 81, 50, 53, 55, 82, 63, 58, 57, 59, 65, or 90, and a Moniepoint entry is in the results, it is moved to position 0.
2. Popular banks — A curated list of popular Nigerian banks is ranked next, in order. Matching is by first word (case-insensitive), so custom list entries like "Zenith Commercial" match the ZENITH BANK popular slot.
3. Remaining banks — Any other NUBAN-valid banks follow in no specific order.

Running Tests

npm test

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

This project is licensed under the ISC License.