Credit Card BIN Data

This is a data file project similar to tzdata, providing credit card BIN (Bank Identification Number) patterns as a source of truth for other libraries.

This repository contains authoritative data about credit card BIN patterns for validation and brand identification, along with reference implementations in multiple programming languages.

The original idea came from this gist by Erik Henrique.

After a JavaScript-only creditcard version, I found myself looking for this in other languages. With a bit of vibe coding style, I created libs for all languages I need (come contribute with more!). The idea is to generate from a source of truth in JSON to language-specific native code, avoiding the overhead of loading JSON files at runtime.

bin-cc/
├── data/                    # Credit card BIN data
│   ├── sources/            # Source data files (editable)
│   │   ├── visa/          # Subfolder for complex brands
│   │   │   ├── base.json
│   │   │   └── bins-*.json
│   │   ├── mastercard.json
│   │   └── ...
│   ├── compiled/           # Compiled output formats
│   │   ├── cards.json      # Simplified regex format
│   │   └── cards-detailed.json  # Full detailed format
│   ├── SCHEMA.md           # Data schema documentation
│   └── README.md           # Data usage guide
│
├── scripts/                # Build and validation tools
│   ├── build.js           # Compiles source → compiled data
│   ├── validate.js        # Standalone validation CLI
│   ├── create-card.js     # Interactive card creation CLI
│   └── lib/               # Shared modules
│
├── libs/                   # Reference implementations
│   ├── javascript/        # Each lib includes example.{ext}
│   ├── python/
│   ├── ruby/
│   ├── elixir/
│   ├── dotnet/
│   ├── java/
│   ├── rust/
│   ├── go/
│   └── php/
│
├── CONTRIBUTING.md         # Contribution guidelines
├── LICENSE                 # MIT License
└── package.json            # Build scripts

The authoritative data follows a build system similar to browserslist:

• Source files data/sources/ - Human-editable card scheme definitions
• Build script scripts/build.js - Compiles and validates data
• Detailed output data/compiled/cards-detailed.json - Full details with BINs
• Simplified output data/compiled/cards.json - Regex patterns only
• Schema docs data/SCHEMA.md - Complete schema documentation

npm run build

This compiles source files into both detailed and simplified formats with validation.

# Validate all sources
node scripts/validate.js

# Validate specific file or directory
node scripts/validate.js data/sources/visa
node scripts/validate.js data/sources/amex.json

node scripts/create-card.js

Interactive CLI to create new card scheme source files.

All libraries provide the same core functionality for credit card BIN validation and brand identification.

Complete implementation in libs/javascript/

npm install creditcard-identifier

const cc = require('creditcard-identifier');
console.log(cc.findBrand('4012001037141112')); // 'visa'

Complete implementation in libs/python/

pip install creditcard-identifier

from creditcard_identifier import find_brand
print(find_brand('4012001037141112'))  # 'visa'

Complete implementation in libs/ruby/

gem install creditcard-identifier

require 'creditcard_identifier'
puts CreditcardIdentifier.find_brand('4012001037141112')  # 'visa'

Complete implementation in libs/elixir/

# mix.exs
{:creditcard_identifier, "~> 1.0"}

# usage
CreditcardIdentifier.find_brand("4012001037141112")  # "visa"

Complete implementation in libs/dotnet/

dotnet add package CreditCardIdentifier

using CreditCardIdentifier;
CreditCard.FindBrand("4012001037141112");  // "visa"

Complete implementation in libs/java/

<!-- Maven -->
<dependency>
    <groupId>br.com.s2n.creditcard</groupId>
    <artifactId>creditcard-identifier</artifactId>
    <version>2.1.0</version>
</dependency>

import br.com.s2n.creditcard.identifier.CreditCardValidator;

CreditCardValidator validator = new CreditCardValidator();
validator.findBrand("4012001037141112");  // "visa"

Complete implementation in libs/rust/

# Cargo.toml
[dependencies]
creditcard-identifier = "2.1.0"

use creditcard_identifier::*;
find_brand("4012001037141112");  // Some("visa")

Complete implementation in libs/go/

go get github.com/renatovico/bin-cc/libs/go

import creditcard "github.com/renatovico/bin-cc/libs/go"

brand := creditcard.FindBrand("4012001037141112")  // "visa"

Complete implementation in libs/php/

composer require creditcard/identifier

use CreditCard\Identifier\CreditCardValidator;

$validator = new CreditCardValidator();
$validator->findBrand('4012001037141112');  // "visa"

See data/compiled/BRANDS.md for the auto-generated list of supported card brands.

Contributions are welcome! This project follows a source → build → compiled workflow:

1. Data updates: Edit source files in data/sources/
2. Build: Run npm run build to compile and validate
3. Test: Ensure npm test passes
4. Document: Cite sources in your PR description

See CONTRIBUTING.md for detailed guidelines.

# Create a new card scheme interactively
node scripts/create-card.js

# Or edit a source file manually
vim data/sources/visa/base.json

# Build and validate
npm run build

# Test
npm test

# Commit changes (both source and generated files)
git add data/
git commit -m "Update Visa BIN patterns"

All libraries are published to their respective package registries for easy installation:

To publish new versions of the libraries, see the RELEASE.md guide. Each library also has its own PUBLISH.md file with detailed instructions:

• Java Publishing Guide
• Rust Publishing Guide
• Go Publishing Guide
• PHP Publishing Guide

All new libraries support automated publishing via GitHub Actions when you create a release with the appropriate tag format (e.g., java-v2.1.0).

MIT License