API для приёма платежей: как спроектировать интеграцию

Идемпотентность — обязательное требование

Сеть ненадёжна: запрос может уйти, а ответ — потеряться. Если клиентское приложение повторит попытку, без защиты появится второй платёж. Поэтому каждая операция создания платежа должна сопровождаться уникальным ключом идемпотентности.

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

Вебхуки: доверяй, но проверяй

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

• •Проверяйте подпись каждого входящего уведомления
• •Обрабатывайте повторные уведомления без побочных эффектов
• •Учитывайте, что статус может прийти не в хронологическом порядке
• •Отвечайте быстро, тяжёлую работу выносите в фоновую очередь

Состояния платежа в вашей системе

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

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

Обработка ошибок и повторов

Разделяйте ошибки на временные и постоянные. Таймаут или недоступность сервиса — повод повторить запрос с нарастающей задержкой. Ошибка валидации данных — повод остановиться и записать инцидент: повторы здесь бесполезны.

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

Сверка как обязательный процесс

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

Сверка — это не признак недоверия к системе, а нормальная финансовая практика. Обнаруженное на следующий день расхождение стоит несравнимо дешевле, чем найденное через квартал.

Безопасность и логирование

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

Полезная практика — логировать идентификатор операции и статус, но не тело запроса целиком. Это упрощает разбор инцидентов и снижает риски.

Тестирование нештатных сценариев

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

Для контроля API-платежей сверяйте статусы операций, уведомления и реестр.