Счета
Один счёт, один новый адрес. Создаёте с бэкенда, покупателя отправляете на checkout_url, ждёте вебхук.
Создать счёт
POST/v1/invoices. Заголовок Authorization: Bearer <токен API>. Тело JSON, не больше 8 КиБ.
| Поле | Тип | Правило |
|---|---|---|
network | string | Обязательно. trc20 или bep20. |
amount | string | Обязательно. USDT строкой: "9.99". До 6 знаков после точки. Больше 0, не больше 1000000. |
external_id | string | Обязательно. Номер вашего заказа. От 1 до 128 байт печатного Unicode: буквы, цифры, знаки, пробелы. Без управляющих символов и переводов строки. Уникален среди всех счетов. |
ttl | integer | Секунды до истечения. От 300 до MAX_TTL (по умолчанию 86400, сутки). Не указан или 0: 1800 (30 минут). |
return_url | string | Необязательно. Куда вернуть покупателя после оплаты: кнопка «Вернуться в магазин» на странице оплаты. Только 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"
Главный канал это вебхук. Запрос нужен для сверки: например, раз в час проверить счета, по которым вебхук не дошёл.
Объект счёта
| Поле | Тип | Что это |
|---|---|---|
id | string | inv_ и 24 hex. 96 случайных бит. |
external_id | string | Ваш номер заказа. |
network | string | trc20 или bep20. |
address | string | Адрес для оплаты. TRON: base58 T…. BSC: EIP-55 0x…. Свой у каждого счёта. |
amount | string | Сумма счёта в USDT. |
received | string | Сколько зачислено. Сумма всех окончательных переводов на адрес, включая доплаты после оплаты, пока адрес под наблюдением. |
status | string | Статус. |
created_at | integer | Unix-секунды. |
expires_at | integer | Unix-секунды. created_at + ttl. |
paid_at | integer | Есть только у paid и late_paid. Время блока перевода, который довёл сумму до amount, Unix-секунды. |
payments | array | Зачисленные переводы: tx (хэш: TRON 64 hex, BSC 0x и 64 hex), log_index, amount, seen_at (когда сервис его зачислил, не время блока). |
uri | string | Что зашито в QR. BEP20: EIP-681 ethereum:<USDT>@56/transfer?address=<адрес>&uint256=<сумма × 1018>. TRC20: просто адрес, общей схемы URI для кошельков TRON нет. |
checkout_url | string | PUBLIC_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. Другие токены и другие сети не зачисляются. Об этом предупреждает страница оплаты.
Когда платёж считается
| Токен | ровно 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_URL | BSC_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.