Как принимать USDT в бизнесе: пошаговое руководство

Приём USDT начинается с выбора сценария оплаты. Для разового счёта достаточно платёжной ссылки, для магазина на готовой платформе — официального плагина, а для собственного учёта заказов подходит REST API. Paymos принимает USDT и оставляет выручку в том же активе без обязательного обмена в BTC, ETH или фиатные деньги.

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

Как выбрать способ приёма USDT?

Платёжная ссылка подходит для счёта, который менеджер отправляет клиенту напрямую. Готовую страницу оплаты можно открыть отдельно или встроить через iframe. Виджет SDK даёт встроенный сценарий на сайте, а официальный плагин подключает одну из поддерживаемых CMS без собственной серверной реализации всего платёжного процесса.

REST API выбирают, когда сервер бизнеса сам создаёт счета и хранит их связь с заказами. Покупателю при этом всё равно можно показать готовую страницу Paymos. API не обязывает создавать собственный интерфейс оплаты: он отвечает за управление счётом, а способ показа выбирается отдельно.

На каких сетях принимать USDT и куда попадает выручка?

Paymos принимает USDT в 11 сетях: Tron, Ethereum, BSC, Polygon, Arbitrum, Optimism, TON, Avalanche, Solana, NEAR и Plasma. Выбор сети влияет на комиссию кошелька покупателя и на срок подтверждения. Постоянную стоимость отправки фиксировать нельзя: сетевые расходы меняются.

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

Как связать платёж со своим заказом?

Присвойте заказу постоянный external_order_id. Передавайте его при создании счёта и сохраняйте рядом идентификатор счёта Paymos. Если соединение оборвалось до получения ответа, повторите запрос с исходным внешним номером: Paymos вернёт существующий счёт.

Новый external_order_id означает новый заказ, а не новую попытку сетевого запроса. Поэтому номер формирует система заказов, а не HTTP-клиент. Отдельный заголовок Idempotency-Key для создания счёта Paymos не применяет.

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

Когда выдавать товар или доступ?

Не связывайте выдачу с возвращением покупателя на страницу успеха. Заказ можно исполнить после проверки подписи вебхука и выполнения политики подтверждений. Число подтверждений зависит от сети и суммы: небольшому платежу может потребоваться меньше, крупному — больше.

Обработчик должен выдерживать повтор одного уведомления. До выдачи товара сохраните запись о выполненном заказе, а при повторе найдите её и завершите обработку без новой выдачи. Это же правило действует при ручном повторе доставки.

Если уведомление приходит повторно, обработчик сначала проверяет результат прежнего исполнения. Возврат покупателя на сайт не заменяет эту проверку и сам по себе не подтверждает оплату.

Как проверить вебхук до изменения заказа?

Paymos передаёт X-Webhook-Signature в формате t={timestamp},v1={hmac_hex}. Пересчитайте HMAC-SHA256 на секрете вебхука и сравните подписи способом, устойчивым к атакам по времени. Проверка должна завершиться раньше, чем обработчик изменит заказ, остаток или доступ покупателя.

При смене секрета действует переходный период, когда могут приниматься текущий и предыдущий секреты. После его окончания предыдущий секрет удаляют из обработчика. Bearer-токен или доверие к IP-адресу не заменяют проверку подписи.

Если подпись не прошла проверку, обработчик не должен менять заказ. Причину отказа можно зафиксировать в журнале, не записывая туда сам секрет вебхука.

Как пережить недоступность обработчика?

Paymos делает 11 попыток за один цикл доставки: первую отправку и десять повторов. Задержки растут от одной минуты до восьми часов, а весь цикл занимает примерно 16 часов. После восстановления принимающей системы недоставленное событие можно повторить вручную.

Адрес вебхука должен быть доступен из интернета. Paymos блокирует адреса обратной петли, частные и локальные адреса канала, CGNAT и IPv6 ULA, а также не следует автоматическим HTTP-перенаправлениям. Контролируйте неудачные доставки и заранее определите, кто запускает ручной повтор.

Ручной повтор запускают после устранения причины недоступности, сохраняя ту же защиту от повторного исполнения заказа.

Какие ключи разделить до запуска?

Merchant API использует HMAC-SHA256, а не Bearer-токен. Секрет хранится на доверенном сервере и не попадает в браузерный код. Учётные данные Payment и Payout разделены: сервису, который создаёт счета, не требуется доступ к выводу средств.

Тестовый и рабочий режимы тоже используют разные ключи при одинаковом наборе методов API. Храните их под разными именами и явно указывайте среду в журналах. Такой порядок не позволяет тестовому сервису случайно обратиться к рабочим счетам.

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

Как учитывать недоплату?

Допуск недоплаты задаётся для проекта в процентах. По умолчанию действует строгое совпадение с допуском 0 %. Если платёж попал в настроенный предел, счёт закрывается по фактически полученной сумме: Paymos не добавляет недостающую часть.

При сумме ниже порога счёт с одним платежом считается недоплаченным. Счёт, для которого разрешено несколько платежей, может продолжить ждать остаток. Это правило нужно отразить в системе заказов, чтобы частичная оплата не открыла доступ раньше времени.

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

Что проверить в тестовом режиме?

Сначала повторите создание счёта с одним external_order_id и убедитесь, что второй счёт не появился. Затем проверьте предусмотренные сценарии оплаты, подпись вебхука, повтор одного уведомления и восстановление после недоступности обработчика. В каждом случае заказ должен исполниться не более одного раза.

Перед переходом к реальным платежам замените тестовые ключи рабочими, проверьте адрес вебхука и выбранный способ оплаты. В документации поддержки укажите, что срок подтверждения зависит от сети, суммы и состояния блокчейна. Обещание одного времени для всех платежей создаст неверные ожидания. Серверный сценарий подробнее разобран в руководстве по REST API.