# Card Toolkit
[](https://badge.fury.io/py/card-generator)
[](https://github.com/NjProVk/CreditsCardTools/actions/workflows/ci.yml)
[](https://github.com/NjProVk/CreditsCardTools/blob/main/LICENSE)
[](https://pypi.org/project/card-generator/)
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.
<details>
<summary><strong>Русская версия</strong></summary>
Мощная и не имеющая зависимостей Python-библиотека для генерации и валидации номеров кредитных карт. Использует локальную офлайн-базу данных BIN для быстрого и надежного определения банка и страны без необходимости в API-ключах или доступе в интернет.
</details>
---
## 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`
```bash
# 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.
```bash
# 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.
```python
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:**
```json
[
{
"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.
```python
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:**
```json
[
{
"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.
```python
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](https://creativecommons.org/licenses/by/4.0/).
- **Source:** [github.com/venelinkochev/bin-list-data](https://github.com/venelinkochev/bin-list-data)
---
Этот проект использует данные из списка BIN, предоставленные проектом `bin-list-data` под руководством venelinkochev и его соавторов. Данные распространяются по лицензии [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/).
- **Источник:** [github.com/venelinkochev/bin-list-data](https://github.com/venelinkochev/bin-list-data)
Raw data
{
"_id": null,
"home_page": null,
"name": "card-generator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "credit card, card generator, card validator, luhn, luhn algorithm, bin, bin lookup, bin checker, iin, generate, generator, validate, validator, validation, visa, mastercard, amex, discover, fintech, payment, ecommerce, test data, mock data, fake data, offline, no-api, local-database",
"author": null,
"author_email": "NjProVk <njprovk@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/3b/f2/cb15e4894f97575ed8119184dc9974ff832a5562837f2cd4c5641f2961f2/card_generator-0.1.6.tar.gz",
"platform": null,
"description": "# Card Toolkit\r\n\r\n[](https://badge.fury.io/py/card-generator)\r\n[](https://github.com/NjProVk/CreditsCardTools/actions/workflows/ci.yml)\r\n[](https://github.com/NjProVk/CreditsCardTools/blob/main/LICENSE)\r\n[](https://pypi.org/project/card-generator/)\r\n\r\nA 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.\r\n\r\n<details>\r\n<summary><strong>\u0420\u0443\u0441\u0441\u043a\u0430\u044f \u0432\u0435\u0440\u0441\u0438\u044f</strong></summary>\r\n\r\n\u041c\u043e\u0449\u043d\u0430\u044f \u0438 \u043d\u0435 \u0438\u043c\u0435\u044e\u0449\u0430\u044f \u0437\u0430\u0432\u0438\u0441\u0438\u043c\u043e\u0441\u0442\u0435\u0439 Python-\u0431\u0438\u0431\u043b\u0438\u043e\u0442\u0435\u043a\u0430 \u0434\u043b\u044f \u0433\u0435\u043d\u0435\u0440\u0430\u0446\u0438\u0438 \u0438 \u0432\u0430\u043b\u0438\u0434\u0430\u0446\u0438\u0438 \u043d\u043e\u043c\u0435\u0440\u043e\u0432 \u043a\u0440\u0435\u0434\u0438\u0442\u043d\u044b\u0445 \u043a\u0430\u0440\u0442. \u0418\u0441\u043f\u043e\u043b\u044c\u0437\u0443\u0435\u0442 \u043b\u043e\u043a\u0430\u043b\u044c\u043d\u0443\u044e \u043e\u0444\u043b\u0430\u0439\u043d-\u0431\u0430\u0437\u0443 \u0434\u0430\u043d\u043d\u044b\u0445 BIN \u0434\u043b\u044f \u0431\u044b\u0441\u0442\u0440\u043e\u0433\u043e \u0438 \u043d\u0430\u0434\u0435\u0436\u043d\u043e\u0433\u043e \u043e\u043f\u0440\u0435\u0434\u0435\u043b\u0435\u043d\u0438\u044f \u0431\u0430\u043d\u043a\u0430 \u0438 \u0441\u0442\u0440\u0430\u043d\u044b \u0431\u0435\u0437 \u043d\u0435\u043e\u0431\u0445\u043e\u0434\u0438\u043c\u043e\u0441\u0442\u0438 \u0432 API-\u043a\u043b\u044e\u0447\u0430\u0445 \u0438\u043b\u0438 \u0434\u043e\u0441\u0442\u0443\u043f\u0435 \u0432 \u0438\u043d\u0442\u0435\u0440\u043d\u0435\u0442.\r\n</details>\r\n\r\n---\r\n\r\n## Key Features\r\n\r\n- **Generate Valid Cards**: Creates credit card numbers that pass the Luhn algorithm check for various schemes (Visa, MasterCard, Amex, Discover).\r\n- **Offline BIN Lookup**: Includes a local BIN database to retrieve card details like brand, type, country, and bank issuer.\r\n- **No Dependencies**: The core logic has zero external dependencies, making it lightweight and easy to integrate.\r\n- **No API Keys Required**: All lookups are performed locally, so you don't need to sign up for services or manage secret keys.\r\n- **Modern and Clean API**: Designed with clear, predictable methods and properties.\r\n- **Fully Typed**: Provides full type hinting for better autocompletion and static analysis.\r\n\r\n## Installation\r\n\r\nYou can install the library from PyPI using `pip` or any other modern package manager like `uv`.\r\n\r\n#### Using `pip`\r\n\r\n```bash\r\n# On Windows\r\npy -m pip install card_generator\r\n\r\n# On Linux/macOS\r\npython3 -m pip install card_generator\r\n```\r\n\r\n#### Using `uv`\r\n\r\n`uv` is an extremely fast, next-generation Python package installer.\r\n\r\n```bash\r\n# Install into your virtual environment (recommended)\r\nuv pip install card_generator\r\n\r\n# Or, if you need to install it system-wide (use with caution)\r\nuv pip install --system card_generator\r\n```\r\n\r\n## Usage Examples\r\n\r\nHere are some examples of how to use the library's main features.\r\n\r\n### 1. Generating Credit Cards\r\n\r\nUse the `CardGenerator` class to create one or more cards.\r\n\r\n```python\r\nfrom card_generator import CardGenerator\r\n\r\n# Initialize a generator for MasterCard\r\nmastercard_generator = CardGenerator(\"mastercard\")\r\n\r\n# Generate 3 standard cards\r\ncards = mastercard_generator.generate(count=3)\r\nprint(cards)\r\n```\r\n\r\n**Example Output:**\r\n\r\n```json\r\n[\r\n {\r\n \"card\": \"5486241234567890\",\r\n \"expiry_date\": \"07/28\",\r\n \"cvv\": 451\r\n },\r\n {\r\n \"card\": \"5179509876543210\",\r\n \"expiry_date\": \"11/29\",\r\n \"cvv\": 812\r\n },\r\n {\r\n \"card\": \"5543620011223344\",\r\n \"expiry_date\": \"02/27\",\r\n \"cvv\": 123\r\n }\r\n]\r\n```\r\n\r\n#### Generation with Options\r\n\r\nYou can generate cards with formatted numbers and include bank information.\r\n\r\n```python\r\nfrom card_generator import CardGenerator\r\nimport json\r\n\r\namex_generator = CardGenerator(\"amex\")\r\n\r\n# Generate 2 cards with formatting and bank info\r\npretty_cards = amex_generator.generate(\r\n count=2,\r\n beautiful_format=True,\r\n include_bank_info=True\r\n)\r\n\r\nprint(json.dumps(pretty_cards, indent=2))\r\n```\r\n\r\n**Example Output:**\r\n\r\n```json\r\n[\r\n {\r\n \"card\": \"3782 822463 10005\",\r\n \"expiry_date\": \"05/30\",\r\n \"cvv\": 8812,\r\n \"info\": {\r\n \"brand\": \"AMERICAN EXPRESS\",\r\n \"type\": \"CREDIT\",\r\n \"category\": \"\",\r\n \"country\": \"United States\",\r\n \"country_code\": \"US\",\r\n \"bank\": \"AMERICAN EXPRESS\",\r\n \"bank_url\": \"www.americanexpress.com\",\r\n \"bank_phone\": \"\"\r\n }\r\n },\r\n {\r\n \"card\": \"3412 345678 90127\",\r\n \"expiry_date\": \"12/28\",\r\n \"cvv\": 1234,\r\n \"info\": null\r\n }\r\n]\r\n```\r\n*(Note: `info` will be `null` if the generated BIN is not found in the local database.)*\r\n\r\n---\r\n\r\n### 2. Validating Credit Cards\r\n\r\nUse the `CardValidator` class to check card numbers and get details.\r\n\r\n```python\r\nfrom card_generator import CardValidator\r\n\r\n# A valid Visa card number\r\ncard_number = \"4539920412345671\"\r\n\r\n# Initialize the validator\r\nvalidator = CardValidator(card_number)\r\n\r\n# --- Check Validity ---\r\nprint(f\"Is Luhn valid? {validator.is_luhn_valid()}\")\r\n\r\n# --- Get Card Type ---\r\n# This is a property, not a method\r\nprint(f\"Card type: {validator.card_type}\")\r\n\r\n# --- Get All Available BIN Info ---\r\ninfo = validator.get_bin_info()\r\nprint(\"BIN Info:\")\r\nprint(info)\r\n```\r\n\r\n**Example Output:**\r\n\r\n```\r\nIs Luhn valid? True\r\nCard type: visa\r\nBIN Info:\r\n{'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'}\r\n```\r\n\r\n---\r\n\r\n## Acknowledgements / \u0418\u0441\u0442\u043e\u0447\u043d\u0438\u043a \u0434\u0430\u043d\u043d\u044b\u0445\r\n\r\nThis 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](https://creativecommons.org/licenses/by/4.0/).\r\n\r\n- **Source:** [github.com/venelinkochev/bin-list-data](https://github.com/venelinkochev/bin-list-data)\r\n\r\n---\r\n\r\n\u042d\u0442\u043e\u0442 \u043f\u0440\u043e\u0435\u043a\u0442 \u0438\u0441\u043f\u043e\u043b\u044c\u0437\u0443\u0435\u0442 \u0434\u0430\u043d\u043d\u044b\u0435 \u0438\u0437 \u0441\u043f\u0438\u0441\u043a\u0430 BIN, \u043f\u0440\u0435\u0434\u043e\u0441\u0442\u0430\u0432\u043b\u0435\u043d\u043d\u044b\u0435 \u043f\u0440\u043e\u0435\u043a\u0442\u043e\u043c `bin-list-data` \u043f\u043e\u0434 \u0440\u0443\u043a\u043e\u0432\u043e\u0434\u0441\u0442\u0432\u043e\u043c venelinkochev \u0438 \u0435\u0433\u043e \u0441\u043e\u0430\u0432\u0442\u043e\u0440\u043e\u0432. \u0414\u0430\u043d\u043d\u044b\u0435 \u0440\u0430\u0441\u043f\u0440\u043e\u0441\u0442\u0440\u0430\u043d\u044f\u044e\u0442\u0441\u044f \u043f\u043e \u043b\u0438\u0446\u0435\u043d\u0437\u0438\u0438 [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/).\r\n\r\n- **\u0418\u0441\u0442\u043e\u0447\u043d\u0438\u043a:** [github.com/venelinkochev/bin-list-data](https://github.com/venelinkochev/bin-list-data)\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A library to generate and validate credit card numbers with local BIN lookup.",
"version": "0.1.6",
"project_urls": {
"Bug Tracker": "https://github.com/NjProVk/CreditsCardTools/issues",
"Homepage": "https://github.com/NjProVk/CreditsCardTools"
},
"split_keywords": [
"credit card",
" card generator",
" card validator",
" luhn",
" luhn algorithm",
" bin",
" bin lookup",
" bin checker",
" iin",
" generate",
" generator",
" validate",
" validator",
" validation",
" visa",
" mastercard",
" amex",
" discover",
" fintech",
" payment",
" ecommerce",
" test data",
" mock data",
" fake data",
" offline",
" no-api",
" local-database"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ea7d791fee65314e36818ab9734f8b677d7d8ac310ffa312f7a66dd55aa8f353",
"md5": "60002819a764b7cf9392d09f52a72d51",
"sha256": "aeeb005590b67598df98039209102cbb4afafd79c9f4a5f54e27e2e7fbc91978"
},
"downloads": -1,
"filename": "card_generator-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "60002819a764b7cf9392d09f52a72d51",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 3354845,
"upload_time": "2025-08-03T10:39:11",
"upload_time_iso_8601": "2025-08-03T10:39:11.594346Z",
"url": "https://files.pythonhosted.org/packages/ea/7d/791fee65314e36818ab9734f8b677d7d8ac310ffa312f7a66dd55aa8f353/card_generator-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3bf2cb15e4894f97575ed8119184dc9974ff832a5562837f2cd4c5641f2961f2",
"md5": "f7ceb30dc9fc708980cf50143842ce81",
"sha256": "864097c1e23c28d058ba00b057db822aaaf98072f8fa7b5bd6ce814442e35b90"
},
"downloads": -1,
"filename": "card_generator-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "f7ceb30dc9fc708980cf50143842ce81",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3211175,
"upload_time": "2025-08-03T10:39:13",
"upload_time_iso_8601": "2025-08-03T10:39:13.379153Z",
"url": "https://files.pythonhosted.org/packages/3b/f2/cb15e4894f97575ed8119184dc9974ff832a5562837f2cd4c5641f2961f2/card_generator-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 10:39:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NjProVk",
"github_project": "CreditsCardTools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "card-generator"
}
JSON
