Справочник API
По спецификации OpenAPI 3.1, версия 1.0.0. Скачать: openapi.yaml.
База: ваш PUBLIC_URL, например https://pay.example.com. Суммы это строки USDT, до 6 знаков после точки: "9.99". Время в Unix-секундах.
Авторизация
Все /v1/*: Authorization: Bearer <токен API>. Токен 64 hex, сервер хранит только его SHA-256. Пути /pay/* публичные.
Любой ответ API это JSON, ошибки тоже. Неизвестный путь даёт 404 not_found, не тот метод на известном пути 405 method_not_allowed.
Методы
POST/v1/invoices
Создать счёт. Идемпотентно по external_id: те же сеть и сумма вернут прежний счёт, другие дадут 409. Одновременные повторы тоже. Поле не того типа даёт 400 с именем поля в message.
| Поле тела | Тип | |
|---|---|---|
network | Network | обязательно |
amount | string, ^[0-9]{1,7}(\.[0-9]{1,6})?$ | обязательно; больше 0, не больше 1000000 |
external_id | string, 1..128 байт | обязательно; ваш номер заказа, уникален; печатный Unicode, без управляющих символов |
ttl | integer, 300..MAX_TTL | не указан или 0: 1800; MAX_TTL по умолчанию 86400, не больше 604800 |
return_url | string, https, до 512 байт | необяз.; кнопка «Вернуться в магазин» после оплаты (подробно) |
Ответы: 200 Invoice · 400 bad_request · 401 unauthorized · 405 method_not_allowed · 409 external_id_conflict · 429 too_many_open_invoices (больше MAX_OPEN_INVOICES открытых счетов в сети, по умолчанию 200) · 500 internal.
GET/v1/invoices/{id}
Счёт со всеми платежами. id: ^inv_[0-9a-f]{24}$.
Ответы: 200 Invoice · 401 unauthorized · 404 not_found · 405 method_not_allowed · 500 internal.
GET/pay/{id}
Страница оплаты для покупателя, HTML на русском. Публичная: id и есть пропуск. Сумма, сеть, адрес с кнопкой копирования, QR, таймер, живой статус. Неоплаченный счёт после окна наблюдения (7 дней после expires_at, 1 день, если не пришло ничего) показывает «Счёт закрыт» без адреса и QR.
Ответы: 200 text/html · 404 счёт не найден.
GET/pay/{id}/status
Статус, который можно показать покупателю. Его опрашивает страница оплаты раз в 5 секунд. Публичный.
{"status": "open", "amount": "9.99", "received": "0", "expires_at": 1794803895}
status: как у счёта, плюс closed: не оплачен и окно наблюдения кончилось (7 дней после expires_at, 1 день, если не пришло ничего).
Ответы: 200 · 404 not_found.
GET/pay/{id}/qr.png
QR из uri счёта, PNG. Публичный.
Ответы: 200 image/png · 404 счёт не найден или закрыт.
Вебхук
POSTWEBHOOK_URL · invoice.paid
Один раз на счёт, когда зачисленная сумма впервые достигла суммы счёта (paid, или late_paid после expires_at). Редиректы не выполняются.
| Заголовок | |
|---|---|
X-Beast-Event | id события, одинаков во всех повторах |
X-Beast-Timestamp | Unix-секунды этой попытки |
X-Beast-Signature | "v1=" + hex(HMAC-SHA256(WEBHOOK_SECRET, timestamp + "." + сырое тело)) |
Тело: id (string, ev_…), type (invoice.paid), created (integer), invoice (Invoice). Все поля обязательны.
Ответ 2xx это доставка. Иначе повтор: 30 с, 1 мин, 2 мин и дальше вдвое, до 6 часов, всего 25 попыток. Таймаут 10 секунд. Подробно в разделе Вебхуки.
Схемы
Network
string: trc20 | bep20.
Status
string: open | paid | expired | late_paid. expired: открыт после expires_at и не оплачен; в окне наблюдения (7 дней после expires_at, 1 день, если не пришло ничего) ещё может стать late_paid.
Invoice
| Поле | Тип | |
|---|---|---|
id | string | обяз.; inv_8c1d2e3f4a5b6c7d8e9f0a1b |
external_id | string | обяз. |
network | Network | обяз. |
address | string | обяз.; TRON base58 T… или BSC EIP-55 0x… |
amount | string | обяз. |
received | string | обяз.; сумма зачисленных окончательных переводов, включая доплаты после оплаты, пока не кончилось окно наблюдения; переводы меньше 0.000001 USDT не зачисляются |
status | Status | обяз. |
created_at | integer | обяз. |
expires_at | integer | обяз. |
paid_at | integer | только у paid и late_paid; время блока перевода, который довёл сумму до amount; позже expires_at значит late_paid |
payments | array of Payment | обяз. |
uri | string | обяз.; bep20: EIP-681 ethereum:<USDT>@56/transfer?address=<адрес>&uint256=<сумма в 18 знаках>; trc20: адрес |
checkout_url | string | обяз.; PUBLIC_URL/pay/<id> |
return_url | string | только если задан при создании |
Payment
| Поле | Тип | |
|---|---|---|
tx | string | хэш: TRON 64 hex, BSC 0x и 64 hex |
log_index | integer | |
amount | string | |
seen_at | integer | когда сервис зачислил, не время блока |
Error
| Поле | Тип | |
|---|---|---|
error | string | обяз.; unauthorized | bad_request | not_found | method_not_allowed | external_id_conflict | too_many_open_invoices | internal |
message | string | пояснение, не всегда |
Что значит каждый код: Ошибки.