naija-validators

Nigerian data validators for developers. TypeScript-first. Zero dependencies.

Stop hand-writing Nigerian validation regexes. This package covers every identifier Nigerian apps need to validate — phone numbers, BVN, NIN, NUBAN bank accounts, CAC registration numbers, and TIN.

Install

npm install naija-validators

or

yarn add naija-validators

What's included

| Validator | Function | Description | |-----------|----------|-------------| | Phone | validatePhone | Validates + detects carrier (MTN, Airtel, Glo, 9mobile…) | | BVN | validateBVN | Bank Verification Number (CBN, 11 digits) | | NIN | validateNIN | National Identification Number (NIMC, 11 digits) | | NUBAN | validateNUBAN | Bank account with check digit algorithm | | RC Number | validateRC | CAC registration (RC, BN, IT prefixes) | | TIN | validateTIN | Tax Identification Number (FIRS/NRS) |

Usage

Phone Number

import { validatePhone, isValidPhone, formatPhone, detectPhoneCarrier } from "naija-validators";

validatePhone("08012345678");
// {
//   valid: true,
//   carrier: "MTN",
//   formatted: { local: "08012345678", international: "+2348012345678" }
// }

validatePhone("+2347031234567");
// { valid: true, carrier: "MTN", formatted: { ... } }

validatePhone("0800000");
// { valid: false, message: "Invalid Nigerian phone number format..." }

// Quick checks
isValidPhone("08012345678");        // true
formatPhone("08012345678");         // "+2348012345678"
formatPhone("08012345678", "local") // "08012345678"
detectPhoneCarrier("08052345678");  // "Glo"

Supported carriers: MTN, Airtel, Glo, 9mobile, Ntel, Smile, Spectranet

Accepted formats:

• 08012345678 (local)
• +2348012345678 (international with +)
• 2348012345678 (international without +)
• 8012345678 (no leading 0)

BVN

import { validateBVN, isValidBVN } from "naija-validators";

validateBVN("12345678901");
// { valid: true, message: "Valid BVN" }

validateBVN("1234");
// { valid: false, message: "BVN must be exactly 11 digits (got 4)" }

isValidBVN("12345678901"); // true

NIN

import { validateNIN, isValidNIN } from "naija-validators";

validateNIN("12345678901");
// { valid: true, message: "Valid NIN" }

isValidNIN("ABC12345678"); // false

NUBAN (Bank Account)

import { validateNUBAN, isValidNUBAN, getAvailableBankCodes } from "naija-validators";

// Format-only (no bank code)
validateNUBAN("0123456789");
// { valid: true, message: "Valid account number format (provide bank code for full NUBAN validation)" }

// Full NUBAN check digit validation
validateNUBAN("0123456789", "058"); // GTBank
// { valid: true, bankName: "Guaranty Trust Bank (GTBank)", bankCode: "058" }

validateNUBAN("0123456780", "058");
// { valid: false, message: "Invalid NUBAN: check digit mismatch (expected 9, got 0)" }

// Get all bank codes
getAvailableBankCodes();
// [{ code: "044", name: "Access Bank" }, { code: "058", name: "GTBank" }, ...]

Common bank codes:

| Bank | Code | |------|------| | Access Bank | 044 | | First Bank | 011 | | GTBank | 058 | | UBA | 033 | | Zenith Bank | 057 | | Kuda Bank | 090267 | | OPay | 100004 |

RC Number (CAC)

import { validateRC, isValidRC } from "naija-validators";

validateRC("RC123456");
// { valid: true, type: "company", prefix: "RC" }

validateRC("BN1234567");
// { valid: true, type: "business_name", prefix: "BN" }

validateRC("IT12345");
// { valid: true, type: "incorporated_trustee", prefix: "IT" }

isValidRC("INVALID"); // false

TIN (Tax Identification Number)

import { validateTIN, isValidTIN } from "naija-validators";

validateTIN("12345678");        // { valid: true }
validateTIN("1234567890");      // { valid: true }
validateTIN("12345678-0001");   // { valid: true } (hyphenated)

isValidTIN("ABC"); // false

Bank Data Utilities

import { getBankByCode, getBankByName, getBankNames, NIGERIAN_BANKS } from "naija-validators";

getBankByCode("058");
// { name: "Guaranty Trust Bank (GTBank)", code: "058", ussd: "*737#" }

getBankByName("zenith");
// { name: "Zenith Bank", code: "057", ussd: "*966#" }

getBankNames();
// ["Access Bank", "Citibank Nigeria", ...]

With React Hook Form

import { isValidPhone, isValidBVN } from "naija-validators";

<input
  {...register("phone", {
    validate: (v) => isValidPhone(v) || "Enter a valid Nigerian phone number"
  })}
/>

<input
  {...register("bvn", {
    validate: (v) => isValidBVN(v) || "Enter a valid 11-digit BVN"
  })}
/>

Contributing

If a carrier prefix has changed, a new bank has been added, or a CAC format has been updated, please open an issue with a reference to the official NCC/CBN/CAC source.

License

MIT © Marcus Aregbe