Ошибки платежей, отладка и мониторинг

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

Table of contents

• Кому и зачем этот гид
• Типология ошибок платежей в API
• Трассировка: как находить проблемные платежи
• Идемпотентность и вебхуки
• Retry policy и circuit breaker
• Мониторинг эквайринга: ключевые метрики
• Алертинг платежей: пороги и реакции
• Диагностика по провайдерам
• Возвраты, реверсалы и рекуррентные списания
• Безопасность и 3‑D Secure
• Сверка и расследования инцидентов
• Чек-лист отладки
• Вывод и следующий шаг

Кому и зачем этот гид

Если вы отвечаете за финтех-продукт, интернет-магазин или мобильное приложение, вам нужен предсказуемый платёжный поток. Ошибки платежей API встречаются всегда: от неправильных параметров запроса до отказов на стороне банка-эквайера и 3‑D Secure. В этой статье мы систематизируем причины отказов, покажем, как строить диагностику платежей, и дадим основу для постоянного мониторинга эквайринга и алертинга платежей.

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

Типология ошибок платежей в API

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

Категория	Пример кода или статуса	Что означает	Рекомендация
Клиентская 4xx	400 invalid_parameters	Неверные поля, формат или валидация	Исправьте запрос, добавьте схему валидации. Сверьтесь с основами интеграции.
Аутентификация	401 unauthorized, 403 forbidden	Ключи API, права доступа	Проверьте ключи, ротацию, границы IP.
Конфликт	409 conflict duplicate	Повторная отправка создания платежа	Используйте идемпотентность и ключи запросов, см. вебхуки и идемпотентность.
Бизнес‑отказ	insufficient_funds, do_not_honor	Решение эмитента отклонить операцию	Не ретрайте автоматически. Предложите другой метод, повтор позже или сплит платежа.
3DS требование	3ds_required, challenge_required	Нужна аутентификация держателя карты	Запустите 3‑D Secure, см. PCI и 3DS.
Сеть/таймаут	408, read timeout	Неизвестный исход операции	Примените безопасный повтор, затем сверку.
Ошибки провайдера 5xx	500, 502, 503	Проблема на шлюзе/эквайере	Включите retry policy и circuit breaker, возможен фоллбек на резервный маршрут, см. банки vs агрегаторы.
Вебхуки	delivery_failed, 5xx на приемнике	События не доставлены	Гарантируйте повторную доставку и идемпотентную обработку, см. вебхуки и идемпотентность.
Сверка	mismatch, missing_settlement	Расхождение списаний и зачислений	Запустите процедуру сверки, см. аналитика и сверка.

Трассировка: как находить проблемные платежи

Надежная диагностика платежей невозможна без единой корреляции по всем сервисам:

• payment_id — внутренний идентификатор платежа;
• idempotency_key — ключ запроса на создание;
• request_id и trace_id — сквозной идентификатор запроса в логах;
• provider_reference и rrn — ссылка на провайдера и Retrieval Reference Number из банковских логов;
• approval_code — код авторизации при успешном разрешении;
• webhook_event_id и version — идентификатор события и его версия.

Рекомендации по логированию:

• Логируйте на каждом хопе: вход клиента, вызов провайдера, обработка вебхука, постинговые операции capture/refund/void.
• Записывайте минимально достаточные персональные данные: токены карт вместо PAN, маскируйте чувствительные поля в соответствии с PCI DSS (см. PCI и 3DS).
• Стандартизируйте уровни: info для бизнес-состояний, warn для нестандартных, error для отказов, fatal для необработанных исключений.

Идемпотентность и вебхуки

Идемпотентность на операциях создания, подтверждения и возврата — способ исключить дубли. Правила:

• Используйте уникальный idempotency_key для каждой бизнес-операции. Повтор с тем же ключом должен возвращать тот же результат.
• Сохраняйте состояние вебхуков с версионированием событий. Если событие приходит повторно, обновляйте запись, а не создавайте новую.
• Подтверждайте прием вебхука только после успешной фиксации в вашей базе.

Подробное руководство по устойчивой доставке событий и ключам запросов — в разделе Вебхуки и идемпотентность.

Retry policy и circuit breaker

Грамотные повторы повышают конверсию без дубликатов. Базовые правила retry policy:

• Повторяйте 5xx, сетевые ошибки и таймауты. Не повторяйте 4xx валидационные и бизнес‑отказы.
• Используйте экспоненциальную задержку с джиттером: 0.5s, 1s, 2s, 4s… с рандомизацией, максимум 3–5 попыток.
• Разделяйте контексты: создание платежа, подтверждение capture и возврат — разные очереди повторов и разные лимиты.
• Для неизвестного исхода после таймаута запросите статус по payment_id у провайдера, прежде чем повторять создание.

Circuit breaker защищает ваши ресурсы и провайдера:

• Открывайте выключатель при росте доли 5xx или таймаутов на коротком окне, переводите трафик на резервного провайдера, если он есть.
• В состоянии half‑open пробуйте ограниченное число запросов; при успехе закрывайте выключатель.
• Логируйте причину открытия, длительность и влияние на конверсию.

Совет: для агрегаторов с несколькими маршрутами полезен роутинг по правилам — если падение авторизаций на провайдере X > 5% за 10 минут, перенаправляйте часть потока. Подробнее о выборе схемы работы — Банки против агрегаторов.

Мониторинг эквайринга: ключевые метрики

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

• Авторизационная конверсия: share успешных authorize из всех попыток.
• Capture success rate: доля успешно подтвержденных платежей от авторизованных.
• Refund success rate и скорость выполнения возвратов.
• Decline rate по причинам: insufficient_funds, do_not_honor, 3ds_required, suspected_fraud.
• Задержки: p95/p99 latency для authorize, capture, refund.
• Webhook lag: разница между временем события и временем его обработки.
• Доли 3‑D Secure challenge vs frictionless.
• Очереди повторов и dead‑letter queue, чтобы видеть застрявшие операции.

Не забудьте про разрезы: по BIN, стране эмитента, типу карты, провайдеру, приложению (iOS/Android/веб). Для мобильных приложений используйте SDK‑метрики и события ошибок, см. Интеграция мобайл SDK.

Алертинг платежей: пороги и реакции

Алертинг платежей должен быть шумонезависимым и сфокусированным на деньгах.

Метрика	Порог	Окно	Канал	Действие
Auth success rate	падение > 3 п.п. от базовой линии	10 мин	Pager	Проверить провайдер, включить circuit breaker, переключить маршрут
Ошибки 5xx провайдера	> 2% от всех вызовов	5 мин	Pager	Включить деградацию, ограничить ретраи
Таймауты authorize p95	> 4 с	10 мин	Slack/Email	Проверить сеть, увеличить timeout, сверка статусов
Webhook lag	> 5 мин задержки	15 мин	Slack	Расширить воркеры, отследить недоставленные события
Доля 3DS challenge	рост > 20%	30 мин	Email	Проверить настройки 3DS, выявить эмитентов с ухудшением
Отказы do_not_honor	рост > 30% в одном BIN	15 мин	Pager	Ограничить BIN‑роутинг, уведомить поддержку
Capture/refund stuck	операция без финального статуса > 30 мин	30 мин	Pager	Форсировать сверку и повтор безопасного статуса

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

Диагностика по провайдерам

Особенности провайдеров и эквайринговых API отличаются кодами и потоками событий. Подробности смотрите в отдельных справочниках:

• YooMoney: коды ответов, статусы холда и списания — YooMoney API.
• Сбербанк Эквайринг: статусы платежа и разбор RRN — Sberbank Acquiring API.
• T‑Bank: обработка 3DS и возвратов — T‑Bank API.
• Беларусбанк: потоки и расхождения по валютам — Belarusbank API.

Для безопасных проверок сценариев используйте песочницу: Тестовый стенд и sandbox.

Возвраты, реверсалы и рекуррентные списания

Возвраты и реверсалы подчиняются своим SLA и правилам сетей карт. Выделяйте их в отдельный поток мониторинга:

• Реверсал холда до списания чаще проходит мгновенно; после capture используйте refund, см. Возвраты и реверсалы.
• Отслеживайте частоту частичных возвратов и остатки к возврату.
• Для рекуррентных платежей важны ретраи при мягких отказах и корректная работа токенизации, см. Рекуррентные подписки.

Безопасность и 3‑D Secure

3‑D Secure повышает безопасность, но может влиять на конверсию. Контролируйте доли challenge и причины отказов на этапе аутентификации. Рекомендуется поддерживать флоу с переходом между фрикшенлес и челлендж‑сценарием по политикам эмитентов. Подробнее — в разделе PCI и 3DS.

Сверка и расследования инцидентов

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

• сопоставляйте authorize, capture, refund с банковскими реестрами;
• ищите пропавшие вебхуки и запрашивайте статусы по ссылочным идентификаторам;
• формируйте отчеты по дельтам и инициируйте автоматическое устранение.

Руководство и шаблоны отчетов — в материале Аналитика и сверка.

Чек-лист отладки

• Сверьте запрос с контрактом API, параметры и подписи. См. Основы интеграции.
• Найдите платеж по payment_id, request_id, provider_reference; проверьте все лог‑хопы.
• Убедитесь в корректности идемпотентности: нет ли дублирующих create с разными ключами.
• Посмотрите ретраи: причины, интервалы, итоги. Проверьте, не ретраятся ли 4xx бизнес‑отказы.
• Восстановите цепочку вебхуков: порядок, задержки, повторы; проверьте dead‑letter queue.
• Проанализируйте 3DS: был ли challenge, каков результат аутентификации.
• Оцените метрики провайдера: рост 5xx, таймаутов; при необходимости включите circuit breaker.
• Запустите сценарий в песочнице для воспроизведения, см. Sandbox.
• В мобильном приложении проверьте корректность SDK‑обработчиков ошибок и сетевых таймаутов, см. Интеграция мобайл SDK.

Вывод и следующий шаг

Ошибки платежей API — не форс-мажор, а управляемая часть процесса. При правильной диагностике платежей, внедрении идемпотентности, разумной retry policy и circuit breaker, а также при постоянном мониторинге эквайринга с продуманным алертингом платежей вы снижаете потери выручки и улучшаете клиентский опыт.

Дальше по плану: проверьте вашу интеграцию по чек-листу и подключите наблюдаемость по метрикам из этого материала. Если вы только начинаете интеграцию, начните с раздела Основы интеграции и заранее продумайте мониторинг, вебхуки и сверку.