Коротко
Режима два. Песочница — ключ qp_test_…: Kaspi не вызывается вообще, реальные деньги не двигаются, оплату вы симулируете сами, кассир не нужен, счета не идут в месячный лимит и пробный период не запускается. Боевой режим — ключ qp_live_…: настоящий QR Kaspi, настоящие деньги, кассир обязателен. Режим переключается в кабинете.
Сравнение
| Что | Песочница | Боевой режим |
|---|---|---|
| Ключ | 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_… не создать счёт в песочнице — поэтому при смене режима не забудьте поменять и ключ. Это самая частая ошибка: в коде остаётся старый тестовый ключ, и получается ситуация «оплата не приходит покупателю».
Что проверить при переходе в боевой режим
- Подключён ли кассир. В разделе Кассиры Kaspi карточка подключения должна быть активной. Если нет: Как подключить кассира Kaspi.
- Везде ли стоит ключ
qp_live_…— в коде, на сервере, в настройках плагина CMS. Старый тестовый ключ не должен остаться нигде. - Лежит ли ключ только на сервере. Его не должно быть в коде, который выполняется в браузере, внутри мобильного приложения или в публичном репозитории.
- Боевой ли адрес webhook. В продакшене принимается только
httpsи настоящий домен — IP и адреса туннелей вроде ngrok не подходят. Секрет тоже обновите под новый адрес. - Проведите первую реальную оплату сами. Выставьте счёт на небольшую сумму и оплатите его из своего Kaspi. Проверьте, что деньги пришли на ваш счёт в Kaspi, webhook доставлен, а заказ у вас закрылся правильно. Потом при желании сделайте возврат этой суммы.
- Помните, что запускается пробный период. 7 дней, 50 счетов в сутки — и отсчёт идёт с первого боевого счёта, а не с даты регистрации.
- Заранее выберите тариф, чтобы работа не встала в момент окончания пробного периода.
Что не меняется
При смене режима логика вашего обработчика webhook, способ проверки подписи, названия полей и порядок статусов остаются прежними. Единственное, что в вашем коде зависит от режима, — это API-ключ.
Вопросы и ответы
Счета из песочницы расходуют лимит? Нет. И месячный лимит, и суточная защита считаются только по боевым счетам.
Песочница запускает пробный период? Нет. Пробный период начинается с первого боевого счёта. В песочнице можно тестировать сколько угодно.
Нужен ли кассир для песочницы? Нет. Kaspi в ней не участвует, поэтому кассир не требуется.
Приходит ли webhook в песочнице? Да, с теми же событиями и той же подписью, что и в бою. Код проверки подписи лучше всего отладить именно здесь.
Можно ли тестовым ключом создать боевой счёт? Нет, так сделано намеренно. Ключ qp_test_… до Kaspi не доходит — это защищает от случайной настоящей оплаты.