Коротко
Счёт создаётся двумя способами. Вручную из кабинета: в разделе Счета указываете сумму и нажимаете Создать счёт — сразу появляются QR и ссылка на оплату. Через API: отправляете POST https://api.qut.kz/api/v1/invoices. Первый раз делайте это в режиме песочницы: настоящие деньги не двигаются, а оплату можно симулировать самому.
Сначала песочница
Вверху кабинета стоит отметка режима: SANDBOX или LIVE. Первый счёт лучше создать в режиме SANDBOX:
- Kaspi не вызывается, подключать кассира не нужно
- Настоящие деньги не двигаются, никому ничего не уходит
- Счёт не считается в лимиты и не запускает пробный период
- Оплату можно симулировать самостоятельно
Как только вы создадите первый счёт в боевом режиме, начнётся отсчёт 7 дней пробного периода — поэтому переключайтесь, когда будете готовы.
Способ 1: вручную из кабинета
- Откройте раздел Счета
- Выберите тип счёта: QR / ссылка или Счёт на телефон (приложение Kaspi)
- Впишите сумму в тенге
- При желании заполните описание («Описание (60 символов)») и номер заказа («№ заказа (необязательно)»)
- Для счёта на телефон укажите номер клиента в формате
7XXXXXXXXXX - Нажмите Создать счёт
Готово. В списке появится новая строка, а по ссылке Страница оплаты можно открыть то, что увидит покупатель. Ссылку отправляют в WhatsApp, Telegram, директ — куда угодно.
В режиме песочницы рядом со счётом есть кнопка [Sandbox] оплачен — нажмёте, и счёт будет помечен как оплаченный, а webhook уйдут так же, как в бою.
Этот способ работает без кода: Нет программиста — как начать.
Способ 2: через API
Сначала в разделе Интеграции в блоке API-ключи создайте ключ. Ключ показывается один раз — скопируйте его сразу. В режиме песочницы ключ начинается с qp_test_….
curl -X POST https://api.qut.kz/api/v1/invoices \
-H "X-API-Key: qp_test_ВАШ_КЛЮЧ" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1001" \
-d '{
"amount": 2500,
"kind": "qr",
"description": "Заказ №1001",
"externalOrderId": "1001",
"customer": { "name": "Асан", "phone": "77010000000" }
}'В ответе придёт 201 и в нём:
| Поле | Зачем |
|---|---|
id | Идентификатор счёта, нужен для запроса статуса |
status | Начальный статус |
payUrl | Страница оплаты, её отправляют покупателю |
qrUrl, qrImageUrl, deepLink | QR и ссылка, открывающая приложение Kaspi |
expiresAt | До какого момента счёт действителен |
Покупателю достаточно дать payUrl — на этой странице есть и QR, и кнопка перехода в Kaspi.
Заголовок Idempotency-Key лучше делать уникальным для каждого счёта (подойдёт номер заказа). Если запрос с тем же ключом повторится, новый счёт не создастся — вернётся прежний.
Симуляция оплаты в песочнице: POST /api/v1/invoices/{id}/simulate с телом { "status": "paid" }.
Полная документация: https://api.qut.kz/docs
Где посмотреть результат
- Кабинет → Счета — список, фильтры, поиск, статус каждого счёта
- Кабинет → Обзор — последние счета и выручка за сегодня
GET /api/v1/invoices/{id}— сам счёт, его события и возвраты- Webhook — уведомление приходит на ваш адрес в момент смены статуса
- Telegram-бот — команды
/lastи/today
Что где лежит в кабинете: Что где находится в кабинете.
Если первый счёт не создаётся
| Признак | Причина |
|---|---|
| API отвечает 401 | Ключа нет, он указан неверно или не задан заголовок X-API-Key |
| API отвечает 403 | У ключа не хватает прав либо тариф неактивен |
| В боевом режиме счёт не создаётся | Кассир Kaspi не подключён или привязка оборвалась |
| Пишет, что ключ недействителен | Ключ не соответствует режиму: ключом песочницы работаете в боевом |
| Сумма не принимается | В QR-счёте максимум 2 знака после запятой, в счёте на телефон — целые тенге |
Вопросы и ответы
Нужен ли кассир, чтобы создать счёт? В песочнице — нет. В боевом режиме — да, кассир Kaspi должен быть подключён.
Сколько живёт QR? Окно сканирования у Kaspi около трёх минут, точное время смотрите в поле expiresAt ответа. Если время вышло, создайте новый счёт.
А если у покупателя нет приложения Kaspi? Счёт на телефон до него не дойдёт — дайте QR или ссылку payUrl.
Счета из песочницы переедут в боевой режим? Нет. Режимы раздельные, тестовые счета остаются в песочнице.
Можно создать несколько счетов одним запросом? Да, POST /api/v1/invoices/bulk принимает от 1 до 100 счетов за раз. В кабинете это кнопка Массово (CSV).