Интеграция платежей TRON: руководство на 2026 год

Интеграция платежей TRON — набор компонентов, который позволяет приложению принимать и отправлять TRX и токены TRC-20, такие как USDT: адреса, подписанные транзакции, обнаружение депозитов и проверку подтверждений. Её можно построить на API узлов TRON или вызвать REST API, который создаёт кошельки, отправляет переводы и присылает вебхуки. Это руководство описывает оба пути.

TL;DR

• Платежи TRX — нативные переводы между аккаунтами. Платежи TRC-20 (например, USDT) — вызовы смарт-контрактов, поэтому расходуют и Energy, и Bandwidth.
• Каждая операция, которая меняет состояние, проходит три шага: сформировать неподписанную транзакцию, подписать её ключом отправителя и отправить в ноду.
• Зачисляйте депозиты только из солидифицированных блоков, только для успешных транзакций, а для TRC-20 — только с одобренных контрактов токенов.
• Комиссии зависят от застейканных или делегированных ресурсов. Заложите их до запуска, иначе TRX будет сжигаться при каждом переводе.
• Можно обойтись без собственных нод и парсеров блоков, используя API кошельков, переводов и вебхуков, например API Chaingateway. Его вебхуки не повторяются автоматически, поэтому планируйте сверку.

Содержание

• Как работают платежи TRON?
• Строить на API узлов или использовать API?
• Как сформировать, подписать и отправить транзакцию?
• Как обнаружить входящие платежи?
• Когда платёж в TRON становится окончательным?
• Как защитить кошельки и приватные ключи?
• Сколько стоят Energy и Bandwidth?
• Как обрабатывать неудачные, задержанные и повторные платежи?
• Можно ли принимать платежи в собственном токене?
• Как отправлять платежи TRON через Chaingateway?
• FAQ
• Источники

Как работают платежи TRON?

TRX — нативный токен TRON. Он оплачивает комиссии сети, а стейкинг даёт сетевые ресурсы и право голоса, согласно документации TRON по TRX. Однако большая часть коммерческих платежей в TRON проходит в токенах, например USDT-TRC20. Поэтому нужно понимать оба типа переводов.

Платёж TRX — это простой перевод между аккаунтами в сети. Платёж TRC-20 устроен иначе: отправитель вызывает функцию transfer контракта токена, которая меняет балансы внутри контракта и испускает событие Transfer. Оба варианта записываются в TRON. Но переводы TRC-20 требуют выполнения смарт-контракта, поэтому расходуют Bandwidth и Energy, как описано в white paper TRON.

Эта разница определяет всю интеграцию:

Строить на API узлов или использовать API?

Документация интеграции TRON перечисляет, что обычно входит в интеграцию: подключение кошельков конечных пользователей, формирование и подпись транзакций, мониторинг депозитов и выводов, а также использование либо TronGrid, либо собственной полной ноды. Операторы бирж и кастодиальных кошельков решают задачи мониторинга депозитов, выводов и запросов баланса и истории на той же основе.

Это даёт два реалистичных пути.

Путь первый: строить на API узлов. Вы получаете полный контроль. Но и отвечаете за вывод адресов, разбор блоков, логику повторов, управление ресурсами и, при собственном хостинге, поддержку ноды. Наше руководство по настройке ноды TRON описывает маршрут Lite FullNode с jar или Docker, если вы выберете его.

Путь второй: использовать API кошельков и вебхуков. Вы вызываете REST-эндпоинт, чтобы создать кошелёк, другой, чтобы отправить перевод, и получаете подписанный вебхук, когда приходит депозит. Наш TRON API создан именно для этого: переводы USDT-TRC20 и вебхуки о депозитах без эксплуатации нод. Эндпоинты описаны в определении OpenAPI.

Полезное эмпирическое правило: если платежи — главное отличие вашего продукта и у вас есть команда для инфраструктуры, стройте сами. Если платежи — функция чего-то другого, API быстрее выводит продукт в продакшен и оставляет инженеров на основном продукте.

Как сформировать, подписать и отправить транзакцию?

Используете ли вы сырые вызовы ноды или SDK, каждая операция TRON, которая меняет состояние, следует одному и тому же трёхшаговому процессу. Сначала формируется неподписанная транзакция через API ноды. Затем её подписывают на стороне клиента приватным ключом отправителя, после чего подписанная транзакция отправляется в ноду.

Две детали стоит знать:

• TAPOS. Каждая транзакция ссылается на недавний блок. Это ограничивает повторное воспроизведение в ветках цепочки, которые не содержат этот блок, согласно документации протокола по транзакциям. На практике формируйте и подписывайте транзакцию незадолго до отправки. Транзакция, подписанная и отложенная надолго, может истечь.
• Используйте SDK для подписи. Руководство разработчика кошельков рекомендует в продакшене готовые функции SDK, а не самописные примитивы подписи. Так вы избегаете граничных случаев сериализации protobuf и восстановления подписи. Не пишите своё.

Для браузерных сценариев, где пользователь платит из своего кошелька, руководство по интеграции DApp описывает два варианта: TronWallet Adapter для поддержки нескольких кошельков или прямую интеграцию TronLink, которая внедряет провайдер в window.tron. Чекауты продавцов, которые создают адрес депозита на каждый заказ, обычно в этом вообще не нуждаются. Клиент платит из того кошелька, который уже использует.

Как обнаружить входящие платежи?

Типичная модель продавца — один адрес депозита на заказ или на клиента. Ваша задача — заметить деньги, приходящие на эти адреса.

Руководство по биржевым и кастодиальным кошелькам описывает два способа обнаружения: опрос API истории аккаунтов TronGrid каждые несколько секунд или последовательный разбор блоков. Если вы разбираете блоки, используйте последнюю солидифицированную высоту. Логи событий и внутренние транзакции получайте отдельно от результатов выполнения и сохраняйте как отдельные записи.

Не пропускайте внутренние транзакции

Это самый частый пробел в самодельных интеграциях. Пользователи могут получить TRX или токены TRC-10 через вызов смарт-контракта, и такие переводы не видны как транзакции верхнего уровня. Тот же гайд советует разбирать внутренние транзакции при зачислении депозитов. Если ваш слушатель смотрит только переводы верхнего уровня, часть клиентов заплатит и никогда не будет зачислена.

Правильно проверяйте депозиты TRC-20

Для депозитов токенов один хеш транзакции ничего не доказывает. Руководство по интеграции кошельков бирж с TRON советует проверить, что транзакция успешна, и разбирать логи Transfer только от одобренных контрактов токенов, проверяя отправителя, получателя и сумму. Никогда не зачисляйте неуспешные транзакции. После солидификации транзакции TRC-20 руководство по взаимодействию с TRC-20 советует подтвердить выполнение через getTransactionInfoById. Для transfer и transferFrom также проверьте событие Transfer, которое испустил контракт токена.

Минимальный чек-лист проверки каждого депозита TRC-20:

1. Адрес контракта есть в вашем списке разрешённых: это настоящий контракт USDT, а не токен-двойник с тем же названием.
2. Результат транзакции — успех.
3. Есть событие Transfer, где получатель — ваш адрес депозита.
4. Сумма совпадает с заказом, с учётом decimals токена.
5. Вы ещё не зачисляли этот ID транзакции.

Шаг со списком разрешённых контрактов важнее, чем кажется. Любой может задеплоить токен с названием «USDT». Ваш код должен проверять контракт, а не символ.

Когда платёж в TRON становится окончательным?

Транзакция TRON проходит четыре фазы: создание и подпись, рассылка и валидация, включение в блок супер-представителем и солидификация. Согласно документации протокола, она считается полностью подтверждённой, когда как минимум 19 разных активных супер-представителей произвели блоки на её блоке или позже. Обычно это занимает около минуты.

Для логики платежей это значит следующее:

• Читайте из высоты солидифицированного блока, а не из головы цепочки. Так откат форка не отменит платёж, который вы уже зачислили. Руководство по интеграции бирж указывает, что солидификация отстаёт от головы примерно на минуту.
• Показывайте клиенту состояние «платёж получен» сразу, а состояние «платёж подтверждён» — только при солидификации. Так оплата ощущается мгновенной и не рискует откатом.
• Делайте зачисление идемпотентным. Если ключ — ID транзакции и индекс лога, повторно доставленный вебхук или повторно разобранный блок не зачислит заказ дважды.

Как защитить кошельки и приватные ключи?

То же руководство для бирж даёт понятные указания по ключам. Выводите адреса депозита по стандарту BIP-44 и подписывайте выводы офлайн, в HSM или на аппаратном кошельке. Никогда не храните ключ в открытом виде на сервере приложения.

На практике это значит:

• Выводите адреса депозита из одного защищённого seed, чтобы не держать тысячи независимых ключей для резервного копирования.
• Держите среду подписи отдельно от веб-приложения, которое смотрит в интернет.
• Логируйте каждый запрос на вывод с указанием того, кто его одобрил. Установите лимиты и обязательное одобрение для крупных сумм.

С Chaingateway POST /api/v2/tron/addresses создаёт кошелёк. Если вы передаёте password, приватный ключ хранится зашифрованным этим паролем. При отправке вы передаёте пароль вместо ключа. Chaingateway не хранит пароль и не может восстановить кошелёк, если вы его потеряете. Подробнее — в нашем руководстве по кошелькам TRON с защитой паролем.

Сколько стоят Energy и Bandwidth?

Комиссии — место, где TRON удивляет новые команды. Согласно руководству по интеграции бирж, выводы расходуют Bandwidth. Переводы TRC-20 и другие вызовы контрактов расходуют также Energy. Ресурсы появляются через стейкинг или делегирование, а при их нехватке вместо них сжигается TRX. Для операторов с большим объёмом рекомендуют стейкинг. Параметр fee_limit ограничивает бюджет Energy со стороны вызывающего для вызовов смарт-контрактов.

Цифры, которые стоит держать в голове, из документации TRON по токеномике:

• Ставка сжигания: 0,001 TRX за байт Bandwidth и 0,0001 TRX за единицу Energy. Эти ставки можно изменить через предложения, поэтому читайте их из сети, а не прописывайте в коде.
• Стейкинг TRX даёт Bandwidth или Energy и создаёт TRON Power для голосования. Расстейкивание запускает период ожидания, который задаёт параметр сети getUnfreezeDelayDays.

Каждый активированный аккаунт также получает возобновляемую квоту в 600 единиц бесплатного Bandwidth. Она постепенно восстанавливается в течение 24 часов после использования. TRX сжигается как запасной вариант, когда Bandwidth или Energy не хватает, согласно сравнению TRON и Ethereum.

Планирование бюджета на комиссии

До запуска оцените количество переводов в месяц и ресурсы, которые нужны каждому из них. Затем решите, сколько стейкать или делегировать, а сколько сжигать. С арифметикой помогут калькулятор Energy и Bandwidth TRON и калькулятор комиссий USDT-TRC20. Наше руководство Energy и Bandwidth объясняет, какой ресурс расходует каждое действие. Статья о снижении комиссий TRC-20 описывает способы уменьшить расходы.

У Chaingateway есть эндпоинты для стейкинга и делегирования: POST /api/v2/tron/freeze и POST /api/v2/tron/delegate. Старый сервис оплаты комиссий Paymaster устарел. Если хотите, чтобы комиссии за пользователей оплачивались, используйте TronFuel. GET /api/v2/tron/chainparameters возвращает текущие цены Energy и Bandwidth.

Одна практическая привычка: всегда задавайте разумный fee_limit для вызовов контрактов и проверяйте доступные ресурсы аккаунта перед отправкой. Так вывод незаметно не сожжёт больше TRX, чем вы заложили в бюджет.

Как обрабатывать неудачные, задержанные и повторные платежи?

Производственные платёжные системы оправдывают себя на граничных случаях. Вот как обрабатывать каждый из них в TRON.

Для тестирования сначала прогоните весь процесс в тестовой сети. Создайте адрес, пополните его, отправьте перевод TRX и перевод TRC-20 и наблюдайте каждое состояние, через которое проходит ваша система. Затем намеренно вызовите сбои, например вызов контракта без Energy и повторно проигранный вебхук. Убедитесь, что система ведёт себя так, как описано в таблице выше.

Можно ли принимать платежи в собственном токене?

Если вы выпускаете токен в TRON, его можно принимать как любой другой TRC-20. TRC-20 — стандарт TRON для взаимозаменяемых токенов, реализованных смарт-контрактами. Его обязательный интерфейс включает balanceOf, transfer, transferFrom, approve, allowance, а также события Transfer и Approval. Поскольку эти функции и события общие, кошельки и биржи могут работать с вашим токеном без специального кода.

Для приёма платежей это значит три вещи. Добавьте адрес своего контракта в список разрешённых для депозитов. Правильно учитывайте decimals в проверках суммы. Тестируйте на небольших переводах, прежде чем открыть приём клиентам. С точки зрения обнаружения ваш токен ведёт себя как USDT: событие Transfer от одобренного контракта.

Как отправлять платежи TRON через Chaingateway?

Создайте кошелёк, отправьте перевод TRC-20 и подпишитесь на депозиты, используя три вида запросов. Эндпоинт TRC-20 требует from, to, contractaddress и amount, а также password или privatekey.

curl -X POST https://app.chaingateway.io/api/v2/tron/transactions/trc20 \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "X-Network: testnet" \
  -H "Content-Type: application/json" \
  -d '{"from": "T...", "to": "T...", "contractaddress": "T...", "amount": 10, "password": "wallet-password"}'

X-Network: testnet использует тестовую сеть Nile. Создайте вебхук для адреса получения запросом POST /api/v2/tron/webhooks и проверяйте каждую доставку по заголовку X-Signature (руководство по подписи). Полезная нагрузка вебхука содержит txid, from, to, amount, contractaddress, blocknumber и type. Начните с Blockchain API и уведомлений о вебхуках. Тарифы начинаются с 49 € в месяц, с 7-дневным пробным периодом без карты (тарифы).

Источники

• TRX, нативный токен сети TRON
• White paper TRON
• Документация по интеграции TRON
• Подпись и рассылка: процесс работы с API
• Транзакции
• Руководство разработчика кошельков
• Интеграция DApp с TronLink
• Интеграция бирж и кастодиальных кошельков
• Интеграция кошельков бирж с сетью TRON
• Взаимодействие с контрактом TRC-20
• Протокольный интерфейс TRC-20
• Токеномика
• TRON и Ethereum

Рекомендуем

• TRON API: переводы USDT-TRC20 и вебхуки о депозитах
• Комиссии TRON: полное руководство и бесплатный калькулятор