Быстрый старт за 4 шага

1. Зарегистрируйтесь и возьмите тестовый ключ в кабинете, раздел «API-ключи».
2. Создайте счёт — в ответе придёт checkout_url.
3. Отправьте покупателя по этой ссылке либо откройте виджет на своём сайте.
4. Дождитесь вебхука invoice.paid и выдайте товар.

Сумма — строкой, в валюте счёта и с её числом знаков: "100.00". В ответе amount — это фиат, а amount_crypto и amount_received — монеты выбранного актива. Сравнивать полученное нужно с amount_crypto: у BTC-счёта на 100 USD amount_received будет вида "0.0015462746".

Все эндпоинты

Виджет на вашем сайте

Покупатель платит, не уходя со страницы. Счёт создаётся на вашем сервере, в кнопку передаётся его id.

Или программно, чтобы поймать результат:

Виджет не читает вашу страницу и не имеет доступа к её данным; обмен идёт только через postMessage с проверкой источника.

Статусы счёта

Вебхуки

POST на ваш URL при каждой смене статуса. Заголовок gw-signature: t=<unix>,v1=<hmac>, где подпись — HMAC-SHA256 от строки timestamp.тело секретом эндпоинта.

Проверяйте подпись и свежесть таймстемпа, иначе кто угодно сможет прислать вам «оплату». Порядок доставки не гарантирован — при сомнении запросите GET /v1/invoices/:id.

Node.js

PHP

Секрет подставляется в HMAC целиком, вместе с префиксом whsec_ — ровно так, как он показан при создании эндпоинта.

Python

Не дошло — повторяем 8 раз с нарастающей паузой до 12 часов. История доставок с отправленной подписью, телом запроса и ответом вашего сервера — в кабинете, там же ручной повтор.

Можно подписаться не на всё: передайте events при создании эндпоинта, и приходить будут только они. Без этого поля приходит всё.

Товар выдавайте по invoice.paid, а не по payment.detected. Второе означает «перевод виден в сети» — подтверждений может ещё не хватать, и в поле status внутри такого события лежит текущий статус счёта, а не смысл самого события. Смысл события — в его type.

Один и тот же URL дважды подключить нельзя: события приходили бы в двух копиях, и заказ, обработанный по доставке, выдался бы дважды. Менять подписку, адрес и паузу существующего эндпоинта можно в кабинете, не пересоздавая его — секрет при этом остаётся прежним.

Лента событий

Если вебхук не дошёл — или вы просто не хотите поднимать приёмник — те же события лежат в ленте. Она не зависит от эндпоинтов: события пишутся, даже если ни один вебхук не подключён.

Событие происходит один раз и имеет один id, сколько бы эндпоинтов его ни получили — по нему и дедуплицируйте. after продолжает чтение с места, где вы остановились.

Списки и страницы

Списки отдаются страницами: limit (1–100, по умолчанию 50) и offset. В ответе — total и has_more, так что видно, осталось ли что-то за краем.

Счета фильтруются по status и по вашему order_id — по нему заказ находится, даже если его id у вас потерялся.

Защита от двойного счёта при повторной отправке

В других API это называют идемпотентностью. Речь о простой вещи: ваш запрос ушёл, ответ не дошёл, вы повторяете — и не хотите получить второй счёт на тот же заказ.

Один order_id сам по себе этого не даёт — два запроса с одним order_id создадут два счёта. Уникальность обеспечивает именно заголовок ниже.

Передавайте Idempotency-Key при создании счёта. Повтор с тем же ключом вернёт исходный счёт, а не создаст второй. Тот же ключ с другим телом — ошибка 409 idempotency_conflict. Ключи хранятся сутки, после чего тот же ключ снова создаёт новый счёт — берите его от идентификатора заказа, а не от даты.

Права ключей

Секретный ключ можно выпустить с ограниченным набором прав — например, только на чтение, если вы отдаёте его подрядчику для сверки. Передайте scopes при создании ключа в кабинете; без него ключ получает всё, что может выдать ваша роль.

Доступны: invoices:read, invoices:write, payouts:read, payouts:write, balances:read, webhooks:manage, events:read. Публичный ключ pk_ можно отдавать в браузер: он читает один счёт по его id и больше ничего.

Проблемные платежи

Покупатель прислал не ту сумму — это не тупик, решение за вами.

Недоплата больше 5% требует подтверждения: первый запрос вернёт 400 confirm_shortfall с точным размером недоплаты в error.details.shortfall_bps, повторите с этим значением в поле confirm_shortfall_bps.

Ошибки

Формат одинаковый для всех ответов:

Безопасность ключа

Ключ — это доступ к деньгам. Держите его только на сервере: из браузера или мобильного приложения его видно любому. При выпуске боевого ключа можно указать IP-адреса вашего сервера — тогда утёкший ключ бесполезен откуда-либо ещё, а запрос с чужого адреса вернёт ip_not_allowed.

Ключ передаётся заголовком Authorization: Bearer sk_… либо X-Api-Key: sk_… — работают оба.

Ключ показывается один раз. Потеряли — отзовите и выпустите новый; скомпрометированный ключ отзывайте немедленно, отзыв действует сразу.

Тестовый режим

Ключи sk_test_… работают сразу после регистрации. Тестовый счёт выставляет заведомо неоплачиваемый адрес вида sandbox-… — реальные монеты на него отправить нельзя. Оплату можно сымитировать кнопкой на странице оплаты или запросом:

Ключ обязателен: иначе любой, кому попала ссылка на счёт, мог бы отправить в вашу интеграцию событие об оплате.

Валюту оплаты счёт получает на странице оплаты. Если вы имитируете платёж запросом, выберите её сами — иначе simulate ответит no_option:

Что в песочнице работает не так:

• Возврат покупателю — да: тестовым ключом по тестовому счёту.
• Вывод средств — нет: тестовые деньги не покидают песочницу, /v1/payouts ответит live_key_required. Отладить можно только обработку ошибок.
• Адрес вывода тестовым ключом добавляется, но годится только для песочницы. Боевой адрес добавляется в кабинете, где мы просим второй фактор.

Тестовые деньги учитываются отдельно и не выводятся.