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

Кому это нужно. Если вы стример и просто принимаете донаты — API вам не понадобится, всё есть в кабинете. Эта страница для тех, кто встраивает оплату в свой сайт или бота.

Как устроено

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

Аутентификация

Ключ создаётся в кабинете и показывается один раз. Передаётся заголовком:

X-Api-Key: pk_xxxx.yyyy

Ключ — это доступ к созданию инвойсов от вашего имени. Держите его на сервере. Не кладите в код страницы, в мобильное приложение и в публичный репозиторий. Утёк — отзовите в кабинете, старый ключ перестанет работать сразу.

Создать инвойс

POST /v1/invoices
X-Api-Key: pk_xxxx.yyyy
Content-Type: application/json

{
  "currency": "BTC",
  "type": "order",
  "expected_amount": "150000",
  "order_id": "order-42"
}

Суммы везде — строкой и в минимальных единицах (сатоши для BTC, литоши для LTC). Не число с плавающей точкой: 0.1 + 0.2 в большинстве языков даёт не 0.3, а на деньгах это недопустимо.

Заголовок Idempotency-Key защищает от дублей: повтор того же запроса вернёт тот же инвойс, а не создаст второй. То же самое делает уникальный order_id.

Webhook

Приходит на ваш адрес при событиях invoice.confirmed, invoice.expired, invoice.underpaid и invoice.late_payment. Подписан HMAC-SHA256 вашим секретом.

Проверяйте подпись по сырому телу запроса, до разбора JSON. Если сначала распарсить, а потом собрать обратно — байты изменятся и подпись не сойдётся. Рабочий пример с проверкой подписи и защитой от повторов лежит в репозитории: examples/webhook-receiver.mjs.

Статус pending в webhook не приходит намеренно: это ещё не деньги, а только замеченная транзакция. Для живого отображения есть SSE на странице оплаты.

Полная спецификация

Машиночитаемая схема OpenAPI 3.0 со всеми маршрутами, полями и кодами ошибок:

openapi.yaml — файл спецификации. Его можно открыть в Swagger Editor, Postman, Insomnia или скормить генератору клиента для вашего языка.

Если открыть ссылку прямо в браузере, вы увидите текст YAML — так и должно быть, это формат для инструментов, а не для чтения глазами.