Статусы платежей YooKassa: как читать и что делать на каждом этапе

Статусы платежей YooKassa: как читать и что делать на каждом этапе

Зачем нужны статусы платежей

Статусы платежей YooKassa помогают бизнесу и пользователям понимать, на каком этапе находится операция: создана, авторизована, подтверждена, отменена или возвращена. Корректная обработка статусов — основа для:

• точной отгрузки товара/оказания услуги;
• понятной коммуникации с клиентом;
• автоматизации кассовых чеков и уведомлений;
• снижения отказов и спорных ситуаций.

Если вы работаете через личный кабинет и без интеграции, статусы видны в разделе «Мои платежи». При работе по API они приходят в ответах и вебхуках — поэтому важно правильно настроить приём уведомлений и логику повторных запросов.

Жизненный цикл платежа в YooKassa

Ниже — обобщённая схема того, как платёж проходит через систему.

Типовой путь:

1. Клиент инициирует оплату → создаётся платёж (статус pending).
2. Покупатель подтверждает платёж (например, 3‑D Secure), провайдер бронирует сумму на карте.
3. Для двухстадийной схемы платёж получает статус waiting_for_capture — средства зарезервированы и ждут вашего подтверждения (capture).
4. После подтверждения продавцом платёж становится succeeded — деньги списаны.
5. Если подтверждение не выполнено вовремя или произошла ошибка/отмена, платёж переходит в canceled.
6. Дополнительно возможны возвраты уже успешных платежей — это отдельные объекты (refund), подробно в справке по возвратам.

Ключевые статусы: расшифровка и действия

Ниже — краткий разбор основных статусов платежей YooKassa. Обратите внимание: в API V3 названия статусов используются на английском в нижнем регистре.

pending — платёж создан и ждёт обработки

• Что значит: платёж инициирован, но ещё не авторизован или требует действия от клиента (подтверждения в банке/кошельке). Иногда это промежуточный этап перед 3‑D Secure.
• Как долго: зависит от метода оплаты и действий покупателя. Если клиент закрывает страницу или не проходит аутентификацию, платёж может позже отмениться.
• Что делать бизнесу: показывать пользователю понятные подсказки, хранить ссылку на продолжение оплаты, не отгружать товар до смены статуса. Если pending «зависает», опционально предложить клиенту повторить попытку.

waiting_for_capture — деньги зарезервированы, ждут подтверждения

• Что значит: платёж успешно авторизован, средства заблокированы на карте клиента/кошельке. Нужно подтвердить списание (capture), чтобы получить деньги.
• Как долго: период подтверждения ограничен настройками и правилами платёжных систем; по умолчанию это ограниченный срок (как правило, до нескольких дней). Если его пропустить, операция будет отменена автоматически.
• Что делать бизнесу: выполнить capture по API или через ЛК, при необходимости — частичный capture (на меньшую сумму). После capture можно отгружать товар.

succeeded — платёж успешно завершён

• Что значит: деньги списаны и будут зачислены согласно регламентам.
• Что делать бизнесу: отгрузить заказ, выдать чек, отправить подтверждение клиенту. При необходимости оформить полный/частичный возврат (refund) — через ЛК или API.

canceled — платёж отменён

• Что значит: списание не произошло. Причины — отказ банка, не пройден 3‑D Secure, истёк срок подтверждения, явная отмена продавцом или покупателем.
• Что делать бизнесу: предложить пользователю оплатить заново, проверить корректность сценария оплаты и подсказок. Изучить детали отмены в API (cancellation_details) и скорректировать UX.

Таблица статусов и действий продавца

Статус	Что означает	Действия продавца	Срок/ограничения	Подсказка по API
pending	Платёж создан, ожидает подтверждения от клиента/системы	Ничего не отгружать, ждать финального статуса. Напомнить клиенту завершить оплату	Зависит от метода	Проверяйте объект payment по id, слушайте вебхуки
waiting_for_capture	Сумма авторизована, требуется capture	Подтвердить списание полностью или частично, либо отменить	Подтверждение доступно ограниченное время	POST /payments/{id}/capture, идемпотентность обязательна
succeeded	Платёж успешно списан	Отгрузка/оказание услуги, чек, уведомление клиента	Финально	Обрабатывайте вебхук succeeded для бизнес‑триггеров
canceled	Платёж отменён	Предложить повторную оплату, устранить причину (UX/техническую)	Финально	Смотрите cancellation_details для причины отмены

Подробнее о методах и полях — в обзоре API V3 и разделах Payments API.

Где смотреть статусы: ЛК и API

• Личный кабинет: откройте раздел «Мои платежи» после входа. Там доступен поиск по заказам, фильтры и детальные карточки. Если нет доступа — проверьте права и решите вопросы со входом в разделе «Проблемы со входом».
• Возможности ЛК: экспресс-управление оплатами, возвратами и отчётами — см. обзор возможностей.
• API и вебхуки: подключите уведомления, чтобы получать смену статусов в реальном времени. Рекомендации и схемы — в API V3: Payments и обзоре API.

Что делать на каждом этапе: краткие алгоритмы

• Когда pending:

  • Показывайте прогресс оплаты и понятные инструкции (особенно для 3‑D Secure/подтверждений).
  • Храните ссылку на продолжение оплаты и кнопку «Попробовать снова».
  • Не бронируйте склад и не отгружайте до финального статуса.

• Когда waiting_for_capture (двухстадийная оплата):

  • Быстро выполните capture — автоматически (по бизнес-правилам) или вручную через ЛК.
  • При частичной отгрузке — используйте частичный capture на фактическую сумму.
  • Если отказались от заказа — отмените платёж, чтобы разблокировать средства у клиента.

• Когда succeeded:

  • Отправьте подтверждение, чек и запустите процесс отгрузки.
  • Сохраните данные транзакции в учёте и CRM.
  • При возврате — создайте refund и уведомите клиента; подробнее — справка по возвратам.

• Когда canceled:

  • Проанализируйте причину. Если истёк срок подтверждения — ускорьте capture в будущем. Если отказ банка — предложите альтернативный метод оплаты.
  • Дайте клиенту удобный способ повторить попытку (оплата ссылкой или счётом — см. ссылки и счета).

Типичные проблемы и решения

• «Платёж завис в pending»:

  • Проверьте, доводит ли пользователь подтверждение до конца (UX, мобильные редиректы, подсказки). Убедитесь, что все редиректы работают на основном домене, без лишних зеркал — см. домены и зеркала.
  • В мобильных браузерах используйте безопасные редиректы и отслеживайте возвращение на сайт после 3‑D Secure. О тестовой оплате на сайте — в разделе оплата на сайтах.

• «waiting_for_capture длится слишком долго»:

  • Настройте автоматический capture после успешной авторизации по вашим правилам (например, после проверки наличия товара).
  • Следите за сроком подтверждения. Если вы не успеваете — перестройте процесс, чтобы не терять оплату.

• «Нужен частичный capture/частичный возврат»:

  • Частичный capture возможен в двухстадийной схеме: спишите только доступную к отгрузке часть.
  • Частичный возврат делайте из ЛК или по API; внимательно ведите учёт, см. справку по возвратам.

• «Много отмен (canceled)»:

  • Проверьте UX: понятные ли ошибки, не истекает ли сессия, корректны ли подсказки по 3‑D Secure.
  • Изучите cancellation_details: если часто «истёк срок подтверждения», автоматизируйте capture. Если «отказ банка» — предлагайте альтернативные методы оплаты.
  • Поднимите уровень защиты и доверия — рекомендации в разделе безопасность платежей.

Лучшие практики интеграции API V3

• Обрабатывайте все статусы: pending, waiting_for_capture, succeeded, canceled. Не полагайтесь только на redirect‑страницы; используйте вебхуки.
• Идемпотентность: для POST‑запросов (create, capture, refund) всегда передавайте уникальный Idempotence-Key, чтобы избежать двойных списаний при повторах.
• Повторы запросов: реализуйте ретраи с экспоненциальной задержкой. Не забывайте проверять текущий статус перед повтором.
• Логи и трассировка: фиксируйте корреляционные идентификаторы платежей и ответы API — это ускоряет разбор инцидентов.
• Тестирование в песочнице: прогоните все ветки статусов, в т.ч. ошибки и отмены. Подробности — в обзоре API V3 и Payments API.

Частные сценарии: двухстадийная оплата, подписки, счета

• Двухстадийная оплата (pre-auth):

  • Этапы: pending → waiting_for_capture → succeeded/canceled.
  • Подходит для проверки наличия товара, динамической цены, частичной отгрузки.

• Одностадийная оплата (auto-capture):

  • Списывает сразу после авторизации: pending → succeeded/canceled.
  • Удобно для цифровых товаров и мгновенного доступа.

• Подписки и регулярные списания:

  • Рекомендуется тщательно обрабатывать ошибки авторизации и повторять попытки. Важно корректно информировать клиента о статусе и причинах отказа.

• Счета и платёжные ссылки:

  • Для повторных попыток и удалённых оплат используйте ссылки и счета. Следите за актуальным статусом, особенно если клиент платит позже.

FAQ по статусам платежей YooKassa

• Как понять, почему платёж canceled?

  • В ответе API смотрите cancellation_details (кто отменил и по какой причине). В ЛК — откройте карточку платежа в «Мои платежи».

• Сколько держится waiting_for_capture?

  • Срок зависит от метода и настроек. Рекомендуем подтверждать как можно быстрее, чтобы избежать автоматической отмены.

• Можно ли сделать частичный capture?

  • Да, если платёж в waiting_for_capture. Списывайте ровно ту сумму, которую готовы отгрузить.

• Успешный платёж — это всегда succeeded?

  • Да. «succeeded платёж YooKassa» означает, что списание завершено и деньги будут зачислены согласно регламенту.

• Что значит pending статус YooKassa спустя долгое время?

  • Обычно это признак, что оплату не завершили или возникли проблемы на стороне плательщика. Предложите повторить или отправьте платёжную ссылку.

• Как безопасно принимать платежи?

  • Следуйте рекомендациям в разделе безопасность платежей, используйте 3‑D Secure, вебхуки и идемпотентность.

Итоги и следующий шаг

Понимание того, как читать статусы платежей YooKassa — pending, waiting_for_capture, succeeded, canceled — помогает сокращать отмены, ускорять отгрузку и улучшать клиентский опыт. Настройте наблюдение за статусами через ЛК и API, автоматизируйте capture и уведомления, заранее продумайте логику возвратов.

Готовы оптимизировать процесс? Войдите в личный кабинет, проверьте раздел «Мои платежи» и, если нужно, донастройте интеграцию по API V3. Если вы только знакомитесь с возможностями, начните с обзора личного кабинета и API V3.