Интеграция с платёжным API — не про то, как отправить один запрос. Она про то, что происходит, когда запрос повторился, ответ потерялся, а вебхук пришёл дважды. Собрали правила, которые экономят недели отладки и предотвращают расхождения в деньгах.
Идемпотентность — обязательное требование
Сеть ненадёжна: запрос может уйти, а ответ — потеряться. Если клиентское приложение повторит попытку, без защиты появится второй платёж. Поэтому каждая операция создания платежа должна сопровождаться уникальным ключом идемпотентности.
Ключ генерируется на стороне вашего сервиса и привязывается к заказу. При повторе с тем же ключом система возвращает результат первой операции, а не создаёт новую.
Вебхуки: доверяй, но проверяй
Уведомления о статусе — основной механизм получения результата. Но обрабатывать их нужно с оглядкой на три свойства: они могут прийти повторно, прийти не по порядку и прийти от кого угодно, если не проверять подпись.
- Проверяйте подпись каждого входящего уведомления
- Обрабатывайте повторные уведомления без побочных эффектов
- Учитывайте, что статус может прийти не в хронологическом порядке
- Отвечайте быстро, тяжёлую работу выносите в фоновую очередь
Состояния платежа в вашей системе
Не копируйте статусы провайдера один в один. Заведите собственную модель состояний, понятную вашей бизнес-логике: создан, ожидает оплаты, оплачен, отклонён, возвращён.
Переходы между состояниями должны быть односторонними там, где это логично: оплаченный заказ не должен вернуться в состояние «ожидает оплаты» из-за запоздавшего уведомления.
Обработка ошибок и повторов
Разделяйте ошибки на временные и постоянные. Таймаут или недоступность сервиса — повод повторить запрос с нарастающей задержкой. Ошибка валидации данных — повод остановиться и записать инцидент: повторы здесь бесполезны.
Ограничивайте число повторов и всегда логируйте итоговый результат. Бесконечные ретраи создают нагрузку и маскируют реальную проблему.
Сверка как обязательный процесс
Даже при идеальной обработке вебхуков часть событий может потеряться. Поэтому нужна регулярная сверка: ежедневно сравнивайте свой реестр операций с реестром провайдера и разбирайте расхождения.
Сверка — это не признак недоверия к системе, а нормальная финансовая практика. Обнаруженное на следующий день расхождение стоит несравнимо дешевле, чем найденное через квартал.
Безопасность и логирование
Ключи доступа хранятся только на сервере и не попадают в клиентский код и репозиторий. Логи не должны содержать полные платёжные реквизиты и персональные данные в открытом виде.
Полезная практика — логировать идентификатор операции и статус, но не тело запроса целиком. Это упрощает разбор инцидентов и снижает риски.
Тестирование нештатных сценариев
Проверяйте не только успешный путь. Смоделируйте потерю ответа, двойной вебхук, отклонённую операцию, частичный возврат и запоздавшее уведомление. Именно эти сценарии вызывают проблемы в продакшене.
Для контроля API-платежей сверяйте статусы операций, уведомления и реестр.
Темы: платёжное API, интеграция платежей, вебхуки платежей, идемпотентность, API эквайринга
