Интеграция крипто-платёжного API следует предсказуемой форме независимо от провайдера: вы создаёте счёт, перенаправляете или встраиваете чекаут, получаете асинхронные вебхуки по мере продвижения платежа, проверяете их и сверяете с собственными записями. Сложная часть — не благоприятный путь, а крайние случаи.
Основной поток
Большинство шлюзов предоставляют REST API с одинаковым жизненным циклом. Вы вызываете его на стороне сервера (никогда не раскрывайте API-ключ в браузере) и относитесь к вебхуку — а не к редиректу браузера — как к источнику истины о том, оплачен ли заказ.
Сначала спроектируйте конечный автомат состояний заказа: ожидание → недоплата/оплачено → подтверждено → завершено, с явными ветвями для истёкших и переплаченных. Проработка этого заранее предотвращает запутанные условия, ведущие к двойному исполнению.
- Создайте счёт с суммой, валютой, ID заказа и URL вебхука.
- Покажите размещённый чекаут или сами отрендерите адрес и сумму.
- Получайте вебхуки на каждое изменение состояния и проверяйте их подпись.
- Убедитесь, что платёж набрал нужные подтверждения, прежде чем исполнять.
- Сверьте вебхук с ончейн-транзакцией и вашим заказом.
Создание счёта
Счёт привязывает конкретную сумму к конкретному заказу на ограниченное время. Отправьте ID заказа как метаданные, чтобы вебхук можно было сопоставить без догадок, и сохраните ID счёта, который возвращает шлюз.
Котировки истекают — шлюз фиксирует курс на несколько минут. Сохраняйте срок и статус счёта, чтобы ваш интерфейс мог показать обратный отсчёт и чтобы поздний платёж обрабатывался как случай сверки, а не потерянный заказ.
Вебхуки — источник истины
Редирект браузера после оплаты — удобство, а не гарантия: пользователь может закрыть вкладку. Вебхук, который получает ваш сервер, — вот на что вы реагируете. Проверяйте каждый вебхук: проверьте подпись (обычно HMAC по сырому телу с вашим секретом) прежде чем доверять хоть одному полю.
Сделайте обработку вебхуков идемпотентной. Шлюзы повторяют доставку, поэтому одно и то же событие «оплачено» может прийти дважды; привяжите обработку к ID события или счёта и сделайте повторные доставки холостыми. Быстро возвращайте 2xx и делайте медленную работу асинхронно, чтобы шлюз не отваливался по таймауту и не повторял зря.
Подтверждения и окончательность
Платёж можно увидеть (в мемпуле или с нулём подтверждений) задолго до его окончательности. Определите порог подтверждений, соответствующий сумме и сети, и исполняйте только по его достижении. Для малых платежей стейблкоинами в быстрых сетях это быстро; для крупных сумм ждите больше.
Защищайтесь от реорганизаций и двойных трат, доверяя состоянию «подтверждено» от шлюза, а не собственному первому наблюдению, и не отдавая товар по платежу с нулём подтверждений, если только вы не принимаете риск.
Сверка и режимы сбоя
Сверка — ежедневная работа по доказательству того, что каждый «оплаченный» заказ соответствует реальной ончейн-транзакции и наоборот. Храните хэш транзакции, полученную сумму и сеть на каждом заказе, чтобы расхождение было запросом, а не расследованием.
Явно планируйте недоплаты (покупатель прислал слишком мало), переплаты (вернуть разницу или зачесть), отправки не в ту сеть и счета, истёкшие-затем-оплаченные. Это не редкие крайние случаи на масштабе — это еженедельные события, и система, которая обрабатывает их тихо, и есть настоящий «production-ready».
Часто задаваемые вопросы
Чему доверять — редиректу браузера или вебхуку?
Вебхуку. Редирект можно потерять, если пользователь закроет вкладку, и его можно подделать. Проверяйте подпись вебхука на стороне сервера и относитесь к нему как к авторитетному сигналу, что заказ оплачен.
Как не дать обработать вебхук дважды?
Сделайте обработку идемпотентной. Шлюзы повторяют доставку, поэтому привяжите логику к ID счёта или события и сделайте повтор холостым. Никогда не исполняйте заказ дважды из-за повторного события «оплачено».
Сколько подтверждений ждать?
Зависит от суммы и сети. Малые платежи стейблкоинами в быстрых сетях можно считать окончательными почти сразу; крупные суммы оправдывают больше подтверждений. Используйте состояние «подтверждено» от шлюза, а не собственное первое наблюдение.
Что делать, если клиент недоплатил или переплатил?
Обрабатывайте оба случая явно. Шлюзы отмечают недоплаты, так что вы можете запросить разницу или вернуть; при переплатах вы возвращаете излишек или зачитываете его. Проработка этих ветвей заранее и отличает демо от продакшена.