Banks DB (Bankcard BIN Database)

Common errors

• TypeError: banksDB is not a function

  cause Attempting to import `banksDB` as a named export (`import { banksDB } from 'banks-db';`) or accessing it as a property on the `require` result in CommonJS.
  fix Use a default import for ESM: `import banksDB from 'banks-db';` or a direct `require` for CommonJS: `const banksDB = require('banks-db');`.

• Cannot read properties of undefined (reading 'color') (or similar for 'engTitle', 'code')

  cause Accessing properties of the `bank` object (e.g., `bank.color`) without first verifying that `bank.code` exists, which indicates that a matching bank was found in the database.
  fix Add a conditional check: `const bank = banksDB(cardNumber); if (bank.code) { /* use bank.color */ } else { /* handle unknown bank */ }`.

• Importing country-specific data causes entire `banks-db` package to be bundled or increases bundle size unexpectedly.

  cause Incorrectly importing all banks then trying to filter, or using the main `banks-db` package when only a few countries are needed.
  fix For specific countries, import `banksDBCore` from `banks-db/core` and then import only the required country data from `banks-db/banks/[cc]` (e.g., `import banksOfRussia from 'banks-db/banks/ru';`). Initialize `banksDBCore` with only the data you need.

Warnings

• gotcha Do not use `banks-db` for any critical billing logic, fraud detection, or security-sensitive operations. The database is community-driven and may contain inaccuracies or be incomplete, making it unsuitable for financial validation beyond UX enhancements.
  Fix: Implement robust server-side validation and use trusted payment gateways for all financial transaction logic. Only use `banks-db` for cosmetic or user guidance purposes.
• breaking As `banks-db` is currently in `0.x.0` versioning, any minor release (e.g., from 0.22.0 to 0.23.0) *could* potentially introduce breaking changes to the API or data structure, although this is not explicitly documented for every release. Database updates might also alter `bank.code` or other property values for existing BINs.
  Fix: Review the release notes for each new version, especially when updating `0.x.0` releases. Test thoroughly to ensure existing integrations remain functional after an upgrade.
• gotcha The `banksDB` function returns an object with a `type` property (e.g., 'visa', 'mastercard') even if no bank-specific data is found. The `code`, `color`, `engTitle`, etc., properties will be `undefined` if the BIN is not in the database. Always check for `bank.code` to determine if detailed bank information is available.
  Fix: Always check `if (bank.code)` before attempting to access bank-specific properties like `bank.engTitle` or `bank.color` to avoid runtime errors.

Install

• npm install banks-db npm
• yarn add banks-db yarn
• pnpm add banks-db pnpm

Imports

• banksDB
  wrong:

  import { banksDB } from 'banks-db';
  const banksDB = require('banks-db').banksDB;

  correct:

  import banksDB from 'banks-db';

  The main `banks-db` package exports the lookup function as its default export for both ESM and CommonJS. Accessing it via named import or property access for CJS will fail.
• banksDB.data
  wrong:

  import { data } from 'banks-db';

  correct:

  import banksDB from 'banks-db';
  const allBanksData = banksDB.data;

  The raw, comprehensive bank data is exposed as a property on the default exported `banksDB` function, not as a separate named export.
• banksDBCore
  wrong:

  import { banksDBCore } from 'banks-db/core';
  const banksDBCore = require('banks-db/core').banksDBCore;

  correct:

  import banksDBCore from 'banks-db/core';

  The core function for country-specific lookups is a default export from the 'banks-db/core' subpath. Similar to the main package, use default import/require.
• banksOfCountry
  wrong:

  import { ru } from 'banks-db/banks';
  import { banksOfRussia } from 'banks-db/banks/ru';

  correct:

  import banksOfRussia from 'banks-db/banks/ru';
  const banksOfChina = require('banks-db/banks/cn');

  Country-specific bank data is provided as a default export from their respective subpaths (e.g., 'banks-db/banks/ru'). Combine with `banksDBCore` for specific country lookups.

Quickstart

This quickstart demonstrates how to import and use the `banks-db` library to retrieve bank information and card type from a given card number prefix, showing how to access properties like bank code, name, type, and brand color. It also illustrates how to access the raw database.

import banksDB from 'banks-db';

// Simulate a card number input field
const cardNumberField = { value: '5275940000000000' };
// In a real application, you'd get this from an input element:
// const cardNumberField = document.getElementById('cardNumberInput');

const bank = banksDB(cardNumberField.value);

if (bank.code) {
  console.log('Bank found!');
  console.log(`Bank Code: ${bank.code}`); // e.g., 'ru-citibank'
  console.log(`Bank Name (EN): ${bank.engTitle}`); // e.g., 'Citibank'
  console.log(`Card Type: ${bank.type}`); // e.g., 'mastercard'
  console.log(`Brand Color: ${bank.color}`); // e.g., '#F8C220'
  console.log(`Country: ${bank.country}`); // e.g., 'ru'
  // Example of applying styles based on bank data
  // document.body.style.backgroundColor = bank.color;
} else if (bank.type) {
  console.log('Bank not found in DB, but card type identified: ' + bank.type);
} else {
  console.log('No bank or card type identified for this prefix.');
}

// To see the raw data (for debugging or custom processing)
// console.log('\nFull Banks DB Data:');
// for (const b of banksDB.data) {
//   console.log(b.code, b.engTitle);
//   if (b.code === 'ru-citibank') break; // Limit output for brevity
// }