Как подключить оплату в USDT на сайте: пошаговая интеграция через API
Подключить приём 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"}
В ответ приходит адрес и срок, до которого он закреплён за клиентом. Если клиент нажмёт кнопку ещё раз, пока срок не истёк, вернётся тот же адрес, а не новый. Это важно: клиент мог уже скопировать первый адрес и отправить на него деньги.
Идентификатор клиента лучше передавать тот, что уже есть в вашей базе. Шлюз вернёт его в уведомлении, и вы сразу поймёте, кому зачислять.
Шаг 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"}}
Обработчик делает пять вещей в таком порядке.
- Проверяет подпись. Шлюз считает HMAC-SHA256 от тела запроса и кладёт результат в заголовок. Вы считаете то же самое своим секретом и сравниваете. Считать нужно по сырому телу запроса, до разбора JSON: после разбора и повторной сборки строка может отличаться на пробел, и подпись не сойдётся.
- Отсекает повторы. Одно и то же событие может прийти дважды, например если ваш сервер ответил с задержкой. Ключ для проверки у пополнения — сеть, хеш транзакции и номер записи в ней. Если такое пополнение уже есть в базе, просто отвечайте «200».
- Зачисляет фактическую сумму. Берите сумму из уведомления, а не из того, что клиент собирался заплатить. Клиент мог отправить меньше, больше или двумя переводами, и на каждый перевод придёт отдельное событие.
- Сохраняет всё в одной транзакции базы данных: запись о пополнении и изменение баланса.
- Отвечает «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. Выплаты, если они нужны
Если клиенты выводят деньги с вашего сайта, порядок такой.
- Списываете сумму с баланса клиента у себя и создаёте заявку.
- Отправляете в шлюз запрос на выплату с уникальным ключом заявки. Если запрос оборвался и вы отправите его повторно с тем же ключом, вторая выплата не создастся.
- Ждёте уведомление:
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, тарифы и подключение на главной странице.