Sandbox YooKassa: тестирование платежей, webhooks, отказных сценариев и сверки
Что такое Sandbox YooKassa
YooKassa Sandbox (yookassa sandbox) — это изолированная среда, в которой можно безопасно проверять логику приема платежей, 3‑D Secure, webhook тест YooKassa, отказные сценарии и процессы сверки без реального списания средств. Тестовый режим YooKassa имитирует ключевые платежные потоки, позволяя разработчикам и QA-командам создавать устойчивую интеграцию до выхода в продакшн.
В песочнице используется отдельная пара тестовых идентификаторов и ключей, а также собственные URL для обратных уведомлений. Часть функций может быть ограничена (например, некоторые платежные методы или внешние провайдеры), однако основной набор сценариев — тестовые платежи YooKassa по картам, предавторизация, подтверждение, отмена, возвраты и доставка вебхуков — доступен в полном объеме.
Рекомендуемые материалы к началу работы:
Когда пригодится тестовый режим
Тестовый режим YouKassa незаменим, когда вы:
- Разрабатываете кастомную интеграцию через API или c помощью готовых CMS‑модулей
- Встраиваете оплату в мобильное приложение: Mobile SDK
- Проверяете прием карт с 3‑D Secure, предавторизацию (hold) и последующее списание
- Эмулируете отказные сценарии: отмена покупателем, отклонение банком-эмитентом, истекшая 3DS‑сессия
- Настраиваете webhook тест YooKassa и проверяете ретраи вебхуков
- Готовите фискальные чеки под 54‑ФЗ: Фискализация
- Отрабатываете возвраты и разбираете спорные операции: Возвраты и диспуты
- Налаживаете процессы сверки и отчетности: Отчеты и реконсиляция
Быстрый старт: как включить песочницу и получить ключи
Зарегистрируйтесь и включите песочницу в Личном кабинете.
Создайте тестовое «магазин/подключение» и получите реквизиты:
- test_shop_id (идентификатор магазина)
- test_secret_key (секретный ключ) для запросов к API
Укажите URL‑адреса для тестовых вебхуков (например, https://staging.yoursite.ru/yookassa/webhook). Раздел «Уведомления/Webhooks» доступен в кабинете.
Проверьте базовые операции через API:
- Создание платежа (create payment)
- Подтверждение/капчур (capture) для предавторизации
- Отмена (cancel)
- Возврат (refund)
Совет: для каждого запроса к API передавайте заголовок с идемпотентным ключом (Idempotence-Key), чтобы избежать дублирования операций при повторах и сетевых сбоях. Подробнее — в разделе «Идемпотентные ключи» ниже.
[image: Экран настроек вебхуков в личном кабинете YooKassa]
Тестовые платежи: ключевые сценарии
Тестовые платежи YooKassa позволяют проверить как «счастливые» пути, так и пограничные кейсы. Ниже — дорожная карта того, что важно отразить в автотестах и ручном прогоне.
[image: Диаграмма последовательности платежа по карте с редиректом и вебхуком]
Таблица сценариев
| Сценарий |
Что проверить |
Ожидаемый webhook/статус |
Итог |
| Успешная оплата с автосписанием (capture=true) |
Создание платежа, редирект/подтверждение, возврат на success_url |
payment.succeeded |
Заказ в статусе «Оплачен», чек сформирован (в песочнице — имитация) |
| Предавторизация (capture=false) |
Создание платежа, получение payment.waiting_for_capture, отдельный capture |
payment.waiting_for_capture → payment.succeeded |
Средства захолдированы, затем списаны по capture |
| Отмена до списания |
Создание оплаты с hold, затем cancel |
payment.canceled |
Холды сняты, заказ остался неоплаченным |
| Пользователь отменил оплату на странице банка |
Возврат на fail/cancel URL |
payment.canceled |
Правильная обработка отказа на фронте и в бэке |
| Истекшая/ошибочная 3DS аутентификация |
Тайм‑аут или введение неверного кода |
payment.canceled или отклонение |
Корректные сообщения пользователю, отсутствие ошибок в логах |
| Повтор клика «Оплатить»/сетевой тайм‑аут |
Повторный запрос с тем же Idempotence-Key |
Тот же payment.id |
Нет дублей заказов и списаний |
| Недоступность вашего вебхука (500/тайм‑аут) |
Имитация 5xx ответа |
Ретраи вебхуков |
Устойчивость к повторной доставке событий |
О тестовых реквизитах. В yookassa sandbox доступны специальные тестовые карты и сценарные параметры. Их актуальный список и правила использования смотрите в вашем ЛК и документации API. Для проверки разных исходов применяйте соответствующие тестовые значения, чтобы спровоцировать успех, отказ или требование 3DS.
3‑D Secure: 3ds тестирование шаг за шагом
3‑D Secure — ключевой этап, влияющий на конверсию и безопасность. В тестовом режиме YouKassa отработайте оба варианта:
- Frictionless (без запроса кода): быстрый проход без дополнительных действий
- Challenge Flow (с вводом кода на стороне банка/ACS)
Рекомендации по сценарию:
- Создайте платеж с confirmation.type=redirect и сохраните confirmation_url.
- Перенаправьте пользователя на confirmation_url, дождитесь завершения аутентификации.
- Обрабатывайте возвращение на success_url/fail_url и показывайте корректное сообщение.
- Дождитесь вебхука payment.succeeded или payment.canceled и финализируйте заказ на бэке.
Проверьте:
- Тайм‑ауты и повторную попытку 3DS
- Корректное закрытие модального окна/редиректа в SPA
- Учет case, когда пользователь закрыл вкладку после подтверждения (итог определяется по вебхуку)
Webhooks в песочнице: настройка, ретраи и проверка подлинности
Вебхуки — источник истины о финальном статусе операции. В yookassa sandbox доступны события, включая: payment.waiting_for_capture, payment.succeeded, payment.canceled, refund.succeeded и др.
Настройка:
- Укажите тестовый URL в кабинете и включите нужные события
- Возвращайте HTTP 200 OK быстро (<1–2 сек), обработку тяжелой логики делайте асинхронно
Ретраи вебхуков:
- Если ваш сервер недоступен, отвечает не‑2xx или превышен тайм‑аут, YooKassa повторит доставку
- Повторы идут с увеличением интервалов (экспоненциальная задержка) до успешного 2xx‑ответа или истечения времени повторных попыток
- Ваша обработка должна быть идемпотентной: несколько одинаковых уведомлений не должны менять результат более одного раза
Проверка подлинности события:
- Никогда не доверяйте статусу из тела вебхука «как есть»
- Извлеките идентификатор объекта (payment_id/refund_id) и дополнительно запросите его состояние через API по вашему тестовому ключу
- Сверьте сумму, валюту, статус и свои метаданные (metadata), затем переходите к изменению статуса заказа
[image: Последовательность ретраев вебхуков и подтверждение статуса через API]
Идемпотентные ключи и безопасные повторы
Идемпотентные ключи (идемпотентные заголовки) — ваш главный инструмент против двойных списаний и дублирования операций.
Как использовать:
- Генерируйте уникальный Idempotence-Key на каждую попытку создания платежа (например, UUID, привязанный к номеру заказа и попытке)
- При сетевой ошибке или тайм‑ауте повторяйте запрос с тем же ключом — API вернет исходный результат без повторного списания
- Применяйте ту же практику для capture/cancel/refund, где повтор возможен из‑за сбоев
Серверные практики:
- Храните соответствие Idempotence-Key ↔ payment.id в БД
- Блокируйте конкурентные операции по одному заказу (mutex/lock)
- Обрабатывайте вебхуки идемпотентно (по payment.id/refund.id), фиксируйте уже примененные события в журнале
Отказные сценарии, возвраты и диспуты
В тестовой среде стоит проверить максимальный набор негативных исходов:
- Отклонение эмитентом/платежным шлюзом (симулируется тестовыми реквизитами)
- Отмена пользователем на стороне банка
- Истечение времени подтверждения
- Неуспешный capture и отмена холда
Возвраты:
- Инициируйте полные и частичные возвраты по API
- Ожидайте webhook refund.succeeded и сверяйте сумму и currency
- Проверьте UX: в ЛК пользователя/в разделе заказов должен отобразиться корректный статус
Диспуты/чарджбеки:
- В песочнице их поведение зачастую эмулируется ограниченно. Разработайте процессы обработки «уведомлений о споре» в бое, а в тесте проверьте маршрут ошибок и уведомления команды
Подробнее: Возвраты и диспуты.
Фискализация 54‑ФЗ в тестовой среде
Даже в песочнице важно формировать корректный состав чека:
- Предмет расчета, ставка НДС, признак способа расчета, система налогообложения
- Сумма по позициям = amount платежа
- Маркировка (если применимо) и признак способа оплаты
Обычно отправка данных в ОФД в песочнице не выполняется, но вы можете проверить, что формируете корректный payload, и валидировать его на своей стороне. Гайд: Фискализация 54‑ФЗ.
Сверка и отчеты: как подтвердить корректность интеграции
Правильная реконсиляция — залог отсутствия «висящих» платежей и расхождений.
Что проверить в песочнице:
- Сверка заказов с платежами: ваш order_id ↔ payment.id (metadata)
- Сравнение сумм, валюты, статусов (succeeded/canceled/waiting_for_capture)
- Обработка поздних вебхуков и повторных доставок
- Реестр возвратов и привязка refund.id к исходному платежу
Мини‑карта полей для сверки
| Внутренняя система |
YooKassa |
Описание |
| order_id |
payment.metadata.order_id |
Связка платежа с заказом |
| сумма заказа |
payment.amount.value/currency |
Контроль суммы и валюты |
| статус заказа |
payment.status |
Финальный статус для учета |
| id возврата |
refund.id |
Связь возврата и платежа |
Подробные процессы — в материале: Отчеты и реконсиляция.
Лучшие практики и чек‑лист перед релизом
- Применяйте идемпотентные ключи во всех критичных запросах
- Обрабатывайте вебхуки асинхронно, отвечайте быстро с 200 OK
- Подтверждайте статус через API по идентификатору из вебхука
- Логируйте каждый шаг платежного потока: request id, payment.id, idempotence key, webhook id
- Реализуйте повторные попытки с backoff на своей стороне для запросов к API
- Тестируйте и happy path, и негативные сценарии, включая отказ 3DS и отмену
- Проверяйте предавторизацию и последующий capture/partial capture
- Имейте процесс возвратов и нотификаций клиенту
- Готовьте корректный состав чека и налоговые параметры: Фискализация
- Закройте вопросы безопасности: хранение ключей, HTTPS, контроль доступа: Безопасность и соблюдение
Чек‑лист:
- Все ключевые методы протестированы (create, capture, cancel, refund)
- Покрыты ретраи вебхуков и идемпотентность
- Сверка и отчеты сходятся
- Обработаны граничные статусы и тайм‑ауты
- UX‑потоки на фронте соответствуют статусам
Частые ошибки и отладка
- Отсутствие Idempotence-Key → дубли платежей при ретраях
- Синхронная тяжелая обработка вебхука → тайм‑ауты и лавина ретраев
- Доверие полю status из вебхука без проверки через API
- Необработанное состояние payment.waiting_for_capture (забытый capture или cancel)
- Несоответствие суммы заказа и payment.amount → отказ при capture/refund
- Использование одного и того же URL для webhook в тесте и бое без окружений
Полезно: проверьте тарифы и эквайринг перед выходом в прод: Тарифы и эквайринг, а также поддержку нужных методов оплаты: Платежные методы.
Итоги и следующий шаг
Песочница YooKassa — безопасный полигон для отладки логики оплаты, 3DS, webhook тестов, ретраев вебхуков и сверки. Отработайте набор критичных сценариев, внедрите идемпотентные ключи и надежную обработку уведомлений — и только после этого переходите в продакшн.
Готовы к запуску? Перейдите к руководству по подключению и финальной проверке:
Запускайтесь уверенно — и принимайте платежи без сбоев уже с первого дня.