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

Авторизация

Запросы подписываются ключом API. Ключ хранится только на сервере: с фронтенда платёжные ручки не вызываются никогда.

Создание счёта

POST /api/invoice/
{ "amount": "149.00", "currency": "USDT", "order_id": "A-1024" }

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

Обработка вебхука

Идемпотентность

Одно и то же уведомление может прийти несколько раз. Обработчик обязан быть идемпотентным: повторный вызов не должен второй раз отгружать товар.

Проверка подписи

Перед обработкой проверьте подпись запроса и сумму. Доверять телу вебхука без проверки нельзя.

Типовые ошибки

  • сумма берётся из вебхука, а не сверяется с заказом;
  • обработчик отвечает 200 до того, как записал результат;
  • ключ API попадает в клиентский бандл;
  • таймаут вебхука меньше времени обработки заказа.