Как подключить оплату в USDT на сайте: пошаговая интеграция через API

Подключение оплаты в USDT: запрос адреса, перевод клиента, вебхук, зачисление

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

Примеры запросов взяты из API KosPay, но логика одинакова почти у всех шлюзов.

Что подготовить до начала

  • API-ключ. Выпускается в кабинете шлюза и хранится только на сервере. В коде сайта, который видит браузер, ключа быть не должно.
  • Адрес для уведомлений (вебхуков). Это URL на вашем сервере, куда шлюз будет присылать события о зачислениях и выплатах. Нужен HTTPS.
  • Секрет подписи. Им вы проверяете, что уведомление пришло от шлюза, а не от постороннего.
  • Решение о модели приёма. Будете вы выдавать адрес на один платёж с ограниченным сроком или закрепите за клиентом постоянный адрес. От этого зависит, как выглядит страница оплаты. Подробно разница описана в статье Адрес на клиента или счёт на сумму.
  • Список сетей. Обычно это TRON (TRC-20) и одна-две дешёвые сети: BSC, Polygon или TON. Как выбрать, рассказано в статье TRC-20 или BEP-20: какую сеть выбрать.

Шаг 1. Клиент нажимает «Пополнить»

Ваш сервер запрашивает у шлюза адрес для этого клиента. В запросе два параметра: идентификатор клиента в вашей системе и сеть.

POST https://kospay.io/v1/payments
Authorization: Bearer cp_live_…

{"userId": "1386", "network": "TRON"}

В ответ приходит адрес и срок, до которого он закреплён за клиентом. Если клиент нажмёт кнопку ещё раз, пока срок не истёк, вернётся тот же адрес, а не новый. Это важно: клиент мог уже скопировать первый адрес и отправить на него деньги.

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

Схема интеграции: сайт запрашивает адрес, клиент переводит USDT, шлюз проверяет и присылает вебхук, сайт зачисляет баланс
Кто что делает при одном пополнении: ваш сайт, клиент и шлюз

Шаг 2. Страница оплаты

На этой странице клиент совершает больше всего ошибок, поэтому её стоит сделать аккуратно.

  • Сеть крупно, рядом с адресом. Не «USDT», а «USDT, сеть TRON (TRC-20)». Именно эту строку клиент будет искать в списке сетей на бирже.
  • Адрес с кнопкой «Скопировать» и QR-код. Вручную адрес никто не перепечатывает, а ошибка в одном символе отправит деньги в никуда.
  • Срок действия адреса, если он ограничен, и просьба не сохранять адрес для следующих платежей.
  • Предупреждение про комиссию биржи. Некоторые биржи вычитают свою комиссию из суммы перевода. Если вы зачисляете фактически пришедшую сумму, клиенту полезно об этом знать заранее.
  • Статус платежа. Страница может раз в несколько секунд спрашивать ваш сервер, пришли ли деньги, и показать «Зачислено», когда придёт уведомление.

Что бывает, если клиент всё-таки ошибся сетью, разобрано в статье Клиент отправил USDT не в ту сеть.

Шаг 3. Обработчик уведомлений

Когда перевод подтверждён и проверен, шлюз отправляет на ваш адрес POST-запрос с событием deposit.credited. В нём идентификатор клиента, сеть, хеш транзакции, полученная сумма, комиссия и сумма к зачислению.

{"event": "deposit.credited", "data": {
  "userId": "1386", "network": "TRON", "txid": "…", "logIndex": 0,
  "amount": "100", "fee": "1", "credited": "99"}}

Обработчик делает пять вещей в таком порядке.

  1. Проверяет подпись. Шлюз считает HMAC-SHA256 от тела запроса и кладёт результат в заголовок. Вы считаете то же самое своим секретом и сравниваете. Считать нужно по сырому телу запроса, до разбора JSON: после разбора и повторной сборки строка может отличаться на пробел, и подпись не сойдётся.
  2. Отсекает повторы. Одно и то же событие может прийти дважды, например если ваш сервер ответил с задержкой. Ключ для проверки у пополнения — сеть, хеш транзакции и номер записи в ней. Если такое пополнение уже есть в базе, просто отвечайте «200».
  3. Зачисляет фактическую сумму. Берите сумму из уведомления, а не из того, что клиент собирался заплатить. Клиент мог отправить меньше, больше или двумя переводами, и на каждый перевод придёт отдельное событие.
  4. Сохраняет всё в одной транзакции базы данных: запись о пополнении и изменение баланса.
  5. Отвечает «200» только после того, как всё записано. Если ответить раньше, а потом упасть, шлюз решит, что событие доставлено, и деньги клиента потеряются у вас в учёте.

Проверка подписи на Python занимает несколько строк:

import hmac, hashlib

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, (signature or "").strip().lower())

Пример на Node.js и полный формат событий есть в документации API.

Шаг 4. Если уведомление не дошло

Сервер может лежать, сертификат может истечь, обработчик может упасть на новой версии кода. На этот случай есть три уровня защиты.

  • Повторы. Если ваш сервер не ответил «200», шлюз повторит доставку с растущими интервалами. Короткий простой ничего не сломает.
  • Опрос статуса. Страница оплаты или фоновая задача может спросить у шлюза статус платежа по его номеру. Это запасной путь, а не основной.
  • Ежедневная сверка. Раз в день стоит сравнивать пополнения в кабинете шлюза с записями у себя. Отдельно проверяйте переводы, которые пришли на адрес после окончания его срока: деньги в этом случае уже на вашем балансе, но ваша система о них не знает, и их нужно вручную привязать к клиенту.

Шаг 5. Выплаты, если они нужны

Если клиенты выводят деньги с вашего сайта, порядок такой.

  1. Списываете сумму с баланса клиента у себя и создаёте заявку.
  2. Отправляете в шлюз запрос на выплату с уникальным ключом заявки. Если запрос оборвался и вы отправите его повторно с тем же ключом, вторая выплата не создастся.
  3. Ждёте уведомление: payout.signed означает, что деньги ушли, payout.failed или payout.rejected означает, что выплата не состоялась и деньги нужно вернуть клиенту на баланс.

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

Типичные ошибки

Ошибка Чем грозит Как избежать
Подпись не проверяется Кто угодно может «зачислить» себе баланс поддельным запросом Проверять HMAC по сырому телу, отклонять запрос без подписи
Нет проверки на повтор Одно пополнение зачисляется дважды Уникальный индекс в базе по сети, хешу и номеру записи
Зачисляется сумма счёта, а не перевода Недоплата превращается в убыток, переплата в жалобу Зачислять сумму из уведомления
«200» отправляется до записи в базу Пополнение теряется при сбое Отвечать после фиксации транзакции
API-ключ в коде страницы Ключ уводят и создают выплаты Ключ только на сервере, белый список IP
Ключ выплаты генерируется заново при повторе Двойная выплата при обрыве связи Ключ = номер заявки в вашей базе

Проверка перед запуском

Перед тем как открыть оплату всем, пройдите короткий список.

  • Тестовый перевод небольшой суммы в каждой включённой сети, с биржи и с личного кошелька.
  • Два перевода на один адрес: должны прийти два уведомления и два зачисления.
  • Перевод меньше ожидаемой суммы: зачисляется фактическая сумма.
  • Повторная отправка тестового уведомления из кабинета: второй раз баланс не меняется.
  • Запрос с неверной подписью: обработчик отвечает ошибкой и ничего не зачисляет.
  • Выплата с тем же ключом дважды: в шлюзе одна выплата.

Безопасность ключа

API-ключ даёт доступ к балансу, поэтому его стоит защитить дополнительно. Если шлюз позволяет, включите белый список IP: тогда запросы с ключом принимаются только с адресов ваших серверов, и украденный ключ без доступа к серверу бесполезен. Выплаты через кабинет лучше подтверждать вторым фактором.

Что уже сделано на стороне шлюза

Шаги из этой статьи касаются вашей стороны: кнопки, страницы оплаты, обработчика уведомлений и запросов на выплату. Всё, что происходит между переводом клиента и вебхуком, делает шлюз. Это наблюдение за четырьмя сетями, ожидание подтверждений, проверка отправителя и сбор средств. Без шлюза к этой статье добавилась бы вся серверная часть, и она самая ответственная.

Частые вопросы

Сколько времени занимает интеграция?

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

Можно ли обойтись без вебхуков?

Можно опрашивать статус платежа по API, но это медленнее и создаёт лишнюю нагрузку. Вебхуки удобнее как основной путь, а опрос и сверка полезны как запасные.

Нужна ли клиентам регистрация в шлюзе?

Нет. Клиент видит только адрес и переводит на него USDT со своего кошелька или биржи.


В KosPay приём бесплатный во всех четырёх сетях, вывод стоит фиксированно: 3 USDT в TRON, 1 USDT в BSC, Polygon и TON, газ сети включён. Адрес выдаётся одним запросом, уведомления подписаны HMAC, выплаты защищены ключом заявки, а подписываются на отдельном устройстве, вне сервера. Все запросы и события описаны в документации API, тарифы и подключение на главной странице.