Чек-лист интеграции криптоплатёжного шлюза

Что вы строите?

Четыре вещи, в этом порядке.

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

Обработка колбэка. Провайдер вызывает ваш эндпоинт при смене состояния платежа. Здесь большая часть настоящей работы и большая часть ошибок.

Сверка. Сопоставляйте проведённые суммы с заказами по расписанию, независимо от колбэков. Колбэки доставляются по сети, а сеть теряет данные.

Обработка исключений. Недоплата, истечение срока, переплата и отправка не в ту сеть требуют по решению каждая. Решать в продакшене — так и начинается очередь в поддержку.

Что нужно обработчику вебхуков?

Проверяйте подпись до разбора чего бы то ни было. Каждый серьёзный провайдер подписывает колбэки; неподписанный считайте враждебным трафиком.

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

Быстро возвращайте 200 и делайте работу потом. Обработчики, исполняющие заказы синхронно внутри вебхука, не укладываются в тайм-аут под нагрузкой, тайм-аут для провайдера выглядит как неудачная доставка, он повторяет — и вот у вас предыдущая проблема, умноженная на объём.

Никогда не доверяйте сумме в колбэке, не сверив её с заказом. Подтвердите, что проведённая сумма совпадает с ожидаемой, прежде чем что-либо отгружать.

Какие сбойные сценарии нужно протестировать?

Недоплата. Отправьте примерно на 2% меньше суммы инвойса. Провайдеры здесь различаются колоссально, и почти никто не документирует поведение. Одни зачисляют частичную сумму, другие удерживают до доплаты, третьи требуют ручного вмешательства. Решите, что делает ваш магазин с частично оплаченным заказом, до того, как такой заказ создаст покупатель.

Опоздавший платёж. Оплатите инвойс после истечения срока. Покупатель отправил реальные деньги на реальный адрес, а ваша система уже закрыла заказ по тайм-ауту. Что дальше — вопрос политики, и дефолт провайдера может не совпадать с вашей.

Не та сеть. Покупатель отправляет верный актив через сеть, которую вы не поддерживаете; гайд по сетям разбирает это подробно. Восстановление варьируется от автоматического до невозможного в зависимости от провайдера и сетей, и ответ должен быть в вашей документации для поддержки раньше, чем в тикете.

Что проверить перед запуском?

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

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

Куда смотреть дальше?

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

Что логировать и к чему привязывать

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

Логируйте и сырое тело колбэка, хотя бы на период хранения. Когда провайдер меняет поле или вы неверно его прочитали, исходная полезная нагрузка — единственное, что решает, что произошло на самом деле.

Ошибки окружений

Тестовые и боевые учётные данные в одном конфигурационном файле, различаемые флагом, который кто-то может случайно переключить. URL вебхука, указывающий на staging-хост в продакшене. Allowlist, привязанный к IP провайдера, который меняется без предупреждения.

Все три обычны, все три ломаются тихо, и все три ловятся одним чек-листом развёртывания, который кто-то действительно читает.

Передача

Запишите, где лежит отчёт о расчётах, у кого есть доступ и что делает задача сверки. Тот, кто построил интеграцию, понимает всё это и однажды перестанет быть тем, кто отвечает на вопрос о прошлом квартале.

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

Перед переключением трафика

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

Куда дальше

Гайд о вебхуках разбирает обработчик подробно, потому что именно там большая часть настоящей работы. Гайд по тестированию описывает живые проверки перед запуском, а подборка API для разработчиков ранжирует провайдеров по документации и качеству API, а не по общему баллу.

Что делать с изменениями у провайдера

Провайдеры меняют поля API, добавляют обязательные параметры и выводят эндпоинты из эксплуатации — обычно с уведомлением по почте тому, кто регистрировал аккаунт. Это часто не тот человек, который сопровождает интеграцию.

Убедитесь, что технический контакт — ролевой адрес, а не отдельный человек, и что его кто-то читает. Затем храните сырые полезные нагрузки колбэков на период хранения, чтобы при смене формы поля видеть, что именно пришло, а не восстанавливать по косвенным признакам.

Это скучно, и это разница между запланированным часом работы и сбоем, который обнаружил покупатель.