{"id":16597,"library":"banks-db","title":"Banks DB (Bankcard BIN Database)","description":"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.","status":"active","version":"0.23.0","language":"javascript","source_language":"en","source_url":"https://github.com/ramoona/banks-db","tags":["javascript","bankcard","bin","bank","card","color","database","db"],"install":[{"cmd":"npm install banks-db","lang":"bash","label":"npm"},{"cmd":"yarn add banks-db","lang":"bash","label":"yarn"},{"cmd":"pnpm add banks-db","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { banksDB } from 'banks-db';\nconst banksDB = require('banks-db').banksDB;","symbol":"banksDB","correct":"import banksDB from 'banks-db';"},{"note":"The raw, comprehensive bank data is exposed as a property on the default exported `banksDB` function, not as a separate named export.","wrong":"import { data } from 'banks-db';","symbol":"banksDB.data","correct":"import banksDB from 'banks-db';\nconst allBanksData = banksDB.data;"},{"note":"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.","wrong":"import { banksDBCore } from 'banks-db/core';\nconst banksDBCore = require('banks-db/core').banksDBCore;","symbol":"banksDBCore","correct":"import banksDBCore from 'banks-db/core';"},{"note":"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.","wrong":"import { ru } from 'banks-db/banks';\nimport { banksOfRussia } from 'banks-db/banks/ru';","symbol":"banksOfCountry","correct":"import banksOfRussia from 'banks-db/banks/ru';\nconst banksOfChina = require('banks-db/banks/cn');"}],"quickstart":{"code":"import banksDB from 'banks-db';\n\n// Simulate a card number input field\nconst cardNumberField = { value: '5275940000000000' };\n// In a real application, you'd get this from an input element:\n// const cardNumberField = document.getElementById('cardNumberInput');\n\nconst bank = banksDB(cardNumberField.value);\n\nif (bank.code) {\n  console.log('Bank found!');\n  console.log(`Bank Code: ${bank.code}`); // e.g., 'ru-citibank'\n  console.log(`Bank Name (EN): ${bank.engTitle}`); // e.g., 'Citibank'\n  console.log(`Card Type: ${bank.type}`); // e.g., 'mastercard'\n  console.log(`Brand Color: ${bank.color}`); // e.g., '#F8C220'\n  console.log(`Country: ${bank.country}`); // e.g., 'ru'\n  // Example of applying styles based on bank data\n  // document.body.style.backgroundColor = bank.color;\n} else if (bank.type) {\n  console.log('Bank not found in DB, but card type identified: ' + bank.type);\n} else {\n  console.log('No bank or card type identified for this prefix.');\n}\n\n// To see the raw data (for debugging or custom processing)\n// console.log('\\nFull Banks DB Data:');\n// for (const b of banksDB.data) {\n//   console.log(b.code, b.engTitle);\n//   if (b.code === 'ru-citibank') break; // Limit output for brevity\n// }","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Always check `if (bank.code)` before attempting to access bank-specific properties like `bank.engTitle` or `bank.color` to avoid runtime errors.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Use a default import for ESM: `import banksDB from 'banks-db';` or a direct `require` for CommonJS: `const banksDB = require('banks-db');`.","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.","error":"TypeError: banksDB is not a function"},{"fix":"Add a conditional check: `const bank = banksDB(cardNumber); if (bank.code) { /* use bank.color */ } else { /* handle unknown bank */ }`.","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.","error":"Cannot read properties of undefined (reading 'color') (or similar for 'engTitle', 'code')"},{"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.","cause":"Incorrectly importing all banks then trying to filter, or using the main `banks-db` package when only a few countries are needed.","error":"Importing country-specific data causes entire `banks-db` package to be bundled or increases bundle size unexpectedly."}],"ecosystem":"npm"}