Коротко
Когда оплата не проходит, не тратьте время на раскопки в коде. Ответьте на три вопроса, и через две минуты станет ясно, где сбой: работает ли в песочнице, выставляется ли счёт вручную из кабинета, работает ли на другом кассире. Эти три вопроса делят проблему на три части — ваш код, привязка Kaspi, сам сервис — и решение у каждой своё.
Дополнительно: эндпоинт GET /api/v1/status отвечает и без ключа и за секунду показывает, жив ли сервис.
Вопрос 1. Работает ли в песочнице
Переключитесь на ключ qp_test_ и повторите тот же самый запрос.
curl -i -X POST https://api.qut.kz/api/v1/invoices \
-H "X-API-Key: qp_test_ВАШ_КЛЮЧ" \
-H "Content-Type: application/json" \
-d '{"amount":1000,"description":"Диагностика"}'| Результат | Вывод |
|---|---|
| В песочнице работает, в бою нет | Сторона Kaspi: привязка кассира, организация или тариф |
| В песочнице тоже не работает | Ваша сторона: запрос, ключ, поля |
Это самый важный вопрос. Песочница вообще не обращается к Kaspi — если ошибка есть и там, Kaspi ни при чём, дело в запросе. Прочитайте поле error: для 401 и 403 есть отдельные страницы.
Вопрос 2. Выставляется ли счёт вручную из кабинета
В боевом режиме зайдите в кабинет и создайте один счёт вручную в разделе «Счета».
| Результат | Вывод |
|---|---|
| Вручную счёт создаётся | Привязка Kaspi жива. Дело в вашей интеграции |
| Вручную счёт тоже не создаётся | Дело в привязке Kaspi или в тарифе |
Этот вопрос убирает код из уравнения. И кабинет, и ваш код идут одним и тем же путём: Qut Pay → Kaspi. Если из кабинета получается, значит путь открыт.
Если вручную тоже не выходит, откройте раздел Kaspi в кабинете: активна ли карточка подключения, есть ли строка «Причина». Самое частое — кто-то вошёл в приложение Kaspi Pay с номера кассира и оборвал сессию.
Вопрос 3. Работает ли на другом кассире
Если подключено несколько кассиров, попробуйте выставить счёт через второго.
| Результат | Вывод |
|---|---|
| На втором кассире работает | Проблема именно в первом кассире |
| Не работает ни на одном | Проблема на уровне организации: тариф, аккаунт, сторона Kaspi |
Если падает только один кассир, проверьте: активна ли SIM, есть ли этот сотрудник в Kaspi Pay, стоит ли у него роль «Кассир», не вошёл ли кто-то с этого номера в приложение.
О подключении нескольких кассиров: Можно ли подключить несколько кассиров.
Состояние самого сервиса
Секундная проверка, которую стоит сделать до трёх вопросов:
curl -s https://api.qut.kz/api/v1/statusЭндпоинт работает без API-ключа. Если он отвечает, сервис жив — вопрос «а не лежите ли вы» закрыт. Если молчит или думает слишком долго, дело на нашей стороне и раскапывать свой код незачем.
Этот эндпоинт стоит завести в мониторинг: тогда о сбое вы узнаете раньше, чем о нём сообщат покупатели.
Таблица чтения результатов
| Песочница | Вручную из кабинета | Вывод | Первое действие |
|---|---|---|---|
| Работает | Создаётся | Дело в интеграции: боевой ключ, режим, поля | Сверьте ключ и режим |
| Работает | Не создаётся | Привязка Kaspi или тариф | Кабинет → Kaspi, затем Тариф |
| Не работает | Создаётся | Дело в запросе: заголовок, поля, ключ | Прочитайте код error |
| Не работает | Не создаётся | Уровень аккаунта или сам сервис | Проверьте status и напишите в поддержку |
Три случая, которые путают чаще всего
Забыли выключить тестовый режим. В песочнице всё прекрасно работает, счета создаются, просто деньги никуда не идут. Это самая частая «ложная поломка». Если ключ начинается с qp_test_, вы в песочнице.
Счёт создался, но вебхук не пришёл. Это две разные задачи. Раз счета создаются, привязка Kaspi жива, и сбой на стороне вебхука: адрес, подпись, код ответа.
Кажется, что деньги не дошли. Деньги никогда не бывают у нас, они идут прямо на счёт Kaspi. Проверять нужно в Kaspi Pay: Счёт оплачен, а денег нет.
Что собрать для поддержки
Если диагностика не дала ответа, напишите нам. С этими данными ответ будет конкретным сразу:
idсчёта или значениеexternalOrderId- Точное время с часами и минутами и с указанием часового пояса
- Режим, в котором вы работали: песочница или боевой
- Полный текст ответа: HTTP-код и поле
error - Первые десять символов ключа — никогда не присылайте ключ целиком
- Ответы на три вопроса: песочница, ручной счёт, другой кассир
Каналы связи: WhatsApp +7 778 881 3333, Telegram @qutpaybot, почта kazprose@gmail.com или раздел «Поддержка» в кабинете.
Вопросы и ответы
Как узнать, есть ли сбой на стороне Kaspi? Отдельной страницы с таким статусом нет. Но если в песочнице всё работает, а в бою одновременно падают несколько кассиров, причина вероятнее всего на стороне Kaspi.
Можно ли делать диагностику в боевом режиме? Да, но ставьте маленькую сумму на пробных счетах и не забывайте отменять их потом.
Считаются ли счета песочницы в лимит? Нет. Счета песочницы не входят в месячный лимит и не запускают пробный период.
Что показывает эндпоинт status? Рабочее состояние сервиса. О привязке вашего конкретного кассира он ничего не говорит — это видно в разделе Kaspi в кабинете.
А если на все три вопроса ответ «работает», но покупатель платить не может? Тогда дело может быть на его стороне: истекло окно QR, старая версия приложения, интернет. Попробуйте создать новый счёт.