beast docs

Счета

Один счёт, один новый адрес. Создаёте с бэкенда, покупателя отправляете на checkout_url, ждёте вебхук.

Создать счёт

POST/v1/invoices. Заголовок Authorization: Bearer <токен API>. Тело JSON, не больше 8 КиБ.

ПолеТипПравило
networkstringОбязательно. trc20 или bep20.
amountstringОбязательно. USDT строкой: "9.99". До 6 знаков после точки. Больше 0, не больше 1000000.
external_idstringОбязательно. Номер вашего заказа. От 1 до 128 байт печатного Unicode: буквы, цифры, знаки, пробелы. Без управляющих символов и переводов строки. Уникален среди всех счетов.
ttlintegerСекунды до истечения. От 300 до MAX_TTL (по умолчанию 86400, сутки). Не указан или 0: 1800 (30 минут).
return_urlstringНеобязательно. Куда вернуть покупателя после оплаты: кнопка «Вернуться в магазин» на странице оплаты. Только https://, до 512 байт, без user:password@ и пробелов. Иначе 400 bad_request. Подробно в Кастомизации.
curl -s https://pay.example.com/v1/invoices \
  -H "Authorization: Bearer $BEAST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"network":"bep20","amount":"9.99","external_id":"order-1042","ttl":1800}'

Сумма строкой, ttl числом. Сумма числом даст 400 с именем поля в message.

Ответ 200 с объектом счёта:

{
  "id": "inv_8154ea91135b00d06bef0b44",
  "external_id": "order-1042",
  "network": "bep20",
  "address": "0x7D202b75b9A48FCE29F6fF834EaEBC383C5ab3CE",
  "amount": "9.99",
  "received": "0",
  "status": "open",
  "created_at": 1794802095,
  "expires_at": 1794803895,
  "payments": [],
  "uri": "ethereum:0x55d398326f99059fF775485246999027B3197955@56/transfer?address=0x7D202b75b9A48FCE29F6fF834EaEBC383C5ab3CE&uint256=9990000000000000000",
  "checkout_url": "https://pay.example.com/pay/inv_8154ea91135b00d06bef0b44"
}

В сыром ответе & в uri придёт как &. Это обычное JSON-экранирование Go, любой парсер его поймёт.

Повтор запроса безопасен

Тот же external_id с той же сетью и суммой вернёт тот же счёт. Сеть упала, таймаут? Просто повторите. С другой сетью или суммой будет 409 external_id_conflict. Значение ttl при сравнении не учитывается. Одновременные повторы тоже безопасны: счёт будет один.

Лимит открытых счетов

В каждой сети не больше MAX_OPEN_INVOICES открытых неистёкших счетов, по умолчанию 200. Следующий получит 429 too_many_open_invoices. Лимит и MAX_TTL ограничивают ущерб от утёкшего токена: чужой поток счетов не съест квоту TronGrid.

Нужен новый счёт на тот же заказ? Дайте новый external_id, например order-1042-2.

Получить счёт

GET/v1/invoices/{id}. Тот же токен. Отдаёт счёт со всеми платежами. Неизвестный или кривой id даёт 404 not_found.

curl -s https://pay.example.com/v1/invoices/inv_8154ea91135b00d06bef0b44 \
  -H "Authorization: Bearer $BEAST_API_TOKEN"

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

Объект счёта

ПолеТипЧто это
idstringinv_ и 24 hex. 96 случайных бит.
external_idstringВаш номер заказа.
networkstringtrc20 или bep20.
addressstringАдрес для оплаты. TRON: base58 T…. BSC: EIP-55 0x…. Свой у каждого счёта.
amountstringСумма счёта в USDT.
receivedstringСколько зачислено. Сумма всех окончательных переводов на адрес, включая доплаты после оплаты, пока адрес под наблюдением.
statusstringСтатус.
created_atintegerUnix-секунды.
expires_atintegerUnix-секунды. created_at + ttl.
paid_atintegerЕсть только у paid и late_paid. Время блока перевода, который довёл сумму до amount, Unix-секунды.
paymentsarrayЗачисленные переводы: tx (хэш: TRON 64 hex, BSC 0x и 64 hex), log_index, amount, seen_at (когда сервис его зачислил, не время блока).
uristringЧто зашито в QR. BEP20: EIP-681 ethereum:<USDT>@56/transfer?address=<адрес>&uint256=<сумма × 1018>. TRC20: просто адрес, общей схемы URI для кошельков TRON нет.
checkout_urlstringPUBLIC_URL/pay/<id>. Сюда отправляете покупателя.

Все суммы это десятичные строки без лишних нулей: "10", "9.99", "0". Не переводите их во float. Храните в центах или в decimal.

Статусы

СтатусЗначитЧто делать
openЖдём оплату. received может быть больше нуля: это частичная оплата.Ждать.
paidЗачислено не меньше суммы до expires_at.Выдать товар.
expiredВремя вышло, оплаты нет. Сервис ещё следит за адресом: 7 дней, если что-то уже пришло, и 1 день, если не пришло ничего.Не выдавать. Ждать возможный late_paid.
late_paidОплата пришла после expires_at, но в окне наблюдения.Решаете сами: выдать товар или вернуть деньги.
open ──(оплачено вовремя)──▶ paid
  │
  └──(время вышло)──▶ expired ──(оплачено в окне)──▶ late_paid
  • expired не хранится, а вычисляется при каждом ответе: open после expires_at.
  • Вебхук invoice.paid уходит один раз, при переходе в paid или late_paid. Смотрите на invoice.status внутри.
  • «Вовремя» в обеих сетях считается по времени блока, а не по моменту, когда сервис увидел перевод. Платёж в блоке до expires_at будет paid, даже если стал окончательным позже.
  • Окно наблюдения: 7 дней после expires_at, 1 день, если не пришло ничего. Сервис смотрит ещё час сверх окна, чтобы не пропустить платёж на самой границе. После этого адрес больше не проверяется. Деньги, пришедшие позже, в счёт не попадут. Неоплаченный счёт тогда закрыт.

Суммы, доплата, переплата

  • Переводы складываются. Покупатель прислал 5 из 9.99? Счёт остаётся open, received показывает 5. Доплата на тот же адрес закроет счёт.
  • Переплата принимается. Если перевод больше суммы, счёт paid, а received больше amount.
  • Доплата после оплаты тоже считается. Адрес под наблюдением до 7 дней после expires_at, и оплаченный тоже. Новые переводы добавятся в received. Статус останется paid, второго вебхука не будет.
  • Позже окна ничего не зачисляется. Такие деньги уйдут на холодный кошелёк при сливе.
  • BEP20 округляется вниз до 6 знаков. У токена 18 знаков. Остаток меньше 0.000001 USDT ничего не зачисляет, но тоже сливается.
  • Только настоящий USDT. Другие токены и другие сети не зачисляются. Об этом предупреждает страница оплаты.

Когда платёж считается

TRC20BEP20
Токенровно TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t, 6 знаковровно 0x55d398326f99059fF775485246999027B3197955, 18 знаков
Окончательностьтолько подтверждённые (solidified)не меньше 15 блоков сверху, лог не откачен реорганизацией. Квитанция не нужна: откаченная транзакция логов не пишет
Получательадрес счётаадрес счёта в topic[2]
Один разуникально по (сеть, tx, log index, получатель). Одна транзакция на два наших адреса оплатит оба счёта. TRC20: одинаковая запись в ответе TronGrid (tx, отправитель, получатель, сумма) засчитывается один раз
Времявремя блока
Как частопервые 10 мин раз в 15 с, дальше раз в минуту, истёкшие и оплаченные раз в 10 мин, истёкшие без единого перевода раз в 30 мин. Не больше 20 адресов за проход, по очереди. Живые счета всегда первые, истёкшим и оплаченным не больше 5 мест из 20один запрос на каждые 50 адресов раз в 15 с, не больше 500 адресов: сначала живые счета, потом те, куда что-то пришло, потом самые новые. Больше 500: в логе ALERT bep20: watching only. Отказ RPC на диапазоне: диапазон делится пополам, вплоть до одного блока
Второе мнениеTRON_VERIFY_URLBSC_VERIFY_RPC_URL

Ошибка API или 429 никогда не отмечает оплату. Адрес или диапазон просто читается снова при следующем проходе. Курсор BSC не уходит дальше непрочитанного диапазона. И дальше блока, которого провайдер ещё не показывает: отстающий узел за тем же URL не заставит пропустить платёж.

Со вторым провайдером счёт станет оплаченным, только когда и он видит USDT на адресе. Расхождение пишет в лог ALERT … NOT marked paid и проверяется снова. Оплату оно не ставит никогда. Через сутки после последнего зачисления проверка прекращается: в логе ALERT … verify gave up, в аудите verify.gaveup, дальше смотрите адрес сами. Без второго провайдера решает основной, а при старте в логе WARNING. Подробнее о доверии.

Страница оплаты

Страница оплаты: счёт оплачен, кнопка «Вернуться в магазин»

GET/pay/{id}. Публичная, без токена. Ссылка на неё и есть пропуск: id не угадать.

  • Сумма крупно, значки токена и сети, адрес и сумма копируются в одно касание, QR из uri, таймер с полоской.
  • Раз в 5 секунд спрашивает /pay/{id}/status. Состояния: «Ждём оплату», «Ждём доплату» с остатком до микро-USDT, «Время вышло» с обещанием зачесть поздний платёж, «Оплачено» с кнопкой «Вернуться в магазин» (если задан return_url).
  • Неоплаченный счёт закрыт, когда кончилось окно наблюдения: 7 дней после expires_at, 1 день, если не пришло ничего. Страница пишет «Счёт закрыт» и больше не показывает адрес и QR.
  • По-русски, под телефон. Имя магазина, логотип, цвет, тема и скругления задаются в Кастомизации.
  • Без внешних ресурсов и без инлайна. CSP default-src 'none'; style-src 'self'; script-src 'self', свой скрипт, свой PNG с QR. frame-ancestors 'none': в iframe не встраивается. Отправляйте покупателя по ссылке.
  • Своя страница? Возьмите address, amount и uri из ответа API и покажите их сами.

Статус для страницы

GET/pay/{id}/status. Публичный. Только то, что можно показать покупателю:

{"amount": "9.99", "expires_at": 1794803895, "received": "5", "status": "open"}

Статусы те же, что у счёта, плюс closed: не оплачен и окно наблюдения кончилось (7 дней после expires_at, 1 день, если не пришло ничего).

GET/pay/{id}/qr.png отдаёт QR из uri в PNG. Неизвестный счёт на всех трёх адресах даёт 404. Закрытый счёт тоже даёт 404 на qr.png.