bin2binМенеджер
API v1 · Русский

Документация API

API bin2bin позволяет создавать держателей, выпускать карты на выбранных БИНах, пополнять их и получать операции. Всё на этой странице можно проверить в песочнице: примеры curl работают с тестовым ключом.

Быстрый старт

Песочница доступна после одобрения заявки менеджером
Напишите менеджеру — после одобрения он выдаст ключ доступа на вашу почту.
Написать @bin2bin_cards
  1. 01
    Получите доступ
    Менеджер одобряет заявку и присылает ключ доступа b2b_access_….
  2. 02
    Войдите в песочницу
    На странице /sandbox по ключу доступа. Регистрации нет.
  3. 03
    Выпустите API-ключ
    Ключ b2b_sk_test_… показывается один раз.
  4. 04
    Работайте через API
    Счета, баланс, карты и вебхуки — только через API.
bash
export B2B_KEY="b2b_sk_test_…"   # ключ из песочницы

curl https://bin2bin.cards/api/v1/whoami \
  -H "Authorization: Bearer $B2B_KEY"

Тестовый счёт за 5 секунд

Главный сценарий песочницы: создать счёт, дождаться его автоматической оплаты и потратить баланс. Счёт создаётся в статусе pending, через 5 секунд становится paid, сумма зачисляется на тестовый баланс, а на ваш вебхук уходит подписанное событие invoice.paid.

1. Укажите вебхук (по желанию)
curl -X PUT https://bin2bin.cards/api/v1/webhook \
  -H "Authorization: Bearer $B2B_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/bin2bin"}'
2. Создайте счёт — status: pending
curl -X POST https://bin2bin.cards/api/v1/invoices \
  -H "Authorization: Bearer $B2B_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":150000,"currency":"USD","description":"Тестовая оплата"}'
3. Через 5 секунд — status: paid, баланс пополнен
sleep 5
curl https://bin2bin.cards/api/v1/invoices/<id счёта> -H "Authorization: Bearer $B2B_KEY"
curl https://bin2bin.cards/api/v1/balance -H "Authorization: Bearer $B2B_KEY"
4. Выпустите карту с баланса
curl -X POST https://bin2bin.cards/api/v1/cards \
  -H "Authorization: Bearer $B2B_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bin":"525847","initial_amount_cents":5000}'

У счёта есть pay_url — тестовая страница со статусом. Она ничего не списывает и нужна только чтобы показать клиенту, как выглядит ссылка на оплату.

Ключи и авторизация

Каждый запрос передаёт ключ в заголовке Authorization: Bearer <ключ>. Мы храним только SHA-256 хэш ключа, поэтому восстановить потерянный ключ нельзя — выпустите новый и отзовите старый. Отозванный ключ сразу получает 401 key_revoked.

Лимит — 60 запросов в минуту на ключ. В ответах есть заголовки X-RateLimit-Limit и X-RateLimit-Remaining; при превышении приходит 429 с заголовком Retry-After в секундах. Активных ключей может быть до 10.

Песочница и боевой режим

Песочница
  • Доступ выдаёт менеджер после одобрения заявки
  • Ключи b2b_sk_test_ выпускаете сами в песочнице
  • Счета, баланс, карты и операции симулированы
  • Данные видны только вам
  • Каждый объект содержит "test": true
Боевой режим
  • Ключи b2b_sk_live_ самостоятельно не выпускаются
  • Их выдаёт менеджер после договора и оплаты подключения
  • Связь: @bin2bin_cards в Telegram или connect@bin2bin.cards

Адрес https://bin2bin.cards/api/v1 работает только в тестовом режиме: боевой ключ на нём получит 403 live_key_here.

Формат ответов

Все ответы — JSON. Успешный ответ кладёт данные в result, ошибка — в problem. В обоих случаях есть request_id (он же в заголовке X-Request-Id) — укажите его, если пишете в поддержку.

Список с постраничной выдачей
{
  "result": [ { "id": "crd_…" }, … ],
  "page": { "has_more": true, "next_after": "crd_a81f03c2d9e64b70" },
  "request_id": "req_…"
}

Списки отдают новые объекты первыми. limit — от 1 до 100 (по умолчанию 20). Следующая страница — с параметром after, равным page.next_after. Суммы — целые числа в центах (amount_cents), время — ISO 8601 в UTC.

Ресурсы

Базовый адрес: https://bin2bin.cards/api/v1. Тело запросов — JSON, заголовок Content-Type: application/json.

Справочник и проверка ключа

Список БИНов и сведения о вашей песочнице.

GET/api/v1/bins

Четыре доступных БИНа с типом использования.

curl
curl https://bin2bin.cards/api/v1/bins \
  -H "Authorization: Bearer $B2B_KEY"
GET/api/v1/whoami

Режим ключа, счётчики объектов и лимиты.

curl
curl https://bin2bin.cards/api/v1/whoami \
  -H "Authorization: Bearer $B2B_KEY"
Ответ
{
  "result": {
    "partner_id": "prt_3f9a1c0b7e21",
    "mode": "test",
    "holders": 0,
    "cards": 0,
    "transactions": 0,
    "webhook_configured": false,
    "limits": { "requests_per_minute": 60, "holders": 200, "cards": 300 }
  },
  "request_id": "req_9c1e0f5a7b3d"
}

Баланс и тестовые счета

Тестовый счёт создаётся в статусе pending и через 5 секунд сам становится paid: сумма зачисляется на тестовый баланс, на вебхук уходит invoice.paid.

POST/api/v1/invoices

Создать тестовый счёт.

amount_centsinteger, обязательноСумма в минимальных единицах: 150000 = 1 500.00
currencystringUSD (по умолчанию), EUR или RUB
descriptionstringНазначение платежа, до 200 символов
curl
curl -X POST https://bin2bin.cards/api/v1/invoices \
  -H "Authorization: Bearer $B2B_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":150000,"currency":"USD","description":"Пополнение баланса"}'
Ответ
{
  "result": {
    "id": "inv_3f9a1c0b7e21a4d08c6e19b2f7d3",
    "type": "invoice",
    "test": true,
    "amount_cents": 150000,
    "currency": "USD",
    "description": "Пополнение баланса",
    "status": "pending",
    "pay_url": "https://bin2bin.cards/pay/test/inv_3f9a1c0b7e21a4d08c6e19b2f7d3",
    "created_at": "2026-11-16T10:30:00.000Z",
    "auto_pay_at": "2026-11-16T10:30:05.000Z",
    "paid_at": null
  },
  "request_id": "req_4c2a9e7d1b03"
}
GET/api/v1/invoices

Список счетов, новые сверху. Фильтр: status (pending | paid). Плюс limit, after.

curl
curl "https://bin2bin.cards/api/v1/invoices?status=paid" \
  -H "Authorization: Bearer $B2B_KEY"
GET/api/v1/invoices/{id}

Один счёт. Через 5 секунд после создания status = paid.

curl
curl https://bin2bin.cards/api/v1/invoices/inv_3f9a1c0b7e21a4d08c6e19b2f7d3 \
  -H "Authorization: Bearer $B2B_KEY"
GET/api/v1/balance

Тестовый баланс по валютам: доступно и ожидает оплаты.

curl
curl https://bin2bin.cards/api/v1/balance \
  -H "Authorization: Bearer $B2B_KEY"
Ответ
{
  "result": [
    { "currency": "USD", "available_cents": 150000, "pending_cents": 0 },
    { "currency": "EUR", "available_cents": 0, "pending_cents": 0 },
    { "currency": "RUB", "available_cents": 0, "pending_cents": 0 }
  ],
  "request_id": "req_8e1f0a6c2d57"
}

Держатели

Держатель — ваш клиент, на которого выпускаются карты.

POST/api/v1/holders

Создать держателя.

full_namestring, обязательноИмя, от 2 до 80 символов
telegramstringUsername вида @name
external_refstringВаш внутренний id, уникален в песочнице
curl
curl -X POST https://bin2bin.cards/api/v1/holders \
  -H "Authorization: Bearer $B2B_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Иван Петров","telegram":"@ivan_p","external_ref":"user-1001"}'
Ответ
{
  "result": {
    "id": "hld_5d2e8a10c4b7f913",
    "type": "holder",
    "test": true,
    "full_name": "Иван Петров",
    "telegram": "@ivan_p",
    "external_ref": "user-1001",
    "cards_count": 0,
    "created_at": "2026-11-16T10:20:31.402Z"
  },
  "request_id": "req_1b7c2d9e0a44"
}
GET/api/v1/holders

Список держателей, новые сверху. Параметры: limit, after.

curl
curl "https://bin2bin.cards/api/v1/holders?limit=10" \
  -H "Authorization: Bearer $B2B_KEY"
GET/api/v1/holders/{id}

Один держатель.

curl
curl https://bin2bin.cards/api/v1/holders/hld_5d2e8a10c4b7f913 \
  -H "Authorization: Bearer $B2B_KEY"

Карты

Карта выпускается мгновенно и всегда тестовая. БИН сохраняется как метаданные, номер — из тестового диапазона. Деньги на карту переводятся с тестового баланса USD.

POST/api/v1/cards

Выпустить тестовую карту.

binstring, обязательноОдин из БИНов: 525847, 441357, 442601, 493724
holder_idstringДержатель; без него карта создаётся без владельца
nicknamestringПодпись карты, до 40 символов
initial_amount_centsintegerСразу перевести на карту с баланса USD
curl
curl -X POST https://bin2bin.cards/api/v1/cards \
  -H "Authorization: Bearer $B2B_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bin":"441357","nickname":"Основная","initial_amount_cents":5000}'
Ответ
{
  "result": {
    "id": "crd_a81f03c2d9e64b70",
    "type": "card",
    "test": true,
    "holder_id": null,
    "bin": "441357",
    "network": "Visa",
    "usage": "contactless",
    "usage_label": "Бесконтактная оплата",
    "number": "4000 0062 9184 3307",
    "last4": "3307",
    "exp_month": 11,
    "exp_year": 2029,
    "cvv": "000",
    "status": "active",
    "balance_cents": 5000,
    "currency": "USD",
    "nickname": "Основная",
    "created_at": "2026-11-16T10:21:05.118Z",
    "note": "Тестовая карта песочницы. Для реальных платежей непригодна."
  },
  "request_id": "req_6e0d4c1a9b28"
}
GET/api/v1/cards

Список карт. Фильтры: holder_id, status (active | frozen), bin. Плюс limit, after.

curl
curl "https://bin2bin.cards/api/v1/cards?status=active&limit=20" \
  -H "Authorization: Bearer $B2B_KEY"
GET/api/v1/cards/{id}

Одна карта.

curl
curl https://bin2bin.cards/api/v1/cards/crd_a81f03c2d9e64b70 \
  -H "Authorization: Bearer $B2B_KEY"
POST/api/v1/cards/{id}/freeze

Заморозить карту. Повторный вызов ничего не меняет.

curl
curl -X POST https://bin2bin.cards/api/v1/cards/crd_a81f03c2d9e64b70/freeze \
  -H "Authorization: Bearer $B2B_KEY"
POST/api/v1/cards/{id}/unfreeze

Разморозить карту.

curl
curl -X POST https://bin2bin.cards/api/v1/cards/crd_a81f03c2d9e64b70/unfreeze \
  -H "Authorization: Bearer $B2B_KEY"

Пополнение карты и покупки

Деньги в песочнице симулированы. Суммы — целые центы USD: 2500 = 25.00 $. Пополнение карты списывает тестовый баланс USD.

POST/api/v1/cards/{id}/topups

Перевести деньги с тестового баланса USD на карту. Не хватает баланса — 409 insufficient_balance, карта заморожена — 409 card_frozen.

amount_centsinteger, обязательноОт 1 до 1 000 000
curl
curl -X POST https://bin2bin.cards/api/v1/cards/crd_a81f03c2d9e64b70/topups \
  -H "Authorization: Bearer $B2B_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":2500}'
POST/api/v1/cards/{id}/simulate-purchase

Имитация покупки по карте. Всегда создаёт операцию: approved или declined с причиной.

amount_centsinteger, обязательноСумма покупки
merchantstringНазвание магазина
channelstringonline (по умолчанию) или contactless
curl
curl -X POST https://bin2bin.cards/api/v1/cards/crd_a81f03c2d9e64b70/simulate-purchase \
  -H "Authorization: Bearer $B2B_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":990,"merchant":"Coffee Point","channel":"contactless"}'
Ответ
{
  "result": {
    "id": "txn_0c4e9b2a7f61d385",
    "type": "transaction",
    "test": true,
    "card_id": "crd_a81f03c2d9e64b70",
    "kind": "purchase",
    "status": "approved",
    "decline_code": null,
    "amount_cents": 990,
    "currency": "USD",
    "merchant": "Coffee Point",
    "channel": "contactless",
    "balance_after_cents": 1510,
    "created_at": "2026-11-16T10:22:47.903Z"
  },
  "request_id": "req_2f8a6d0c3e19"
}
GET/api/v1/transactions

Операции, новые сверху. Фильтры: card_id, kind (topup | purchase). Плюс limit, after.

curl
curl "https://bin2bin.cards/api/v1/transactions?card_id=crd_a81f03c2d9e64b70" \
  -H "Authorization: Bearer $B2B_KEY"

Вебхук

Один адрес на песочницу. Подробности о событиях и подписи — в разделе «Вебхуки».

PUT/api/v1/webhook

Задать адрес. В ответе — секрет для проверки подписи; он показывается один раз, при каждом PUT выпускается новый.

urlstring, обязательноhttps:// на стандартном порту, публичный домен
curl
curl -X PUT https://bin2bin.cards/api/v1/webhook \
  -H "Authorization: Bearer $B2B_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/bin2bin"}'
GET/api/v1/webhook

Текущий адрес и 10 последних доставок.

curl
curl https://bin2bin.cards/api/v1/webhook \
  -H "Authorization: Bearer $B2B_KEY"
POST/api/v1/webhook/test

Отправить тестовое событие ping и вернуть результат доставки.

curl
curl -X POST https://bin2bin.cards/api/v1/webhook/test \
  -H "Authorization: Bearer $B2B_KEY"
DELETE/api/v1/webhook

Отключить вебхук.

curl
curl -X DELETE https://bin2bin.cards/api/v1/webhook \
  -H "Authorization: Bearer $B2B_KEY"

Тестовые карты

Тестовые карты нужны только для проверки интеграции. Для реальных платежей они непригодны.

Как ведёт себя simulate-purchase:

УсловиеРезультат
Карта замороженаdeclined · card_frozen
channel: contactless на БИНе «Только онлайн»declined · channel_not_supported
Сумма больше балансаdeclined · insufficient_funds
Иначеapproved, баланс уменьшается

Вебхуки

Когда что-то меняется, песочница отправляет POST на ваш адрес. Ответьте любым кодом 2xx в течение 5 секунд — иначе доставка считается неуспешной (её видно в GET /api/v1/webhook). Повторов в песочнице нет.

invoice.created
Создан тестовый счёт
invoice.paid
Счёт оплачен, баланс пополнен (через 5 с)
card.issued
Выпущена карта
card.frozen / card.unfrozen
Изменился статус карты
transaction.created
Пополнение или покупка
ping
Тестовое событие из /webhook/test
Тело события
{
  "event_id": "evt_4b1e…",
  "event": "invoice.paid",
  "test": true,
  "sent_at": "2026-11-16T10:22:48.011Z",
  "data": { … объект счёта … }
}

Подпись — в заголовке X-B2B-Signature: t=<unix-время>,sha256=<hex>. Это HMAC-SHA256 от строки <t>.<сырое тело> с секретом из PUT /webhook. Отклоняйте события старше 5 минут.

Node.js — проверка подписи
import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.sha256));
}

Ошибки

Ошибка всегда приходит в одном виде. code — стабильный машинный код, message — пояснение на русском, param — поле, к которому относится ошибка (или null).

{
  "problem": {
    "code": "invalid_param",
    "message": "Поле amount_cents — целое число центов от 1 до 1000000.",
    "param": "amount_cents"
  },
  "request_id": "req_7d3a0e9c1f52"
}
HTTPcodeКогда
400body_not_jsonТело запроса — не JSON-объект
401key_missingНет заголовка Authorization: Bearer …
401key_invalidКлюч не распознан или не найден
401key_revokedКлюч отозван в песочнице
403live_key_hereБоевой ключ отправлен на тестовый адрес
404not_foundОбъект не найден в вашей песочнице
404unknown_routeТакого адреса нет
405method_not_supportedМетод не поддерживается для адреса
409card_frozenДействие недоступно для замороженной карты
409insufficient_balanceНа тестовом балансе USD не хватает средств
409duplicateПовтор уникального значения (external_ref)
409sandbox_limitДостигнут лимит объектов песочницы
409webhook_missingВебхук ещё не настроен
413body_too_largeТело больше 16 КБ
422invalid_paramНеверное значение; поле указано в param
429too_many_requestsБольше 60 запросов в минуту на ключ
500server_errorВнутренняя ошибка — повторите запрос

БИНы

В тариф «Под ключ» входят все 4 БИНа. Карты с бесконтактной оплатой работают и онлайн. Тот же список отдаёт GET /api/v1/bins.

БИНСистемаТипГде работает
525847Бесконтактная оплатаОплата телефоном в магазинах, работает и онлайн
441357VISAБесконтактная оплатаОплата телефоном в магазинах, работает и онлайн
442601VISAБесконтактная оплатаОплата телефоном в магазинах, работает и онлайн
493724VISAТолько онлайнОплата в интернете и подписки
Готовы к боевому подключению?

Боевые ключи выдаёт менеджер после договора. Почта: connect@bin2bin.cards

Написать @bin2bin_cards