Как принимать платежи USDT на сайте одним вызовом API

Принимайте USDT с Suawave: создайте адрес приёма, покажите сеть и QR-код, проверяйте callback и обновляйте заказ после перевода средств.

Опубликовано , обновлено

Чтобы принимать платежи USDT с Suawave, создайте адрес приёма, указав свой адрес выплат и HTTPS callback URL. Покажите покупателю адрес, сеть и минимальную сумму. Проверяйте подпись каждого callback, связывайте событие с заказом и выполняйте заказ только после того, как callback о подтверждённом платеже показывает достаточную сумму USDT.

Один вызов API из заголовка создаёт адрес приёма. Сайту также нужны страница оплаты и обработчик callback. Весь процесс описан в руководстве по быстрому старту Suawave.

1. Выберите сеть и узнайте минимум

Используйте тикер, который определяет и сеть, и актив. В примерах используется trc20/usdt, то есть USDT в сети TRON. Показывайте сеть на всех этапах оплаты: одного обозначения «USDT» недостаточно, чтобы покупатель правильно отправил платёж.

Перед созданием заказа выполните GET /trc20/usdt/info/:

curl "https://api.suawave.com/trc20/usdt/info/"

Прочитайте minimum_transaction_coin из ответа. Храните суммы как десятичные строки и используйте точную десятичную арифметику или целое число минимальных единиц актива.

Берите минимумы и комиссии из соответствующих источников:

Сведения для страницы оплаты Источник
Минимальный платёж для выбранного тикера minimum_transaction_coin из info или create
Поля комиссий для созданного адреса Ответ create
Фактическая сумма перевода по поступлению value_forwarded_coin в callback о подтверждённом платеже

Порядок удержаний описан в руководстве по комиссиям и минимумам. Эндпоинт оценки стоимости перевода не даёт котировку комиссии, которая удерживается из поступления USDT: он возвращает настроенную верхнюю оценку в нативной монете сети.

2. Создайте адрес приёма

Сохраните на сервере идентификатор заказа и новый непредсказуемый nonce. Добавьте оба значения в callback URL, чтобы обработчик мог сверить их с сохранённым заказом.

Вызовите GET /trc20/usdt/create/ с адресом выплат и этим callback URL. Запрос соответствует примеру быстрого старта; перед использованием замените условный адрес, идентификатор заказа и nonce своими значениями:

curl -G "https://api.suawave.com/trc20/usdt/create/" \
  --data-urlencode "address=TXyzPayoutAddressExample0000000000000" \
  --data-urlencode "callback=https://shop.example/hook?order=1001&nonce=7f3a9c" \
  --data-urlencode "pending=1"

Короткий nonce выше служит заглушкой, а не образцом генерации. Создавайте nonce криптографическим генератором случайных чисел вашей платформы.

Сохраните полученный address_in вместе с заказом. На этот адрес платит покупатель. address_out служит адресом ваших выплат; если перепутать их, процесс оплаты нарушится.

Каноническая пара тикер и callback определяет заказ. Повторный запрос для этой пары возвращает существующий адрес приёма, а первый вызов фиксирует параметры callback. Другой адрес выплат для той же пары отклоняется. Используйте отдельный callback URL для каждого заказа, который хотите отслеживать независимо.

В справочнике API описаны канонизация callback URL и полный набор параметров create. Используйте HTTPS для эндпоинта callback и URL-кодируйте каждое значение query-параметра. Callback на частные и loopback-адреса отклоняются.

3. Покажите адрес приёма и QR-код

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

Вызовите GET /trc20/usdt/qrcode/ с фактическим address_in из create. Этот пример документации также использует условный адрес и сумму:

curl -G "https://api.suawave.com/trc20/usdt/qrcode/" \
  --data-urlencode "address=TDepositAddressExample0000000000" \
  --data-urlencode "value=25.5"

Ответ содержит qr_code, data URI изображения PNG для атрибута источника картинки, и payment_uri, точный текст, закодированный в QR.

Для TRON в QR кодируется только адрес приёма. API проверяет value, но не включает его в содержимое QR. Покупатель должен ввести сумму в кошельке. Для EVM-токенов запрос с value кодирует запрос перевода токенов EIP-681; поддержка зависит от кошелька, и плательщик может иметь возможность изменить сумму.

Сканирование QR не подтверждает оплаченную сумму. Её определяет обработчик callback по проверенным данным платежа.

4. Проверяйте каждый callback до изменения заказа

По умолчанию callback приходят как GET-запросы. Параметр post=1 при create выбирает form POST; json=1 выбирает JSON POST и имеет приоритет над post=1. Ваши собственные query-параметры callback остаются в URL.

Прочитайте заголовок x-ca-signature и проверьте его публичным ключом из GET /pubkey/. Для GET используется точный полный URL, включая исходный порядок query-параметров. Для POST используется исходное тело запроса до разбора. Следуйте примерам проверки подписей для своего языка.

После проверки сопоставьте идентификатор заказа и nonce с сохранёнными значениями. Также проверьте address_in и coin: для тикера trc20/usdt поле coin в callback имеет значение trc20_usdt.

При pending=1 допустимое поступление может вызвать следующие события:

Поле callback Значение события Действие страницы оплаты
pending равно "1" Поступление обнаружено Показывать ожидание, не выполнять заказ
pending равно "0" Транзакция перевода подтверждена Сопоставить подтверждённую сумму с заказом

У событий pending и confirmed разные UUID. Повторные доставки одного события сохраняют тот же UUID. Надёжно сохраняйте обработанные UUID, чтобы повторная попытка не приводила к выполнению заказа дважды.

5. Запишите платёж и подтвердите получение

Callback о подтверждённом платеже содержит value_coin, сумму поступления; fee_coin, удержанную комиссию; и value_forwarded_coin, сумму, поступившую на адрес выплат. Определите, какая сумма учитывается по правилам вашего магазина, и сравнивайте её с помощью точной арифметики.

Сохраните событие и связанное изменение заказа вместе до подтверждения получения. Верните HTTP 200 с обычным текстом *ok* в течение 30 секунд. Для уже обработанного события пропустите повторную работу и верните то же подтверждение.

Из-за повторных попыток callback могут приходить не по порядку. Позднее событие pending не должно возвращать подтверждённое поступление в ожидание. Правила подтверждения получения, повторных попыток и порядка событий описаны в руководстве по callback.

Если callback отсутствует, GET /trc20/usdt/logs/ позволяет получить историю переводов и доставки по исходному callback URL. Используйте его как резервный способ сверки. Результат sent означает, что перевод подтверждён, но получение confirmed callback не подтверждено, в том числе после исчерпания повторных попыток.

Что происходит с небольшими и повторными платежами?

Какова минимальная сумма платежа USDT?

Прочитайте minimum_transaction_coin для выбранного тикера вместо того, чтобы прописывать фиксированную сумму на странице оплаты. К поступлению применяется минимум, действующий на момент его первого обнаружения.

Что делать, если покупатель отправляет меньше суммы заказа?

Различайте сумму заказа и минимум тикера. Допустимое поступление может быть меньше стоимости заказа. Оставляйте заказ неоплаченным, пока проверенные подтверждённые поступления не удовлетворят вашим правилам учёта суммы. Каждое допустимое поступление переводится отдельно и имеет собственный confirmed callback, поэтому исключайте повторные события до суммирования.

Поступление ниже минимума тикера не переводится, не вызывает callback и не попадает в публичные журналы. Страница оплаты должна ясно показывать минимум до отправки средств.

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

В этой интеграции выполняйте заказ при pending, равном "0", после проверки подписи и данных заказа. Это событие следует за подтверждением транзакции перевода. Обнаружение поступления, сканирование QR или ответ API на create не подтверждают оплату заказа.