Счёт Kaspi по номеру телефона
Счёт Kaspi по номеру телефона в Qut Pay — это счёт типа «на телефон»: вы указываете сумму и номер клиента, счёт приходит уведомлением прямо в его приложение Kaspi, клиент открывает его и подтверждает оплату. Выставить такой счёт можно в кабинете, командой Telegram-бота, списком из CSV или одним запросом к API. Об оплате вы узнаёте автоматически: вебхуком invoice.paid с подписью HMAC-SHA256, запросом статуса или сообщением в Telegram. Деньги поступают напрямую на ваш счёт Kaspi Pay.
Qut Pay работает через роль «Кассир» в вашем собственном Kaspi Pay: вы добавляете кассира с отдельным номером и подключаете его в кабинете — как подключить за 15 минут. Нужен бизнес-аккаунт Kaspi Pay (ИП или ТОО).
Что видит покупатель
- В приложении Kaspi появляется уведомление о счёте. Сканировать QR и переходить по ссылке не нужно.
- В счёте видны сумма, ваше описание (до 60 символов), название магазина — как оно записано в Kaspi Pay — и номер кассира. Номер кассира показывает сам Kaspi, скрыть его нельзя, поэтому кассиру лучше дать отдельный номер, а не личный.
- Клиент открывает счёт и подтверждает оплату. Пока он не подтвердил, деньги никуда не уходят: счёт — это запрос оплаты, со счёта клиента ничего не снимается само.
- После оплаты у клиента остаётся чек Kaspi; дополнительно можно отправить ему страницу чека Qut Pay (
receiptUrl). - Ваш номер заказа (
externalOrderId) иmetadataклиент не видит.
Подробнее: что видит покупатель.
Как выставить счёт Kaspi клиенту
В кабинете
Раздел Счета → тип «Счёт на телефон (приложение Kaspi)» → сумма, номер клиента, описание и номер заказа → Создать. Если сначала ввести номер, тип переключится на счёт на телефон сам. Счёт сразу появляется в списке со статусом.
Командой Telegram-бота
Привяжите чат к организации в @QutPayBot (код — в кабинете: Настройки → Telegram-бот) и напишите:
/invoice 5000 77001234567 Консультация
Счёт уйдёт в приложение Kaspi клиента. Номер бот распознаёт в любой записи: 8 700 123 45 67, +77001234567. Вместо /invoice подойдут /счёт и /шот. Все команды бота.
Списком: CSV в кабинете или bulk в API
В разделе Счета есть кнопка «Массово (CSV)»: вставьте строки вида сумма;телефон;описание;№ заказа (разделитель — ; или табуляция), до 200 строк за раз. Строка без телефона станет QR-счётом.
5000;77011234567;Абонемент, ноябрь;M-101
5000;87017654321;Абонемент, ноябрь;M-102
Через API то же делает POST /api/v1/invoices/bulk: до 100 счетов за запрос, каждый проверяется отдельно, ответ 207 — результат по каждой строке. Одна ошибка в номере не останавливает остальные. Массовое создание счетов.
Через API
Счёт на оплату Kaspi через API — один запрос с kind: "phone":
curl -X POST https://api.qut.kz/api/v1/invoices \
-H 'X-API-Key: qp_live_…' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: order-1001' \
-d '{
"amount": 2500,
"kind": "phone",
"description": "Заказ №1001",
"externalOrderId": "1001",
"customer": { "phone": "77011234567" }
}'
В ответе — HTTP 201: id (inv_…), status: "pending", payUrl и expiresAt. payUrl есть и у счёта на телефон: если клиент не заметил уведомление, ссылку можно отправить ему отдельно. Idempotency-Key защищает от дублей: повтор с тем же ключом вернёт тот же счёт, а не создаст второй.
Правила для счёта на телефон:
- сумма — только целые тенге, на тиыны придёт
amount_must_be_whole_tenge; - описание — до 60 символов;
- номер —
77011234567; записи+7 701 123 45 67и87011234567API приводит к этому виду сам; - если номер не клиент Kaspi, придёт
422 kaspi_customer_not_found— не повторяйте на тот же номер, дайте клиенту QR или ссылку.
Все поля и ошибки: создание счёта, интеграция с сайтом, OpenAPI — api.qut.kz/docs. Готовые SDK: Node.js, PHP, Python. Для бота в Salebot — отдельная инструкция, для учётной системы — Kaspi и 1С.
Как приходит подтверждение оплаты
Автоматическое подтверждение оплаты Kaspi работает тремя способами, их можно совмещать.
Вебхук об оплате Kaspi
Адрес указывается в кабинете: Интеграции → webhook. Когда клиент оплатил, Qut Pay отправляет на этот адрес POST с событием invoice.paid — на практике в пределах 5 секунд:
{
"event": "invoice.paid",
"invoice": {
"id": "inv_…",
"externalOrderId": "1001",
"status": "paid",
"amount": 2500,
"paidAt": "…"
},
"sentAt": "…"
}
Каждый запрос подписан. В заголовках приходят X-Webhook-Timestamp и X-Webhook-Signature:
X-Webhook-Signature = "sha256=" + hex( HMAC-SHA256( secret, timestamp + "." + rawBody ) )
Проверяйте подпись по сырому телу запроса, до разбора JSON, и отклоняйте запросы старше 5 минут. Сначала ответьте 2xx, потом обрабатывайте заказ: при ошибке или тайм-ауте доставка повторяется до 11 раз, поэтому выполняйте обработку один раз на пару (invoice.id, status). Секрет показывается один раз, когда вы добавляете адрес. В боевом режиме адрес — только https на настоящем домене и без пароля. Настройка вебхуков, проверка подписи: примеры для Express, Laravel и Django.
Опрос статуса
Если принять вебхук негде — нет сервера, доступного снаружи, — спрашивайте статус сами:
curl https://api.qut.kz/api/v1/invoices/inv_… -H 'X-API-Key: qp_live_…'
Статус paid — оплачено. Спрашивать чаще раза в 3–5 секунд бессмысленно: ответ не придёт быстрее, а частые запросы упрутся в ограничение частоты. Там, где клиент стоит рядом и ждёт, держите оба способа: вебхук основной, опрос — страховка. Вебхук или опрос статуса.
Сообщение в Telegram
В чат, привязанный к @QutPayBot, приходит сообщение об оплате: сумма, описание, номер заказа, данные клиента и номер чека. Интеграция для этого не нужна — удобно, когда счета выставляет менеджер вручную. В тот же чат приходят сообщения о возвратах, истёкших счетах и обрыве подключения кассира.
QR или счёт на телефон
| Счёт на телефон | QR-счёт | |
|---|---|---|
| Как доходит до клиента | Уведомление в приложении Kaspi | QR на экране или ссылка payUrl |
| Что нужно знать о клиенте | Номер телефона | Ничего |
| Приложение Kaspi у клиента | Обязательно | Не обязательно: ссылка открывается и в браузере |
| Сумма | Только целые тенге | До 2 знаков после запятой |
| Описание | До 60 символов | До 100 символов |
| Сколько ждёт оплаты | Заметно дольше, чем QR | Окно сканирования — около 3 минут |
| Где удобно | После звонка, в переписке, ежемесячные счета, рассылка по базе | Экран у прилавка, сайт, витрина, вендинг |
Короткое правило: клиент смотрит на ваш экран — QR; клиент далеко, а номер известен — счёт на телефон. Полное сравнение.
Срок жизни и ограничения
Срок счёта приходит в поле expiresAt — берите его оттуда, а не из константы в коде: срок задаёт Kaspi. Счёт на телефон лежит в приложении клиента заметно дольше окна QR, поэтому клиент может оплатить не сразу. Когда срок вышел, счёт переходит в expired и приходит invoice.expired; продлить его нельзя — создайте новый, тот же externalOrderId можно передать снова.
На уже закрытый счёт деньги ещё могут прийти: если клиент подтвердил в последний момент, придёт invoice.paid с пометкой late: true. Это настоящие деньги — выполните заказ или сделайте возврат. Срок жизни счёта.
- В месячный лимит тарифа идут только оплаченные счета: неоплаченные, просроченные и отменённые не считаются.
- Отдельная суточная защита считает счета, созданные за день: на «Бесплатном» — 50, на «Старте» — 200. Тарифы и лимиты.
- Частота запросов к API — 200 записей и 600 чтений в минуту на ключ.
Возвраты
Вернуть деньги можно по оплаченному счёту:
- в кабинете: Счета → откройте счёт → Возврат; для частичного возврата укажите меньшую сумму;
- через API:
POST /api/v1/invoices/{id}/refund; безamount— полный возврат, сamount— частичный. Ключу нужно правоrefunds:write.
curl -X POST https://api.qut.kz/api/v1/invoices/inv_…/refund \
-H 'X-API-Key: qp_live_…' \
-H 'Content-Type: application/json' \
-d '{"amount": 1000, "reason": "Клиент отказался"}'
Деньги уходят с вашего счёта Kaspi Pay: возврат выполняет сам Kaspi, и срок, в течение которого он возможен, тоже задаёт Kaspi. После возврата приходят invoice.refunded или invoice.partially_refunded и сообщение в Telegram. Через Telegram-бота возврат не оформить — так сделано намеренно. На ответ refund_unknown запрос не повторяйте: сначала прочитайте статус счёта. Неоплаченный счёт не возвращают, а отменяют: POST /api/v1/invoices/{id}/cancel, кнопка Отменить в кабинете или /cancel в боте. API возвратов.
Сначала песочница
Ключ qp_test_… работает без реальных денег: счёт создаётся, оплату вы ставите сами (POST /api/v1/invoices/{id}/simulate с телом {"status":"paid"}), вебхуки приходят по-настоящему. Номер 77000000404 в песочнице возвращает kaspi_customer_not_found — так проверяется ветка «номера нет в Kaspi». Симуляция оплаты.
Частые вопросы
Можно выставить счёт Kaspi по номеру без сайта и программиста?
Да. Счёт на телефон выставляется в кабинете (раздел «Счета»), командой /invoice 5000 77011234567 в Telegram-боте или списком из CSV. API нужен, только если счёт должен создаваться автоматически — с сайта, из CRM, бота или 1С.
Как я узнаю, что клиент оплатил?
Автоматически: вебхук invoice.paid с подписью HMAC-SHA256 приходит на ваш сервер обычно в пределах 5 секунд после оплаты, статус можно запросить через GET /api/v1/invoices/{id}, а в привязанный Telegram-чат приходит сообщение об оплате. Все счета и их статусы видны в кабинете.
Что делать, если у клиента нет приложения Kaspi?
Если номер не клиент Kaspi, API сразу ответит kaspi_customer_not_found — повторять на тот же номер не нужно. Если же на этом номере нет приложения Kaspi, счёт останется в pending и истечёт. В обоих случаях создайте QR-счёт и отправьте клиенту ссылку payUrl: она открывается и в браузере.
Деньги снимутся с клиента без его согласия?
Нет. Каждый счёт клиент открывает и подтверждает в приложении Kaspi сам. Ежемесячные счета по подписке — тоже новые счета по расписанию, и каждый из них клиент оплачивает сам.
В каком формате писать номер?
77011234567. API принимает и +7 701 123 45 67, и 87011234567 и приводит их к этому виду. Telegram-бот распознаёт номер в любой записи.
Сколько это стоит?
Qut Pay — фиксированная подписка без процента с платежей: «Бесплатный» тариф — 20 оплат в месяц бессрочно, «Старт» — 4 990 ₸ в месяц за 800 оплат. В лимит идут только оплаченные счета. Комиссию Kaspi удерживает сам Kaspi по своим условиям, как и без нас. Подробнее: тарифы.
Ещё по теме: Kaspi Pay API для сайта, Kaspi и 1С, оплата Kaspi в Telegram и WhatsApp, сравнение сервисов для приёма Kaspi.
Выставите первый счёт на телефон
Зарегистрируйтесь, подключите кассира Kaspi Pay и проверьте весь сценарий в песочнице.
Qut Pay — независимый сервис, не партнёр Kaspi и не аффилирован с АО «Kaspi Bank». Он работает через роль «Кассир» в вашем Kaspi Pay, деньги поступают напрямую на ваш счёт Kaspi Pay. Нужен бизнес-аккаунт Kaspi Pay (ИП или ТОО). Смотрите также: Kaspi API для сайта, счета Kaspi в Telegram и WhatsApp, Kaspi и 1С, счёт Kaspi из Salebot, тарифы, центр доверия.