Коротко
Почти все проблемы после перехода в боевой режим сводятся к пяти причинам: ключ остался тестовым, кассир не подключён или привязка оборвалась, тариф неактивен или упёрлись в лимит, адрес вебхука недоступен снаружи, режим на самом деле не переключился. Пройдите пять шагов по порядку — обычно на все пять уходит меньше пяти минут.
Шаг 1. Ключ боевой?
Самая частая причина. Ключ qp_test_ не создаст реальный счёт.
- Где смотреть: кабинет → Интеграции → API-ключи. В списке виден префикс каждого ключа
- Как должно быть: ключ, которым пользуется ваш сервер, начинается с
qp_live_ - Что делать: если боевого ключа нет — создайте. Ключ показывается целиком только один раз, скопируйте сразу. Затем обновите переменную окружения на сервере и перезапустите сервис
Как проверить: посмотрите, какой ключ реально подставляется, — в логе или в env. Только не пишите ключ в лог целиком: достаточно префикса и последних четырёх символов.
Даже если вы ключ заменили, сервис мог не перезапуститься и продолжает работать со старым. Встречается очень часто.
Признак: API отвечает 401 — API отвечает 401.
Шаг 2. Кассир активен?
В песочнице кассир был не нужен, поэтому его легко не подключить вовсе.
- Где смотреть: раздел Кассиры Kaspi
- Как должно быть: хотя бы одна карточка активна, строки «Причина» рядом нет
- Что делать:
- Карточки нет совсем — подключите кассира: Как подключить кассира Kaspi
- Карточка неактивна — введите номер и переподключите кодом из SMS, это минута
- Если ваш ключ привязан к конкретному кассиру, проверьте активность именно его: привязанный ключ на другого кассира не переключится
Самая частая причина обрыва — кто-то вошёл в приложение Kaspi Pay с номера кассира. Kaspi разрешает одному номеру только одно активное устройство.
Шаг 3. Тариф и лимит
- Где смотреть: кабинет → Тариф
- Как должно быть: тариф активен, месячный лимит не исчерпан
- Что делать:
- Тариф неактивен — оплатите или напишите в поддержку
- Лимит исчерпан — перейдите на тариф выше
Не путайте две разные ошибки:
| Ошибка | Что значит | Что делать |
|---|---|---|
tariff_limit_reached | Закончился месячный лимит счетов | Повысить тариф или дождаться следующего месяца |
tariff_daily_burst | Сработала суточная защита | Проверить код: где-то может быть цикл |
tariff_inactive или 403 | Тариф неактивен | Оплатить в разделе Тариф |
Суточное число — не бизнес-лимит, а страховка от зациклившейся интеграции. Подробнее: Достигнут лимит.
Шаг 4. Адрес вебхука открывается снаружи?
Если счета создаются, но уведомление об оплате до вашей системы не доходит — дело здесь.
- Где смотреть: кабинет → Интеграции → журнал вебхуков. Там записан ответ по каждой доставке
- Как должно быть: адрес на
https://и реальном домене, открывается снаружи без авторизации, отвечает 2xx - Что делать: откройте адрес с постороннего устройства, например с мобильного интернета
Частые причины:
- Адрес локальный или через туннель: в продакшене IP-адрес и временный адрес туннеля не принимаются
- Адрес закрыт авторизацией: мы получаем 401/403 и не проходим
- Адрес редиректит в другое место: 307/308 отслеживается только на сам этот адрес (http→https, слеш), редирект на другой домен не отслеживается
- Ваша сторона отвечает не 2xx: тогда доставка повторяется 11 раз, с задержкой от 10 секунд до часа
Если не сходится подпись — проверьте, что считаете её по неизменённому телу запроса: Подпись вебхука не сходится.
Шаг 5. Режим действительно боевой?
Последняя и самая простая проверка. Иногда переключатель не сработал, или его переключили не в той организации.
- Где смотреть: кабинет → Настройки → переключатель режима
- Как должно быть: положение Боевой
- Дополнительно: посмотрите сверху, в какой организации вы находитесь. Если организаций несколько, режим мог быть переключён в другой
Признак: счета создаются, ошибок нет, но покупатель при сканировании QR не видит настоящую страницу оплаты, а счёт в кабинете помечен как тестовый.
Всё проверено, но по-прежнему не работает
Если пять шагов чистые, проблема может быть на стороне Kaspi:
- Проверьте состояние сервиса
- Посмотрите, нормально ли в этот момент работает само приложение Kaspi
- Диагностика за две минуты: Проблема у вас или у Kaspi
Если и это не помогло, напишите в поддержку. Приложите: идентификатор счёта, примерное время, текст ошибки и префикс ключа (не сам ключ).
Вопросы и ответы
В песочнице всё работало, почему сломалось в боевом? В песочнице Kaspi не участвует и кассир не нужен. В боевом добавляются три вещи: кассир, тариф и реальный ответ Kaspi. Поломка — в одной из них.
Ключ заменил, а 401 всё равно приходит. Сервис перезапущен? Старый ключ мог остаться в памяти. Ещё проверьте, что заголовок называется ровно X-API-Key.
Счёт создаётся, но не переходит в paid. Опрос идёт каждые 3 секунды, свежий счёт проверяется на каждом круге. Прошло больше минуты — проверьте привязку кассира и то, что покупатель действительно оплатил.
Что будет со старыми тестовыми счетами после перехода? Останутся в списке, но реальными не станут и в месячный лимит не войдут.
Можно вернуться в песочницу и потестировать? Да. Переключите режим обратно и работайте с ключом qp_test_. Но уже начавшийся пробный период не остановится.