Поддержка ЮKassa: диагностика ошибок и решение проблем оплаты

Поддержка ЮKassa: диагностика ошибок и решение проблем оплаты

Поддержка ЮKassa — это не только ответы на вопросы, но и чёткая методика, как быстро найти причину отказа и вернуть конверсию. Ниже — практическое руководство по отладке, если возникли проблемы с оплатой ЮKassa: платёж не прошёл, ошибка 3D Secure, СБП таймаут, чек не пришёл или возникло дублирование списаний.

Если вы только планируете запуск или обновляете приём платежей, загляните на страницы: Подключение, Платёжные методы, Оплата ЮKassa, Тарифы и комиссии.

Быстрый чек‑лист диагностики

Для продавца (мерчанта):

• Проверьте статус платежа в личном кабинете ЮKassa и в вашей CMS/CRM.
• Сверьте, не запущен ли тестовый режим и корректны ли ключи в проде.
• Убедитесь, что вебхуки доходят и ваш сервер отвечает 200 OK.
• Смотрите логи: idempotence-key, payment_id, order_id, статус.
• Уточните у покупателя: банк, способ (карта/СБП/SberPay), время, скрин ошибки.

Для покупателя (если общаетесь в первом уровне поддержки):

• Проверьте баланс, лимиты банка и корректность реквизитов.
• Подтвердите, что в приложении банка был получен пуш/SMS для 3D Secure или подтверждение СБП.
• Попробуйте другой способ оплаты или карту (например, СБП или SberPay).

Частые симптомы и быстрые решения

Ниже — быстрый справочник по типовым ситуациям.

Симптом	Вероятная причина	Что сделать
Платёж «в ожидании» слишком долго	Нет подтверждения 3D Secure или СБП, либо нет ответа вебхука	Попросите покупателя подтвердить в банке; проверьте доставку вебхуков и повторите отправку
Платёж не прошёл (отказ)	Банк-эмитент отклонил; неверные реквизиты; антифрод	Предложите другой способ или банк; включите альтернативы из Платёжных методов; проверьте риск-фильтры
Ошибка 3D Secure	Сбой ACS банка, истёк таймер подтверждения, неверный одноразовый код	Рекомендовать повтор с Wi‑Fi/мобильной сетью, обновить приложение банка, попробовать SberPay/СБП
СБП таймаут	Покупатель не подтвердил перевод в срок, банк недоступен	Предложить повтор, показать QR ещё раз; проверить, верно ли выбран банк в СБП
Дублирование списаний	Несоблюдение идемпотентности, повторное создание платежа при таймауте	Используйте одинаковый idempotence-key для повторов; выполняйте capture один раз
Чек не пришёл	ККТ офлайн, ошибка фискализации, некорректная номенклатура	Проверьте настройки ККТ и ОФД, отправьте чек повторно, см. ККТ и 54‑ФЗ, Чеки ЮKassa

Ошибки 3D Secure: почему не удаётся подтвердить платёж

При ошибке 3D Secure в ЮKassa (ошибка 3D Secure ЮKassa) платёж отклоняется банком-эмитентом на этапе аутентификации. Частые причины:

• покупатель не подтвердил операцию в приложении банка (истёк таймер);
• SMS с одноразовым кодом не пришла или введён неверный код;
• сбой ACS сервера банка или нестабильный интернет у клиента;
• устройство/браузер блокирует редирект или iframes.

Что сделать:

• Попросите клиента обновить банковское приложение и повторить оплату в другом браузере или в режиме инкогнито.
• Рекомендовать альтернативу: СБП или SberPay (см. Sberbank — ЮKassa).
• На стороне интеграции: не прерывайте сессию во время редиректа на 3DS, храните состояние заказа, корректно обрабатывайте возврат с параметрами успеха/неуспеха.

Советы по UX:

• Показать таймер и подсказки: «Не закрывайте окно — подтвердите платёж в приложении банка».
• Предлагать запасной вариант «Оплатить через СБП» при повторном отказе 3DS.

СБП таймаут: что это и как исправить

СБП таймаут — ситуация, когда покупатель не подтвердил перевод в своём банке в отведённое время или банк временно недоступен. Нюансы:

• Обычно таймаут составляет несколько минут; после — платёж меняет статус на «canceled/expired».
• При повторе не создавайте новый заказ без сверки предыдущего статуса — исключайте дублирование.

Решения:

• Предложить покупателю открыть приложение банка заранее и включить уведомления.
• Отображать QR-код повторно и давать явную кнопку «Открыл банк — продолжить».
• Проверить, корректно ли вы передаёте реквизиты СБП в соответствии с документацией (см. Интеграция API).

Дублирование списаний: причины и профилактика

Дублирование списаний — одна из самых неприятных проблем с оплатой ЮKassa. Главные источники:

• Несоблюдение идемпотентности: при таймауте вы создаёте новый платёж с новым idempotence-key и тем же заказом.
• Повторный capture при уже подтверждённой операции.
• Повтор клика по кнопке «Оплатить» из-за задержки ответа.

Как предотвратить:

• Генерируйте idempotence-key на уровне заказа и используйте его при всех повторах запроса.
• Делайте capture в транзакции с проверкой статуса: выполняйте только если статус waiting_for_capture.
• Блокируйте кнопку «Оплатить» после первого нажатия и показывайте индикатор ожидания.
• На бэке применяйте очереди и взаимные блокировки по order_id.

Если дубль уже произошёл:

• Сверьте статусы обеих операций в ЛК и по API.
• Оформите возврат одной из операций (см. Возвраты и чарджбек).
• Зафиксируйте инцидент и обновите политику идемпотентности.

Чеки и фискализация: «чек не пришёл»

Фискализация по 54‑ФЗ — обязательный этап для продаж. Когда «чек не пришёл ЮKassa», проверьте:

• статус ККТ и ОФД в ЛК; не офлайн ли касса;
• корректность номенклатуры (признак предмета расчёта, ставка НДС, признак способа платежа);
• не тестовый ли режим или дубль чека по одному заказу;
• корректность e‑mail/телефона покупателя.

Действия:

• Повторная отправка чека из ЛК/через API.
• Проверка очереди чеков, устранение ошибок ККТ и синхронизация с ОФД.
• Актуализируйте настройки по 54‑ФЗ: см. ККТ и 54‑ФЗ и раздел Чеки ЮKassa.

Статусы платежей и сверка

Понимание статусов помогает верно отрабатывать бизнес-логику:

• pending — создан, ожидает действия клиента/банка;
• waiting_for_capture — заморожены средства, нужно списать (capture);
• succeeded — успешно оплачено;
• canceled/expired — отменён или истёк срок подтверждения.

Рекомендации по сверке:

• Сверяйте статусы по API и в отчётах (см. Отчёты и сверка).
• Не меняйте статус заказа в CMS до получения финального вебхука succeeded/canceled.
• Для холд‑схемы (two‑step) автоматизируйте capture и отмену по SLA.

Справочник по ошибкам интеграции:

Код/Статус	Что значит	Что делать
400 Bad Request	Некорректные данные запроса	Проверить схему, суммы, валюту, номенклатуру
401 Unauthorized	Неверные ключи/токен	Сверить окружение и ключи, см. Интеграция API
403 Forbidden	Недостаточно прав или антифрод	Проверить доступ, риск‑настройки, попробовать другой метод
404 Not Found	Платёж/чек не найден	Сверить идентификатор, журнал запросов
409 Conflict	Конфликт идемпотентности	Используйте постоянный idempotence-key на заказ
429 Too Many Requests	Лимит запросов	Включить ретраи с backoff
5xx	Сторонняя ошибка	Повторить попытку по стратегии восстановления

Интеграция: API, вебхуки, редиректы

Ключевые точки отказа в интеграции ЮKassa:

• Несогласованность окружений (test/prod): ключи перепутаны, реальный платёж идёт в тест.
• Вебхуки: ваш сервер не принимает подпись/не отвечает 200 OK, из‑за чего не обновляется статус заказа.
• Редиректы и возвраты: теряется контекст сессии после 3D Secure/SBП.

Проверки и best practices:

• Синхронизируйте время сервера через NTP — иначе подписи по времени могут не сходиться.
• Валидируйте подпись вебхука и логируйте payload целиком, удаляя чувствительные данные.
• Имейте очередь повторной доставки вебхуков и идемпотентные обработчики.
• Используйте стандартные статусы ЮKassa, не придумывайте собственных переходов.
• Для SberPay и платежей через Сбер смотрите рекомендации на странице Sberbank — ЮKassa.

Что передать в поддержку, чтобы ускорить решение

Чтобы поддержка ЮKassa оперативно разобралась, заранее подготовьте:

• merchant_id (shopId) и название магазина;
• payment_id (из ЛК/логов) и номер/идентификатор заказа;
• сумма, валюта, способ оплаты (карта/СБП/SberPay);
• дата/время (с часовым поясом), скрин ошибки и URL шага, где она возникла;
• для карт — только первые 6 и последние 4 цифры; не передавайте полный PAN, CVV и пароли.

Также приложите технические детали:

• idempotence-key, HTTP‑коды ответов, выдержки из логов обработчика вебхуков;
• была ли попытка повторной оплаты и сколько раз;
• поведение в вашей CMS/CRM: какой статус присвоился заказу.

Профилактика ошибок и безопасность

• Идемпотентность и очереди: все операции по одному заказу должны быть атомарны и повторяемы без побочных эффектов.
• Retriable‑стратегии: используйте экспоненциальный backoff на 5xx/429, но не создавайте новые платежи без необходимости.
• UX‑подсказки: объясняйте 3D Secure и СБП, показывайте таймер и шаги подтверждения.
• PCI DSS и токенизация: храните минимум платёжных данных, см. Безопасность и PCI DSS.
• Альтернативные методы: подключите СБП/SberPay/кошельки для снижения отказов — см. Платёжные методы.

Для нюансов возвратов и споров ознакомьтесь с разделом Возвраты и чарджбек.

Итоги и что делать дальше

Проблемы с оплатой ЮKassa чаще всего решаются быстрым чек‑листом: проверить статусы, вебхуки и идемпотентность, дать клиенту понятный повторный сценарий (альтернативный метод оплаты, повтор подтверждения 3DS или СБП). Если «платёж не прошёл ЮKassa», возникла ошибка 3D Secure, СБП таймаут, чек не пришёл или заметили дублирование списаний — действуйте по инструкциям выше, а для тонкой отладки используйте разделы Интеграция API, Отчёты и сверка и FAQ.

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