# Чем песочница отличается от боевого режима

> В песочнице Kaspi не вызывается вообще, реальных денег нет и кассир не нужен — оплату вы симулируете сами. Полное сравнение двух режимов и что проверить при переходе в боевой.

## Коротко

Режима два. **Песочница** — ключ `qp_test_…`: Kaspi не вызывается вообще, реальные деньги не двигаются, оплату вы симулируете сами, кассир не нужен, счета не идут в месячный лимит и пробный период не запускается. **Боевой режим** — ключ `qp_live_…`: настоящий QR Kaspi, настоящие деньги, кассир обязателен. Режим переключается в [кабинете](https://qut.kz/app).

## Сравнение

| Что | Песочница | Боевой режим |
|---|---|---|
| Ключ | `qp_test_…` | `qp_live_…` |
| Kaspi вызывается | Нет | Да |
| Реальные деньги | Не двигаются | Идут напрямую на ваш счёт в Kaspi |
| Кассир Kaspi | Не нужен | Обязателен |
| Кто «оплачивает» | Вы сами: `POST /api/v1/invoices/{id}/simulate` | Покупатель приложением Kaspi |
| QR | Не настоящий QR Kaspi | Настоящий, с ограниченным окном сканирования |
| Webhook | Приходит, как в бою | Приходит |
| Проверка подписи | Та же HMAC-SHA256 | Та же |
| Месячный лимит | Не расходуется | Расходуется |
| Пробный период | Не запускается | **Первый боевой счёт запускает пробный период** |
| Возвраты | Симуляция | Настоящие, через Kaspi |

Главное: поведение API в песочнице совпадает с боевым. Те же поля, те же статусы, те же события webhook, та же схема подписи. Поэтому интеграцию можно написать и отладить целиком.

## Зачем нужна песочница

- **Чтобы начать работу, пока кассир не подключён.** Даже если подбор номера займёт пару дней, интеграция уже будет готова.
- **Чтобы проверить весь жизненный цикл счёта:** `new` → `pending` → `paid`, а также `cancelled`, `expired`, `refunded`.
- **Чтобы убедиться, что webhook обрабатывается правильно:** подпись, `timestamp`, повторная доставка, идемпотентность.
- **Для автотестов.** В CI можно прогонять полный цикл через `simulate`, ничьи деньги при этом не двигаются.
- **Чтобы отработать пограничные случаи:** неуспешная оплата, истечение срока, частичный возврат.

## Как переключить режим

Режим переключается в кабинете, и ключ выдаётся под него. Ключом `qp_test_…` боевой счёт не создать, а ключом `qp_live_…` не создать счёт в песочнице — поэтому при смене режима **не забудьте поменять и ключ**. Это самая частая ошибка: в коде остаётся старый тестовый ключ, и получается ситуация «оплата не приходит покупателю».

## Что проверить при переходе в боевой режим

1. **Подключён ли кассир.** В разделе [Кассиры Kaspi](https://qut.kz/app/kaspi/) карточка подключения должна быть активной. Если нет: [Как подключить кассира Kaspi](/kb/ru/connect-cashier).
2. **Везде ли стоит ключ `qp_live_…`** — в коде, на сервере, в настройках плагина CMS. Старый тестовый ключ не должен остаться нигде.
3. **Лежит ли ключ только на сервере.** Его не должно быть в коде, который выполняется в браузере, внутри мобильного приложения или в публичном репозитории.
4. **Боевой ли адрес webhook.** В продакшене принимается только `https` и настоящий домен — IP и адреса туннелей вроде ngrok не подходят. Секрет тоже обновите под новый адрес.
5. **Проведите первую реальную оплату сами.** Выставьте счёт на небольшую сумму и оплатите его из своего Kaspi. Проверьте, что деньги пришли на ваш счёт в Kaspi, webhook доставлен, а заказ у вас закрылся правильно. Потом при желании сделайте возврат этой суммы.
6. **Помните, что запускается пробный период.** 7 дней, 50 счетов в сутки — и отсчёт идёт **с первого боевого счёта**, а не с даты регистрации.
7. **Заранее выберите тариф**, чтобы работа не встала в момент окончания пробного периода.

## Что не меняется

При смене режима логика вашего обработчика webhook, способ проверки подписи, названия полей и порядок статусов остаются прежними. Единственное, что в вашем коде зависит от режима, — это API-ключ.

## Вопросы и ответы

**Счета из песочницы расходуют лимит?** Нет. И месячный лимит, и суточная защита считаются только по боевым счетам.

**Песочница запускает пробный период?** Нет. Пробный период начинается с первого боевого счёта. В песочнице можно тестировать сколько угодно.

**Нужен ли кассир для песочницы?** Нет. Kaspi в ней не участвует, поэтому кассир не требуется.

**Приходит ли webhook в песочнице?** Да, с теми же событиями и той же подписью, что и в бою. Код проверки подписи лучше всего отладить именно здесь.

**Можно ли тестовым ключом создать боевой счёт?** Нет, так сделано намеренно. Ключ `qp_test_…` до Kaspi не доходит — это защищает от случайной настоящей оплаты.