Тестовый режим (Sandbox)

Тестовый режим позволяет проверить интеграцию на той же кассе и с тем же API-ключом, что и в проде — без реальных денег и без влияния на баланс, бухгалтерию и аналитику.

Отдельная тестовая касса не нужна: достаточно одного дополнительного поля в запросе создания платежа.

Как включить

Добавьте "test": true в тело запроса создания платежа:

curl -X POST https://rollypay.io/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rpk_live_ВАШ_КЛЮЧ" \
  -H "X-Nonce: $(uuidgen)" \
  -d '{
    "amount": "1500.00",
    "payment_currency": "RUB",
    "order_id": "order_test_001",
    "test": true
  }'

Либо передайте заголовок X-Test-Mode: true вместо поля в теле запроса — оба варианта равнозначны и взаимозаменяемы.

Что гарантирует изоляция

Область	Поведение в тестовом режиме
Способ оплаты	Всегда принудительно тестовый СБП (заглушка), независимо от переданного payment_method. Реальная обработка платежа не запускается
Лимиты кассы (caps)	Не проверяются и не расходуются
Баланс мерчанта	Не изменяется
Кэшбэк RollyCoin	Не начисляется
Аналитика и обороты	Тестовые платежи полностью исключены из отчётов и метрик
Возвраты (refunds)	Недоступны для тестовых платежей (нет реальных денег для возврата)

В ответе на создание платежа и в объекте платежа присутствуют поля:

{
  "environment": "sandbox",
  "test": true
}

Оплата на тестовой платёжной форме

На pay_url тестового платежа вместо реального QR-кода отображается баннер «Тестовый режим» и кнопки для ручной симуляции результата — реальный сканер СБП здесь не нужен.

POST /public/payments/{token}/simulate

{
  "outcome": "paid",
  "csrf_token": "..."
}

Поле	Значение	Описание
outcome	"paid" | "failed"	Желаемый итог тестового платежа

Эндпоинт доступен только для платежей с environment: sandbox; для боевых платежей возвращает ошибку. Платёж проходит те же переходы статусов, что и в реальном сценарии: created → processing → paid/canceled, поэтому ваш код может быть протестирован по идентичному сценарию поллинга/колбэков.

Колбэки для тестовых платежей

Уведомление на callback_url для тестового платежа помечено:

• полем "test": true в теле запроса;
• заголовком X-Test-Mode: true.

{
  "event_type": "payment.paid",
  "payment_id": "pay_...",
  "order_id": "order_test_001",
  "status": "paid",
  "amount": "1500.00",
  "currency": "RUB",
  "test": true
}

Подпись (X-Signature) вычисляется так же, как для боевых колбэков — можно использовать один и тот же код проверки. Рекомендуем проверять флаг test/заголовок X-Test-Mode, чтобы не выполнять реальную бизнес-логику (списания, отгрузку товара) для тестовых событий, если это нежелательно.

Просмотр тестовых платежей

По умолчанию список платежей и статистика (GET /api/v1/payments, GET /api/v1/payments/stats) показывают только боевые (prod) платежи — тестовые их не засоряют. Чтобы получить их явно:

Параметр	Что вернёт
?environment=sandbox	Только тестовые платежи
?environment=all	Все платежи, боевые и тестовые
без параметра	Только боевые (по умолчанию)

В личном кабинете (как в текущем, так и в новом new.rollypay.io) тестовые платежи доступны на отдельной вкладке «Тестовые» в разделе платежей, с пометкой «Тест» в списке и в деталях платежа. Там же есть кнопка «Создать платёж» с переключателем «Тестовый платёж» — можно создать тестовый платёж без единой строчки кода.

Типичный сценарий проверки интеграции

1. Создайте платёж с "test": true.
2. Откройте pay_url — убедитесь, что виден баннер «Тестовый режим».
3. Нажмите «Симулировать успешную оплату» (или вызовите /simulate с outcome: "paid" напрямую).
4. Проверьте, что на callback_url пришло событие payment.paid с "test": true.
5. Убедитесь, что баланс и аналитика не изменились — тестовый платёж на них не влияет.
6. Повторите с outcome: "failed", чтобы проверить обработку неуспешного платежа на своей стороне.

---

Смотрите также: Платежи — общая структура запроса создания платежа, Колбэки — проверка подписи и повторные попытки.