bin2binМенеджер
How-to с кодом· 3 мин чтения

Как в песочнице создать счёт, пополнить баланс и поймать вебхук

Практический разбор тестового API bin2bin: доступ, подпись вебхука, создание счёта и выпуск карты с баланса. С примерами curl и фрагментом на Node.js.

Песочница bin2bin нужна не для «потыкать интерфейс», а чтобы пройти тот же цикл, который потом окажется в боевом контуре: счёт, пополнение баланса, карта, событие у вас на сервере. Ниже — практическая последовательность. Все адреса и поля совпадают с открытой документацией. Базовый URL: https://bin2bin.cards/api/v1.

Открытой регистрации в песочнице нет. Сначала напишите @bin2bin_cards, менеджер выдаёт ключ доступа на почту. В самой песочнице вы выпускаете тестовый ключ b2b_sk_test_… — он показывается один раз.

Серверные узлы, поток данных, телефон и карта

1. Проверьте ключ

Сохраните ключ в переменную окружения и запросите /whoami. В ответе будут режим test, счётчики объектов и лимиты (60 запросов в минуту, лимиты на держателей и карты).

bash
export B2B_KEY="b2b_sk_test_…"

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

Потерянный ключ восстановить нельзя: хранится только SHA-256 хэш. Выпустите новый и отзовите старый.

2. Настройте вебхук и сохраните секрет

Укажите публичный HTTPS-адрес на стандартном порту. В ответе придёт секрет подписи. Он показывается один раз; каждый новый PUT выпускает новый секрет.

bash
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"}'

Доставка — POST с JSON-телом вида:

json
{
  "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 минут лучше отклонять. Ответьте кодом 2xx за 5 секунд: повторов в песочнице нет.

Фрагмент проверки на Node.js. Важно брать именно сырое тело запроса, а не сериализованный заново JSON:

js
import crypto from "node:crypto";

export function verifyBin2binSignature(signatureHeader, rawBody, secret) {
  const parts = Object.fromEntries(
    String(signatureHeader || "")
      .split(",")
      .map((chunk) => {
        const i = chunk.indexOf("=");
        return [chunk.slice(0, i), chunk.slice(i + 1)];
      }),
  );

  const ts = Number(parts.t);
  const digest = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(parts.sha256 || "", "utf8");
  const b = Buffer.from(digest, "utf8");
  const fresh = Math.abs(Date.now() / 1000 - ts) <= 5 * 60;

  return (
    Number.isFinite(ts) &&
    a.length === b.length &&
    crypto.timingSafeEqual(a, b) &&
    fresh
  );
}

Проверить доставку без создания счёта можно так: curl -X POST https://bin2bin.cards/api/v1/webhook/test -H "Authorization: Bearer $B2B_KEY". На адрес уйдёт событие ping.

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

Счёт появляется в статусе pending. Через 5 секунд он сам становится paid, сумма зачисляется на тестовый баланс USD, на вебхук уходит invoice.paid. Суммы в API передаются в центах: 150000 — это 1 500.00 USD.

bash
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":"Тестовая оплата"}'

В ответе будет id и pay_url. Страница оплаты в песочнице ничего не списывает: она показывает, как выглядит ссылка для клиента. Через пять секунд проверьте статус и баланс:

bash
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"

Если вебхук настроен, к этому моменту на вашем сервере уже должно лежать событие invoice.paid с тем же объектом счёта.

Цепочка: счёт, баланс, выпуск карты

4. Выпустите карту с баланса

Карты создаются только через API. Укажите БИН из GET /api/v1/bins и, при желании, стартовую сумму с тестового баланса.

bash
curl https://bin2bin.cards/api/v1/bins \
  -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","nickname":"Основная","initial_amount_cents":5000}'

Если баланса не хватает, придёт 409 insufficient_balance. Дальше можно пополнить карту (POST /api/v1/cards/{id}/topups) или имитировать покупку (simulate-purchase с каналом contactless или без него). Операция создаётся всегда: либо approved, либо declined с причиной.

Частые ошибки на этом пути

Симптом Что проверить
401 key_missing / key_invalid Заголовок Authorization: Bearer … и сам ключ
401 key_revoked Ключ отозван, нужен новый
409 webhook_missing Сначала PUT /webhook, если метод требует настроенный адрес
Вебхук «не пришёл» Логи вашего сервера, ответ не 2xx или дольше 5 секунд, секрет от старого PUT
409 insufficient_balance Сначала дождитесь invoice.paid и проверьте GET /balance
429 Лимит 60 запросов в минуту, смотрите Retry-After

Когда цикл в песочнице проходит стабильно, его же можно обсуждать как основу боевой интеграции. Боевые ключи самостоятельно не выпускаются — их выдаёт менеджер. Если доступа к песочнице ещё нет, напишите @bin2bin_cards.

Обсудить свой карточный продукт

Напишите менеджеру в Telegram. Расскажем о подключении «Под ключ», подберём сценарий под вашу аудиторию и откроем песочницу после одобрения заявки.

Написать @bin2bin_cards

Читайте также