Русский · English
Готовые примеры работы с API BIN Lookup на шести языках: Python, TypeScript (Node.js), Go, Java, C#, PHP. Определить банк по номеру карты — по первым 6–8 цифрам (BIN / IIN) узнать платёжную систему, тип и категорию карты, банк-эмитент, страну карты и валюту. Плюс антифрод по карте: сверка страны карты со страной IP плательщика.
Каждый пример запускается сразу — без регистрации, без ключа, без карты. В коде зашит публичный демо-ключ.
git clone https://github.com/atlorium-api/bin-lookup-api-client
cd bin-lookup-api-client/python && pip install -r requirements.txt && python main.py 45717360 8.8.8.8Демо-ключ: ответы сгенерированы (моки), не реальные данные.
BIN 45717360 · MASTERCARD · CHARGE CARD · STANDARD
Эмитент: ВИНОГРАДОВА - ДОРОФЕЕВ BANK
Страна карты: RUSSIAN FEDERATION (RU) · Валюта: RUB
Контакты банка: https://алла.info · +7 127 780-36-14
IP плательщика: RUSSIAN FEDERATION (RU), Рязань — страна совпадает со страной карты
Риск-факторов не обнаружено.
[i] Потребительская карта
[i] Категория: STANDARD
Демо-ключ отвечает правдоподобными моками, а не реальными данными справочника — поэтому название банка в примере выше выглядит сгенерированным. Так и задумано: интеграцию можно написать и протестировать до оплаты. Подставьте боевой ключ — тот же код начнёт возвращать настоящие данные об эмитенте.
Отправляйте первые 6–8 цифр. Полный номер карты (PAN) не должен покидать ваш периметр.
Это не формальность, а базовая гигиена PCI DSS: BIN не является данными держателя карты, а полный PAN — является, и его нельзя логировать, пересылать в сторонние сервисы и хранить без сертификации.
Поэтому во всех шести примерах есть функция normalizeBin(), которая обрезает вход до 8 цифр перед отправкой. Даже если в неё случайно прилетит полный PAN из формы чекаута, наружу уйдёт только BIN:
python main.py 4571736012345678 # в сеть уйдёт GET /api/bin/45717360Антифрод на чекауте, маршрутизация платежей (выбрать эквайера по стране и платёжной системе), UX формы оплаты (подставить иконку платёжной системы, включить 3-D Secure), аналитика по типам карт, отсечение предоплаченных карт в подписочных сервисах.
Примеры не просто печатают JSON, а применяют данные: в каждом есть функция assessCheckoutRisk(), которая по карточке BIN и IP плательщика выносит вердикт — совпадает ли страна карты со страной IP (классический признак фрода), не предоплаченная ли это карта (повышенный риск чарджбэка), не в списках ли блокировок IP, известен ли эмитент, потребительская карта или корпоративная.
Проверить API вообще без клонирования:
curl -H "Authorization: Bearer ak_sandbox_demo_mockdata_v1" \
"https://atlorium.com/api/bin/45717360?customerIp=8.8.8.8"| Язык | Запуск | Требуется |
|---|---|---|
| Python | pip install -r requirements.txt && python main.py |
Python 3.10+ |
| TypeScript / Node.js | npm install && npm start |
Node.js 20+ |
| Go | go run . |
Go 1.22+ |
| Java | java Main.java |
JDK 17+ (без зависимостей) |
| C# | dotnet run |
.NET 8+ |
| PHP | php main.php |
PHP 8.1+ |
Передать свой BIN и IP плательщика аргументами: python main.py 48334884 8.8.8.8
Ключ передаётся в заголовке Authorization:
Authorization: Bearer ВАШ_КЛЮЧ
| Ключ | Что делает |
|---|---|
ak_sandbox_demo_mockdata_v1 |
Демо-ключ. Публичный, один на всех. Возвращает моки, денег не списывает, регистрации не требует. Ответы детерминированы — на них можно писать стабильные тесты. |
| Боевой ключ | Реальные данные справочника BIN. Получить в личном кабинете: atlorium.com |
Переход на боевой ключ не требует правок в коде — все примеры читают переменную окружения:
export ATLORIUM_API_KEY="ak_ваш_боевой_ключ"Каждый ответ песочницы помечен заголовком X-Atlorium-Sandbox: true — перепутать мок с реальными данными невозможно.
Базовый адрес: https://atlorium.com
| Метод | Путь | Назначение |
|---|---|---|
GET |
/api/bin/{bin} |
Карточка карты по BIN/IIN + антифрод-проверка по IP плательщика |
GET |
/api/bin/validate/{bin} |
Проверка формата BIN (только цифры, длина 6/8/10) |
| Параметр | Где | Тип | Описание |
|---|---|---|---|
bin |
путь | string | BIN/IIN — первые 6, 8 или 10 цифр номера карты. Чем длиннее, тем точнее определение эмитента; 8 цифр — разумный компромисс между точностью и PCI-гигиеной. |
customerIp |
query | string | (Необязательно) IP-адрес плательщика. Если передан — в ответ добавляются антифрод-поля: страна/город по IP, совпадение страны IP со страной карты, проверка по спискам блокировок. |
| Параметр | Где | Тип | Описание |
|---|---|---|---|
bin |
путь | string | Проверяемый BIN (6, 8 или 10 цифр; пробелы и разделители игнорируются) |
Проверяется формат, а не существование BIN: isValidFormat: true не означает, что банк-эмитент найдётся.
| Поле | Тип | Что содержит |
|---|---|---|
valid |
bool | Ключевое поле. Найден ли BIN в справочнике |
binNumber |
string | BIN, по которому выполнялся поиск |
binLength |
int | Длина BIN: 6, 8 или 10 |
cardBrand |
string | Платёжная система: VISA, MASTERCARD, MIR… |
cardType |
string | Тип карты: DEBIT, CREDIT, CHARGE CARD… |
cardCategory |
string | Категория: STANDARD, GOLD, PLATINUM, BUSINESS… |
country / countryCode / countryCode3 |
string | Страна карты: название, ISO-2, ISO-3 |
currencyCode |
string | Валюта карты, ISO-4217 |
issuer |
string | Банк-эмитент |
issuerWebsite / issuerPhone |
string | Сайт и телефон банка |
isCommercial |
bool | Коммерческая (корпоративная) карта, а не потребительская |
isPrepaid |
bool | Признак риска. Предоплаченная (в т.ч. виртуальная) карта |
isReloadable |
bool | Можно ли пополнять. false у одноразовых карт |
hasCustomerIp |
bool | Был ли передан customerIp — то есть заполнены ли поля ниже |
ipMatchesBin |
bool | Главный антифрод-флаг. Страна IP плательщика совпадает со страной карты |
ipCountry / ipCountryCode / ipCountryCode3 |
string | Страна по IP плательщика |
ipRegion / ipCity |
string | Регион и город по IP |
ipBlocklisted |
bool | IP найден в списках блокировок |
ipBlocklists |
array | В каких именно списках |
elapsedMs |
int | Время обработки запроса на нашей стороне, мс |
| Поле | Тип | Что содержит |
|---|---|---|
normalizedBin |
string | BIN после очистки от пробелов и разделителей |
isValidFormat |
bool | Формат корректен (только цифры, длина 6/8/10) |
binLength |
int | Длина нормализованного BIN |
message |
string | Текстовое пояснение результата |
| Код | Причина | Что делать |
|---|---|---|
400 |
Неверный формат BIN | Должны быть 6, 8 или 10 цифр, только цифры |
401 |
Ключ отсутствует, просрочен или недействителен | Проверьте заголовок Authorization |
402 |
Недостаточно кредитов на балансе | Пополнить на atlorium.com |
404 |
BIN не найден в справочнике | Формат верный, но такой записи нет |
429 |
Превышен rate-limit | Повторить с задержкой |
503 |
Сервис временно недоступен | Повторить позже. За сбой на нашей стороне деньги не списываются |
Обратите внимание: если BIN синтаксически корректен, но отсутствует в справочнике, эндпоинт отвечает 200 OK с valid: false — это не ошибка. Во всех шести примерах коды разложены в человекочитаемые причины — смотрите класс AtloriumError.
Оплата pay-as-you-go, без подписки: платите только за выполненные запросы. Актуальные тарифы и лимиты — на atlorium.com/pricing.
Актуальные цены и лимиты: atlorium.com/pricing
Откуда данные? Из справочника BIN/IIN платёжных систем и банков-эмитентов, дополненного гео-базой IP для антифрод-проверки.
Сколько цифр отправлять — 6, 8 или 10? BIN исторически 6 цифр, но платёжные системы перешли на 8-значные BIN, и по шести цифрам эмитент определяется грубее. Рекомендуем 8. Десять цифр API принимает, но это уже больше половины номера карты — с точки зрения PCI-гигиены лишний риск при незначительном приросте точности.
Можно ли отправить полный номер карты? Технически API возьмёт первые цифры, но делать так не нужно. Обрезайте PAN на своей стороне: в примерах за это отвечает normalizeBin(). Полный номер карты — данные держателя, их нельзя передавать по сети без нужды.
Определяет ли сервис, что карта настоящая и на ней есть деньги? Нет, и это важная граница. BIN Lookup отвечает на вопрос «что это за карта и чей это банк», а не «действительна ли карта, не украдена ли она, хватит ли баланса». Проверка карты на валидность — задача эквайера и алгоритма Луна, проверка баланса — авторизационного запроса.
Что означает ipMatchesBin: false? Что карта выпущена в одной стране, а платёж идёт с IP другой. Это признак риска, а не приговор: так выглядят туристы, экспаты, релоканты и пользователи VPN. Используйте флаг как один из сигналов скоринга, а не как единственную причину отказа.
Чем это отличается от бесплатных BIN-баз? Открытые базы обновляются нерегулярно и не покрывают новые 8-значные BIN, а антифрод-проверки по IP в них нет вовсе. Здесь оба сигнала приходят одним запросом, с SLA и без ограничений на коммерческое использование.
Обязательна ли регистрация, чтобы попробовать? Нет. Демо-ключ публичный и работает без аккаунта — но возвращает моки, а не реальные данные.
Антифрод на чекауте редко ограничивается картой. Из того же аккаунта и тем же ключом доступны:
- AML-скоринг криптокошелька — риск-балл, санкции, PEP
- SWIFT/BIC — разбор кода по ISO-9362 и сверка перед международным переводом
- Профиль IP — гео, ASN, детект VPN, прокси и Tor
- Справочник БИК ЦБ РФ — реквизиты банка и контрольный ключ расчётного счёта
- CIDR-калькулятор — разбиение сети на подсети и проверка вхождения IP
- ЕГРЮЛ/ЕГРИП — проверка контрагента по ИНН/ОГРН: статус, адрес, капитал
Полный каталог — atlorium.com
- Документация API (Swagger): atlorium.com/binAPI
- Описание сервиса: atlorium.com/binDescription
- Веб-интерфейс: atlorium.com/binGUI
- OpenAPI-спецификация: bin_ru.json
- Поддержка: support@atlorium.com
MIT — берите код и используйте как хотите, в том числе в коммерческих проектах.