Документация API
API bin2bin позволяет создавать держателей, выпускать карты на выбранных БИНах, пополнять их и получать операции. Всё на этой странице можно проверить в песочнице: примеры curl работают с тестовым ключом.
Быстрый старт
- 01Получите доступМенеджер одобряет заявку и присылает ключ доступа
b2b_access_…. - 02Войдите в песочницуНа странице /sandbox по ключу доступа. Регистрации нет.
- 03Выпустите API-ключКлюч
b2b_sk_test_…показывается один раз. - 04Работайте через APIСчета, баланс, карты и вебхуки — только через API.
export B2B_KEY="b2b_sk_test_…" # ключ из песочницы curl https://bin2bin.cards/api/v1/whoami \ -H "Authorization: Bearer $B2B_KEY"
Тестовый счёт за 5 секунд
Главный сценарий песочницы: создать счёт, дождаться его автоматической оплаты и потратить баланс. Счёт создаётся в статусе pending, через 5 секунд становится paid, сумма зачисляется на тестовый баланс, а на ваш вебхук уходит подписанное событие invoice.paid.
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"}'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":"Тестовая оплата"}'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"
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.
Справочник и проверка ключа
Список БИНов и сведения о вашей песочнице.
/api/v1/binsЧетыре доступных БИНа с типом использования.
curl https://bin2bin.cards/api/v1/bins \ -H "Authorization: Bearer $B2B_KEY"
/api/v1/whoamiРежим ключа, счётчики объектов и лимиты.
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.
/api/v1/invoicesСоздать тестовый счёт.
| amount_cents | integer, обязательно | Сумма в минимальных единицах: 150000 = 1 500.00 |
| currency | string | USD (по умолчанию), EUR или RUB |
| description | string | Назначение платежа, до 200 символов |
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"
}/api/v1/invoicesСписок счетов, новые сверху. Фильтр: status (pending | paid). Плюс limit, after.
curl "https://bin2bin.cards/api/v1/invoices?status=paid" \ -H "Authorization: Bearer $B2B_KEY"
/api/v1/invoices/{id}Один счёт. Через 5 секунд после создания status = paid.
curl https://bin2bin.cards/api/v1/invoices/inv_3f9a1c0b7e21a4d08c6e19b2f7d3 \ -H "Authorization: Bearer $B2B_KEY"
/api/v1/balanceТестовый баланс по валютам: доступно и ожидает оплаты.
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"
}Держатели
Держатель — ваш клиент, на которого выпускаются карты.
/api/v1/holdersСоздать держателя.
| full_name | string, обязательно | Имя, от 2 до 80 символов |
| telegram | string | Username вида @name |
| external_ref | string | Ваш внутренний id, уникален в песочнице |
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"
}/api/v1/holdersСписок держателей, новые сверху. Параметры: limit, after.
curl "https://bin2bin.cards/api/v1/holders?limit=10" \ -H "Authorization: Bearer $B2B_KEY"
/api/v1/holders/{id}Один держатель.
curl https://bin2bin.cards/api/v1/holders/hld_5d2e8a10c4b7f913 \ -H "Authorization: Bearer $B2B_KEY"
Карты
Карта выпускается мгновенно и всегда тестовая. БИН сохраняется как метаданные, номер — из тестового диапазона. Деньги на карту переводятся с тестового баланса USD.
/api/v1/cardsВыпустить тестовую карту.
| bin | string, обязательно | Один из БИНов: 525847, 441357, 442601, 493724 |
| holder_id | string | Держатель; без него карта создаётся без владельца |
| nickname | string | Подпись карты, до 40 символов |
| initial_amount_cents | integer | Сразу перевести на карту с баланса USD |
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"
}/api/v1/cardsСписок карт. Фильтры: holder_id, status (active | frozen), bin. Плюс limit, after.
curl "https://bin2bin.cards/api/v1/cards?status=active&limit=20" \ -H "Authorization: Bearer $B2B_KEY"
/api/v1/cards/{id}Одна карта.
curl https://bin2bin.cards/api/v1/cards/crd_a81f03c2d9e64b70 \ -H "Authorization: Bearer $B2B_KEY"
/api/v1/cards/{id}/freezeЗаморозить карту. Повторный вызов ничего не меняет.
curl -X POST https://bin2bin.cards/api/v1/cards/crd_a81f03c2d9e64b70/freeze \ -H "Authorization: Bearer $B2B_KEY"
/api/v1/cards/{id}/unfreezeРазморозить карту.
curl -X POST https://bin2bin.cards/api/v1/cards/crd_a81f03c2d9e64b70/unfreeze \ -H "Authorization: Bearer $B2B_KEY"
Пополнение карты и покупки
Деньги в песочнице симулированы. Суммы — целые центы USD: 2500 = 25.00 $. Пополнение карты списывает тестовый баланс USD.
/api/v1/cards/{id}/topupsПеревести деньги с тестового баланса USD на карту. Не хватает баланса — 409 insufficient_balance, карта заморожена — 409 card_frozen.
| amount_cents | integer, обязательно | От 1 до 1 000 000 |
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}'/api/v1/cards/{id}/simulate-purchaseИмитация покупки по карте. Всегда создаёт операцию: approved или declined с причиной.
| amount_cents | integer, обязательно | Сумма покупки |
| merchant | string | Название магазина |
| channel | string | online (по умолчанию) или contactless |
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"
}/api/v1/transactionsОперации, новые сверху. Фильтры: card_id, kind (topup | purchase). Плюс limit, after.
curl "https://bin2bin.cards/api/v1/transactions?card_id=crd_a81f03c2d9e64b70" \ -H "Authorization: Bearer $B2B_KEY"
Вебхук
Один адрес на песочницу. Подробности о событиях и подписи — в разделе «Вебхуки».
/api/v1/webhookЗадать адрес. В ответе — секрет для проверки подписи; он показывается один раз, при каждом PUT выпускается новый.
| url | string, обязательно | https:// на стандартном порту, публичный домен |
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"}'/api/v1/webhookТекущий адрес и 10 последних доставок.
curl https://bin2bin.cards/api/v1/webhook \ -H "Authorization: Bearer $B2B_KEY"
/api/v1/webhook/testОтправить тестовое событие ping и вернуть результат доставки.
curl -X POST https://bin2bin.cards/api/v1/webhook/test \ -H "Authorization: Bearer $B2B_KEY"
/api/v1/webhookОтключить вебхук.
curl -X DELETE https://bin2bin.cards/api/v1/webhook \ -H "Authorization: Bearer $B2B_KEY"
Тестовые карты
Тестовые карты нужны только для проверки интеграции. Для реальных платежей они непригодны.
- Выбранный БИН хранится в поле
binкак метаданные. Номер карты на реальном БИНе не выпускается. - Номер берётся из тестового диапазона:
400000…для Visa и510000…для Mastercard. - Контрольная цифра намеренно неверная: номер не проходит проверку Луна, и платёжные системы его не примут.
- CVV всегда
000, у каждой карты"test": true. - Карты выпускаются только через API:
POST /api/v1/cards.
Как ведёт себя simulate-purchase:
| Условие | Результат |
|---|---|
| Карта заморожена | declined · card_frozen |
channel: contactless на БИНе «Только онлайн» | declined · channel_not_supported |
| Сумма больше баланса | declined · insufficient_funds |
| Иначе | approved, баланс уменьшается |
Вебхуки
Когда что-то меняется, песочница отправляет POST на ваш адрес. Ответьте любым кодом 2xx в течение 5 секунд — иначе доставка считается неуспешной (её видно в GET /api/v1/webhook). Повторов в песочнице нет.
invoice.createdinvoice.paidcard.issuedcard.frozen / card.unfrozentransaction.createdping{
"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 минут.
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"
}| HTTP | code | Когда |
|---|---|---|
| 400 | body_not_json | Тело запроса — не JSON-объект |
| 401 | key_missing | Нет заголовка Authorization: Bearer … |
| 401 | key_invalid | Ключ не распознан или не найден |
| 401 | key_revoked | Ключ отозван в песочнице |
| 403 | live_key_here | Боевой ключ отправлен на тестовый адрес |
| 404 | not_found | Объект не найден в вашей песочнице |
| 404 | unknown_route | Такого адреса нет |
| 405 | method_not_supported | Метод не поддерживается для адреса |
| 409 | card_frozen | Действие недоступно для замороженной карты |
| 409 | insufficient_balance | На тестовом балансе USD не хватает средств |
| 409 | duplicate | Повтор уникального значения (external_ref) |
| 409 | sandbox_limit | Достигнут лимит объектов песочницы |
| 409 | webhook_missing | Вебхук ещё не настроен |
| 413 | body_too_large | Тело больше 16 КБ |
| 422 | invalid_param | Неверное значение; поле указано в param |
| 429 | too_many_requests | Больше 60 запросов в минуту на ключ |
| 500 | server_error | Внутренняя ошибка — повторите запрос |
БИНы
В тариф «Под ключ» входят все 4 БИНа. Карты с бесконтактной оплатой работают и онлайн. Тот же список отдаёт GET /api/v1/bins.
| БИН | Система | Тип | Где работает |
|---|---|---|---|
| 525847 | Бесконтактная оплата | Оплата телефоном в магазинах, работает и онлайн | |
| 441357 | VISA | Бесконтактная оплата | Оплата телефоном в магазинах, работает и онлайн |
| 442601 | VISA | Бесконтактная оплата | Оплата телефоном в магазинах, работает и онлайн |
| 493724 | VISA | Только онлайн | Оплата в интернете и подписки |
Боевые ключи выдаёт менеджер после договора. Почта: connect@bin2bin.cards