banks-db

library0.23.0jsnpmunverified

The `banks-db` library provides a client-side database of bank identification numbers (BINs) to retrieve bank names and associated brand colors based on a bankcard prefix. Its primary function is to enhance user experience on billing pages, for example, by dynamically displaying a bank's logo or changing background colors as a user types their card number. It is crucial to understand that this database is community-driven and explicitly warns against its use for any billing logic, fraud detection, or security-sensitive operations due to potential inaccuracies or incompleteness. The current stable version is 0.23.0, and the package maintains a relatively active release cadence, with minor version updates typically occurring every few weeks to months, often reflecting database updates or small feature enhancements. A key differentiator is its dual approach: offering a comprehensive global dataset through the main export, alongside the ability to selectively load country-specific data for optimized bundle sizes, with direct integration examples for PostCSS and CSS-in-JS environments.

data payments

npm install banks-db

github ↗package ↗

INSTALL

IMPORT

SIG · BANKS-DB

banks-db

datajavascriptv0.23.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

banksDB

✓ import banksDB from 'banks-db';

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

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

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

✗ import { data } from 'banks-db';

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

banksDBCore

✓ import banksDBCore from 'banks-db/core';

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

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

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

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

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.

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 // }

Debug

Known issues

gotchaDo 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.

affects: >=0.1.0

breakingAs `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.

affects: >=0.1.0

gotchaThe `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.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: banksDB is not a function

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')

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.

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.

Upgrade

Version history

0.23.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

81 hits · last 30 days

node

Perplexity

panscient.com

OpenAI (training)

Resources

githubhttps://github.com/ramoona/banks-db ↗

packagehttps://www.npmjs.com/package/banks-db ↗