Card Toolkit

A powerful and dependency-free Python library to generate and validate credit card numbers. It uses a local, offline BIN database for fast and reliable bank and country lookups without needing API keys or internet access.

Русская версия

Мощная и не имеющая зависимостей Python-библиотека для генерации и валидации номеров кредитных карт. Использует локальную офлайн-базу данных BIN для быстрого и надежного определения банка и страны без необходимости в API-ключах или доступе в интернет.

---

Key Features

• Generate Valid Cards: Creates credit card numbers that pass the Luhn algorithm check for various schemes (Visa, MasterCard, Amex, Discover).
• Offline BIN Lookup: Includes a local BIN database to retrieve card details like brand, type, country, and bank issuer.
• No Dependencies: The core logic has zero external dependencies, making it lightweight and easy to integrate.
• No API Keys Required: All lookups are performed locally, so you don't need to sign up for services or manage secret keys.
• Modern and Clean API: Designed with clear, predictable methods and properties.
• Fully Typed: Provides full type hinting for better autocompletion and static analysis.

Installation

You can install the library from PyPI using pip or any other modern package manager like uv.

Using pip

# On Windows
py -m pip install card_generator

# On Linux/macOS
python3 -m pip install card_generator

Using uv

uv is an extremely fast, next-generation Python package installer.

# Install into your virtual environment (recommended)
uv pip install card_generator

# Or, if you need to install it system-wide (use with caution)
uv pip install --system card_generator

Usage Examples

Here are some examples of how to use the library's main features.

1. Generating Credit Cards

Use the CardGenerator class to create one or more cards.

from card_generator import CardGenerator

# Initialize a generator for MasterCard
mastercard_generator = CardGenerator("mastercard")

# Generate 3 standard cards
cards = mastercard_generator.generate(count=3)
print(cards)

Example Output:

[
  {
    "card": "5486241234567890",
    "expiry_date": "07/28",
    "cvv": 451
  },
  {
    "card": "5179509876543210",
    "expiry_date": "11/29",
    "cvv": 812
  },
  {
    "card": "5543620011223344",
    "expiry_date": "02/27",
    "cvv": 123
  }
]

Generation with Options

You can generate cards with formatted numbers and include bank information.

from card_generator import CardGenerator
import json

amex_generator = CardGenerator("amex")

# Generate 2 cards with formatting and bank info
pretty_cards = amex_generator.generate(
    count=2,
    beautiful_format=True,
    include_bank_info=True
)

print(json.dumps(pretty_cards, indent=2))

Example Output:

[
  {
    "card": "3782 822463 10005",
    "expiry_date": "05/30",
    "cvv": 8812,
    "info": {
      "brand": "AMERICAN EXPRESS",
      "type": "CREDIT",
      "category": "",
      "country": "United States",
      "country_code": "US",
      "bank": "AMERICAN EXPRESS",
      "bank_url": "www.americanexpress.com",
      "bank_phone": ""
    }
  },
  {
    "card": "3412 345678 90127",
    "expiry_date": "12/28",
    "cvv": 1234,
    "info": null
  }
]

(Note: info will be null if the generated BIN is not found in the local database.)

---

2. Validating Credit Cards

Use the CardValidator class to check card numbers and get details.

from card_generator import CardValidator

# A valid Visa card number
card_number = "4539920412345671"

# Initialize the validator
validator = CardValidator(card_number)

# --- Check Validity ---
print(f"Is Luhn valid? {validator.is_luhn_valid()}")

# --- Get Card Type ---
# This is a property, not a method
print(f"Card type: {validator.card_type}")

# --- Get All Available BIN Info ---
info = validator.get_bin_info()
print("BIN Info:")
print(info)

Example Output:

Is Luhn valid? True
Card type: visa
BIN Info:
{'brand': 'VISA', 'type': 'DEBIT', 'category': 'CLASSIC', 'country': 'Russian Federation', 'country_code': 'RU', 'bank': 'SBERBANK', 'bank_url': 'www.sberbank.ru', 'bank_phone': '+7-495-500-55-50'}

---

Acknowledgements / Источник данных

This project utilizes the BIN list data provided by the bin-list-data project, which is maintained by venelinkochev and contributors. The data is licensed under the Creative Commons Attribution 4.0 International License.

• Source: github.com/venelinkochev/bin-list-data

---

Этот проект использует данные из списка BIN, предоставленные проектом bin-list-data под руководством venelinkochev и его соавторов. Данные распространяются по лицензии Creative Commons Attribution 4.0 International.

• Источник: github.com/venelinkochev/bin-list-data