Песочница и тестирование: тестовые ключи, карты и сценарии

Песочница платежей API — это безопасная тестовая среда, где разработчики обкатывают интеграцию, не рискуя деньгами клиентов. Здесь вы проверите основные и крайние сценарии: от успешных платежей и возвратов до 3‑DS аутентификации, отказов и доставки вебхуков. Эта страница — ваш практический гид по тесту: sandbox API ключи, тестовые карты API, тестирование 3DS, webhook тестирование, логи запросов и переход из env test в live.

Что такое песочница платежи API и зачем она нужна

Песочница платежей API — это полноценная имитация боевой среды с теми же методами и объектами, но без проводок в банках и списаний с реальных карт. В песочнице можно:

протестировать все базовые операции: создание платежа, подтверждение, отмена и возврат;
выполнить тестирование 3DS (включая frictionless, challenge и отказ);
проверить webhook тестирование — доставка, подпись, повтор вебхуков;
воспроизвести пограничные кейсы: таймауты, отклонения эмитентом, антифрод-правила;
просмотреть логи запросов и сверить payload с документацией.

Начните с краткого гайда по интеграции: см. раздел Быстрый старт интеграции и общую Документацию API. Если вы только выбираете подход, ознакомьтесь с возможностями Прием платежей API и поддерживаемыми Методами оплаты.

Получить CloudPayments бесплатно

Среды 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 и сделайте контрольный платеж. Если нужна помощь с финальными проверками, напишите в поддержку — мы поможем завершить тестирование и выйти в прод без сюрпризов.

Получить CloudPayments бесплатно