Песочница и тестирование: тестовые ключи, карты и сценарии
Песочница платежей API — это безопасная тестовая среда, где разработчики обкатывают интеграцию, не рискуя деньгами клиентов. Здесь вы проверите основные и крайние сценарии: от успешных платежей и возвратов до 3‑DS аутентификации, отказов и доставки вебхуков. Эта страница — ваш практический гид по тесту: sandbox API ключи, тестовые карты API, тестирование 3DS, webhook тестирование, логи запросов и переход из env test в live.
Table of contents
Что такое песочница платежи API и зачем она нужна
Песочница платежей API — это полноценная имитация боевой среды с теми же методами и объектами, но без проводок в банках и списаний с реальных карт. В песочнице можно:
- протестировать все базовые операции: создание платежа, подтверждение, отмена и возврат;
- выполнить тестирование 3DS (включая frictionless, challenge и отказ);
- проверить webhook тестирование — доставка, подпись, повтор вебхуков;
- воспроизвести пограничные кейсы: таймауты, отклонения эмитентом, антифрод-правила;
- просмотреть логи запросов и сверить payload с документацией.
Начните с краткого гайда по интеграции: см. раздел Быстрый старт интеграции и общую Документацию API. Если вы только выбираете подход, ознакомьтесь с возможностями Прием платежей API и поддерживаемыми Методами оплаты.
Среды env test vs live: различия
Обе среды максимально похожи, чтобы вы переносили код без переписываний. Тем не менее есть важные отличия.
| Аспект |
Test (Sandbox) |
Live |
| Деньги |
Симулированные, без фактических списаний |
Реальные списания и зачисления |
| 3‑DS |
Полный симулятор: успешные, челендж, отказ |
Реальные проверки банка-эмитента |
| Вебхуки |
События приходят из симулятора, возможен ручной повтор |
События производства, повтор при сбоях |
| Данные |
Тестовые, очищаются или архивируются |
Производственные, соответствуют 54‑ФЗ и PCI DSS |
| Ограничения |
Щадящие лимиты, доступна симуляция отказов |
Боевые лимиты и антифрод |
| Карты |
Только тестовые карты API |
Только реальные карты клиентов |
Важно: переключение между env test и live выполняется через ключи и/или настройку окружения, методы и форматы объектов остаются одинаковыми.
Sandbox API ключи: как получить и хранить
Sandbox API ключи выдаются в личном кабинете разработчика. Обычно доступно два типа секретов: публичный (для клиентских SDK) и секретный серверный. Рекомендации по работе с ключами:
- создайте отдельные ключи на каждое окружение и команду (dev, staging, QA);
- не храните секреты в репозитории — используйте переменные окружения и хранилища секретов;
- регулярно ротируйте ключи и удаляйте неиспользуемые;
- ограничьте доступ к ключам по роли и, при необходимости, по IP;
- при утечке сразу отзовите ключ и сгенерируйте новый;
- помните: ключи песочницы недействительны в live и наоборот.
См. базовые требования к безопасности и соответствию стандарту PCI DSS в разделе Безопасность и PCI DSS.
Тестовые карты API и сценарии 3‑ДС
В песочнице доступна подборка тестовых карт для разных сценариев. Точный список номеров и подсказок смотрите в кабинете разработчика — ниже приведены типовые примеры для ориентирования.
| Сценарий |
Номер карты (пример) |
CVC |
Срок |
3‑DS |
Результат |
| Успешный платеж без 3‑DS (frictionless) |
4111 1111 1111 1111 |
123 |
Любая будущая дата |
Нет |
Успех |
| Успешный платеж с 3‑DS challenge |
5555 5555 5555 4444 |
123 |
Любая будущая дата |
Challenge |
Успех после подтверждения |
| Отказ эмитента |
4000 0000 0000 0002 |
123 |
Любая будущая дата |
Может быть |
Отказ банка |
| Недостаточно средств |
4000 0000 0000 9995 |
123 |
Любая будущая дата |
Нет |
Отказ по средствам |
| Ошибка 3‑DS аутентификации |
4012 8888 8888 1881 |
123 |
Любая будущая дата |
Challenge |
Отказ по 3‑DS |
| Таймаут на стороне эмитента |
4211 1111 1111 1110 |
123 |
Любая будущая дата |
Может быть |
Ошибка/повтор |
Пояснения и советы:
- если 3‑DS включен в настройках мерчанта, часть тестовых карт инициирует challenge-окно; следуйте инструкциям симулятора;
- используйте реальные суммы и валюты, чтобы проверить округления и комиссии (в тесте деньги не списываются);
- токенизируйте карту и повторно списывайте для проверки Рекуррентных платежей;
- проверьте отмену до списания и полный/частичный Возврат после списания.
Для мобильных приложений используйте актуальные SDK и тестируйте нативные потоки 3‑DS: см. Mobile SDK.
Webhook тестирование: доставка, подпись и повтор вебхуков
Вебхуки — ключ к асинхронной синхронизации статусов. В песочнице вы можете полноценно настроить webhook тестирование.
- настройте URL в кабинете и убедитесь, что эндпоинт доступен извне;
- используйте локальный туннель при разработке (например, ngrok), чтобы принимать события на localhost;
- проверяйте цифровую подпись событий — секрет подписи храните отдельно от ключей API;
- дизайн доставки — как правило at-least-once, поэтому обеспечьте идемпотентность по event_id;
- включите повтор вебхуков через кабинет для любых событий, которые необходимо перепроиграть;
- логируйте полученные payload и заголовки, чтобы упростить отладку.
Список событий и форматы объектов см. на странице Вебхуки и события. Обязательно протестируйте события об успешной/проваленной оплате, отмене и возвратах, а также отчеты по выплатам, если вы используете Выплаты и вывод средств.
Симуляция отказов и редких сценариев
Для проверки устойчивости интеграции полезна симуляция отказов. В тестовой среде обычно доступны управляющие триггеры. Типовые подходы:
- параметры платежа: особые суммы или комбинации полей вызывают конкретный отказ;
- metadata-флаги: передайте метку сценария, чтобы симулировать таймаут или ошибку сети;
- специальные тестовые карты: набор BIN/карта провоцирует конкретный ответ эмитента.
Ниже — ориентировочная шпаргалка. Конкретные значения триггеров смотрите в Документации API.
| Что проверить |
Пример запуска в песочнице |
Ожидаемый результат |
| Таймаут банка-эмитента |
metadata: scenario=issuer_timeout |
Платеж в статусе pending, затем отказ или повтор |
| Сбой сети при подтверждении |
metadata: scenario=network_error |
Ошибка 5xx, повтор запроса по идемпотентному ключу |
| Отказ антифрода |
metadata: scenario=antifraud_decline |
Отказ с кодом antifraud, событие в логах |
| Ошибка 3‑DS |
metadata: scenario=3ds_fail |
Окно 3‑DS, затем отказ аутентификации |
| Долгая обработка (long running) |
metadata: scenario=delayed_capture |
Смена статуса с задержкой, вебхук по готовности |
Параллельно проверьте интеграцию с антифродом и пост-обработку рисков: см. Antifraud и риск-менеджмент.
Логи запросов и отладка интеграции
Логи запросов — лучший друг разработчика. В песочнице доступны:
- логи запросов к API: метод, путь, статус, latency, тело запроса и ответа с маскировкой чувствительных полей;
- логи вебхуков: история попыток, подписи, payload — удобно для webhook тестирования;
- фильтры по диапазону дат, статусам, idempotency-key и корелляционному идентификатору.
Практические советы:
- для всех write-операций отправляйте X-Idempotency-Key — это спасёт от дублей при повторах;
- сохраняйте корреляционный ID из заголовков ответа API в ваши логи, чтобы быстро находить транзакцию;
- сравнивайте времена: запрос — webhook — обновление в БД, чтобы проверить последовательность.
Если используете готовые интеграции, посмотрите раздел CMS плагины: многие плагины уже включают удобные логи и тестовые режимы.
Чек-лист перед выходом в live
Проверьте все пункты, чтобы переход из env test в live был безболезненным.
- ключи: использованы боевые, sandbox API ключи удалены из конфигов;
- 3‑DS: протестированы frictionless, challenge, fail; корректно обрабатываются редиректы и мобильные SDK;
- вебхуки: URL доступен, подпись валидируется, повтор вебхуков не создаёт дублей;
- идемпотентность: для create/capture/refund используются уникальные ключи;
- возвраты: реализованы полный и частичный Возвраты и отмены;
- рекуррентные: токены хранятся безопасно, выставлены лимиты в Рекуррентных платежах;
- фискализация: проверена интеграция по 54‑ФЗ;
- антифрод: согласованы правила и листинги в Antifraud и риск;
- отчётность: протестированы Отчёты и выгрузки и сверка финансов;
- тарифы: ознакомьтесь с Тарифами и комиссиями;
- SLA: контакты и процессы эскалации — см. SLA и поддержка.
FAQ по тестированию
- Можно ли использовать реальные карты в песочнице? Нельзя — применяйте только тестовые карты API. Для end-to-end с реальным списанием используйте live на небольшой сумме.
- Отличается ли API между test и live? Методы и структуры одинаковые; различаются ключи и бизнес-поведение (реальные списания, антифрод, 3‑DS у банка).
- Как быстро приходят вебхуки? В песочнице — сразу или с управляемой задержкой. Повтор вебхуков возможен вручную из кабинета.
- Храните ли вы тестовые данные? Тестовые данные хранятся ограниченно и могут удаляться/анонимизироваться по политике. Не используйте персональные данные клиентов в песочнице.
- Где посмотреть примеры запросов? В Документации API и на странице Прием платежей API. Для быстрого запуска — Быстрый старт интеграции.
Полезные ссылки
- Прием платежей API — /priem-platezhey-api
- Документация API — /dokumentatsiya-api
- Быстрый старт интеграции — /bystryi-start-integratsii
- Методы оплаты — /metody-oplat
- Вебхуки и события — /vebhuki-i-sobytiya
- Рекуррентные платежи — /rekurrentnye-platezhi
- Возвраты и отмены — /vozvraty-i-otmeny
- Mobile SDK — /mobile-sdk
- CMS плагины — /cms-plugins
- Тарифы и комиссии — /tarify-i-komissii
- Отчёты и выгрузки — /otchety-i-vygruzki
- Выплаты и вывод средств — /vyplaty-i-vyvod-sredstv
- Фискализация 54‑ФЗ — /fiskalizatsiya-54-fz
- Antifraud и риск — /antifraud-i-risk
- SLA и поддержка — /sla-i-podderzhka
Готовы перейти из песочницы в боевой режим? Проверьте чек-лист, смените ключи на live и сделайте контрольный платеж. Если нужна помощь с финальными проверками, напишите в поддержку — мы поможем завершить тестирование и выйти в прод без сюрпризов.