beast docs

Справочник 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.

Поле телаТип
networkNetworkобязательно
amountstring, ^[0-9]{1,7}(\.[0-9]{1,6})?$обязательно; больше 0, не больше 1000000
external_idstring, 1..128 байтобязательно; ваш номер заказа, уникален; печатный Unicode, без управляющих символов
ttlinteger, 300..MAX_TTLне указан или 0: 1800; MAX_TTL по умолчанию 86400, не больше 604800
return_urlstring, 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-Eventid события, одинаков во всех повторах
X-Beast-TimestampUnix-секунды этой попытки
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

ПолеТип
idstringобяз.; inv_8c1d2e3f4a5b6c7d8e9f0a1b
external_idstringобяз.
networkNetworkобяз.
addressstringобяз.; TRON base58 T… или BSC EIP-55 0x…
amountstringобяз.
receivedstringобяз.; сумма зачисленных окончательных переводов, включая доплаты после оплаты, пока не кончилось окно наблюдения; переводы меньше 0.000001 USDT не зачисляются
statusStatusобяз.
created_atintegerобяз.
expires_atintegerобяз.
paid_atintegerтолько у paid и late_paid; время блока перевода, который довёл сумму до amount; позже expires_at значит late_paid
paymentsarray of Paymentобяз.
uristringобяз.; bep20: EIP-681 ethereum:<USDT>@56/transfer?address=<адрес>&uint256=<сумма в 18 знаках>; trc20: адрес
checkout_urlstringобяз.; PUBLIC_URL/pay/<id>
return_urlstringтолько если задан при создании

Payment

ПолеТип
txstringхэш: TRON 64 hex, BSC 0x и 64 hex
log_indexinteger
amountstring
seen_atintegerкогда сервис зачислил, не время блока

Error

ПолеТип
errorstringобяз.; unauthorized | bad_request | not_found | method_not_allowed | external_id_conflict | too_many_open_invoices | internal
messagestringпояснение, не всегда

Что значит каждый код: Ошибки.