Kaspi Pay API для сайта и приложения
Публичного API для приёма оплат Kaspi Pay, который любой магазин подключает по документации, у Kaspi нет (API Kaspi Магазина — для заказов маркетплейса, не для оплаты на вашем сайте). Qut Pay даёт разработчику обычный REST API поверх вашего собственного Kaspi Pay: сервер одним запросом создаёт счёт, покупатель платит по Kaspi QR, по счёту в приложении Kaspi.kz на свой номер или по ссылке, а ваш сервер получает подписанный webhook invoice.paid. Работает это через роль «Кассир» в вашем бизнес-аккаунте Kaspi Pay. Деньги идут напрямую на ваш счёт Kaspi Pay, Qut Pay их не касается.
Эта страница — справочник по интеграции Kaspi Pay для разработчиков интернет-магазинов, SaaS, мобильных приложений, ботов и CRM. Как подключить кассира (пять шагов, около 15 минут), описано в пошаговом руководстве.
Коротко об API
- База:
https://api.qut.kz/api/v1, JSON, только HTTPS. - Ключ в заголовке
X-API-Key(илиAuthorization: Bearer …):qp_test_…— песочница,qp_live_…— реальные платежи. - Счета: создать, получить статус, список, отменить, вернуть деньги; до 100 счетов одним запросом (
POST /api/v1/invoices/bulk). - Результат: webhook с подписью HMAC-SHA256 или запрос
GET /api/v1/invoices/{id}. - Спецификация: OpenAPI в JSON, справочник api.qut.kz/docs, руководство «Интеграция с сайтом».
Интеграция Kaspi Pay сводится к двум точкам: создать счёт и узнать результат.
Ваш сервер ──POST /api/v1/invoices──▶ Qut Pay ──счёт──▶ Kaspi
◀── payUrl, qrImageUrl, deepLink
покупатель платит в Kaspi.kz
◀── POST на ваш адрес: invoice.paid (HMAC-SHA256)
Создать счёт
Обязательное поле одно — amount, в тенге.
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-pay' \
-d '{
"amount": 2500,
"description": "Заказ №1001",
"externalOrderId": "1001",
"successUrl": "https://site.kz/ok",
"metadata": { "branch": "almaty-1" }
}'
Ответ — HTTP 201:
{ "id": "inv_…", "status": "pending", "payUrl": "https://qut.kz/pay/inv_…", "qrUrl": "…", "deepLink": "…", "qrImageUrl": "…", "expiresAt": "…" }
Отправьте покупателя на payUrl или выведите QR на своей странице. Все поля запроса и ответа и коды ошибок собраны в справочнике по созданию счёта.
Kaspi QR, счёт на телефон или ссылка
Отдельный «Kaspi QR API» не нужен: все три сценария закрывает один эндпоинт, тип счёта задаёт поле kind.
| Способ | Как в API | Когда удобно |
|---|---|---|
| Kaspi QR | kind: "qr" (по умолчанию), картинка qrImageUrl (SVG) или qrPngUrl | Сайт, экран киоска, витрина |
| Счёт на номер покупателя | kind: "phone" и customer.phone в формате 7XXXXXXXXXX | Продажа в чате, по телефону, подписки |
| Ссылка на оплату | payUrl — готовая страница оплаты, deepLink сразу открывает приложение Kaspi | Ссылка в мессенджере, редирект с сайта |
- Окно сканирования QR — около трёх минут, его задаёт Kaspi. Не зашивайте это число в код, берите
expiresAtиз ответа. - Счёт на телефон — только целые тенге, описание до 60 символов (у QR — до 100). Если номер не клиент Kaspi, придёт
422 kaspi_customer_not_found: не повторяйте запрос, предложите QR. - Постоянная ссылка без привязки к заказу (Instagram, печатный QR, пакеты пополнения баланса):
POST /api/v1/payment-linksсоздаёт страницуqut.kz/p/<slug>. Каждая оплата по ней — обычный счёт с теми же webhook.
Подробнее: QR-счёт или счёт по телефону, платёжные ссылки.
Webhook оплаты Kaspi и проверка подписи
Адрес добавляется в кабинете, в разделе Интеграции: там же выбираются события, а секрет показывается один раз. В боевом режиме адрес должен быть на https и на настоящем домене, без авторизации.
POST /qutpay-webhook
X-Webhook-Event: invoice.paid
X-Webhook-Timestamp: 1757167000
X-Webhook-Signature: sha256=3f1a…
X-Webhook-Delivery: 17
{ "event": "invoice.paid", "invoice": { "id": "inv_…", "externalOrderId": "1001", "status": "paid", "amount": 2500, "metadata": { "branch": "almaty-1" }, "paidAt": "…" }, "sentAt": "…" }
Подпись считается так:
signature = "sha256=" + hex( HMAC-SHA256( secret, timestamp + "." + rawBody ) )
Четыре правила:
- Считайте подпись по сырому телу запроса, до разбора JSON. После
JSON.stringify(req.body)байты другие, и подпись не сойдётся. - Не принимайте
timestampстарше 5 минут. Сравнивайте подпись за постоянное время:timingSafeEqual,hash_equals,hmac.compare_digest. - Сначала ответьте 2xx, работу делайте после. На ответ не 2xx доставка повторяется до 11 раз, с паузой от 10 секунд до часа.
- Обрабатывайте событие один раз по паре
(invoice.id, status): одно и то же событие может прийти повторно.
Обычно хватает двух событий: invoice.paid и invoice.refunded. Если деньги по уже закрытому счёту (expired, cancelled) пришли с опозданием, invoice.paid всё равно придёт, с признаком late: true: выполните заказ или сделайте возврат. Примеры для Express, Laravel и Django — в статье «Безопасность вебхуков», события и журнал доставок — в «Настройке вебхуков».
Опрос статуса вместо webhook
Если у вашей системы нет доступного извне адреса (устройство за NAT или на GSM-модеме, конструктор ботов), спрашивайте статус сами:
GET https://api.qut.kz/api/v1/invoices/{id}
X-API-Key: qp_live_…
→ { "id": "inv_…", "status": "paid", … }
Если покупатель ждёт у экрана, ведите оба канала. Webhook остаётся основным и обычно приходит в пределах 5 секунд, а первые 30 секунд параллельно опрашивайте статус, примерно раз в секунду. Что пришло раньше, то и принимайте. Подробно: вебхук или опрос статуса; для киосков и терминалов есть отдельная страница «Kaspi-оплата для устройств через API».
Возвраты, идемпотентность, metadata
Возврат — POST /api/v1/invoices/{id}/refund с телом { "amount": 1500, "reason": "Товар возвращён" }. Без amount счёт возвращается полностью, с amount — частично (статус partially_refunded); сумма всех возвратов не больше оплаченной. Ключу нужно право refunds:write, деньги уходят с вашего счёта Kaspi. При refund_unknown и refund_pending_unknown запрос не повторяйте, а прочитайте статус счёта. Подробнее: API возвратов.
Idempotency-Key — заголовок с ключом, который вычисляется в вашей системе, например order-1001-pay. Повтор с тем же ключом не создаёт новый счёт: вернётся прежний, с HTTP 200 и idempotentReplay: true. Поэтому после таймаута запрос можно спокойно повторить. Подробнее: идемпотентность.
externalOrderId — ваш номер заказа. Он возвращается в webhook, по нему ищут счёт: GET /api/v1/invoices?externalOrderId=1001. От дублей он не защищает, для этого нужен Idempotency-Key.
metadata — любой JSON: точка продаж, корзина, номер ячейки. Хранится без изменений и возвращается и в webhook, и в ответе на запрос статуса. Подробнее: metadata и номер заказа.
Песочница, ключи, лимиты
- Песочница. Ключ
qp_test_…работает без кассира и без денег, Kaspi не вызывается. Оплату имитируетPOST /api/v1/invoices/{id}/simulateс{"status":"paid"}(а такжеfailedиexpired). Webhook отправляются по-настоящему, адрес может бытьhttpиlocalhost. Счета песочницы не входят в лимит тарифа и не запускают пробный период. Как симулировать оплату. - Ключи. Создаются в кабинете (Интеграции → API-ключи) и показываются один раз. Ключ живёт только на сервере. Заводите отдельный ключ на каждую интеграцию. По умолчанию у ключа права
invoices:readиinvoices:write, а возвраты — отдельное правоrefunds:write. Если у вас несколько точек или проектов, ключ можно привязать к конкретному кассиру. Подробнее: API-ключи, права доступа. - Лимиты частоты. На один ключ — 600 чтений (GET) и 200 записей в минуту. При превышении приходит
429 request_rate_limitedс заголовкомRetry-After, остаток показываетX-RateLimit-Remaining. Кодыtariff_limit_reachedиtariff_daily_burstприходят с тем же HTTP 429, но это лимиты тарифа, и повтор не поможет. Подробнее: ограничения частоты.
SDK, модули и инструменты
Пример на Node.js SDK: создать счёт и принять webhook.
import express from 'express';
import { QutPay, verifyWebhook } from '@qutpay/sdk';
const app = express();
const qp = new QutPay({ apiKey: process.env.QUTPAY_API_KEY });
app.post('/buy', async (req, res) => {
const inv = await qp.createInvoice({
amount: 2500,
description: 'Заказ №1001',
externalOrderId: '1001',
successUrl: 'https://site.kz/ok',
idempotencyKey: 'order-1001-pay', // уходит в заголовок Idempotency-Key
});
res.redirect(inv.payUrl);
});
app.post('/qutpay-webhook', express.raw({ type: '*/*' }), (req, res) => {
if (!verifyWebhook({ secret: process.env.QUTPAY_WEBHOOK_SECRET, rawBody: req.body, headers: req.headers })) return res.sendStatus(401);
const { event, invoice } = JSON.parse(req.body);
if (event === 'invoice.paid') markPaid(invoice.externalOrderId);
res.sendStatus(200);
});
| Что | Где взять |
|---|---|
Node.js SDK: @qutpay/sdk, ESM, Node.js 18+, без зависимостей | qutpay-sdk-node.zip · описание |
PHP SDK: один файл, PHP 7.4+, классы \QutPay\Client и \QutPay\Webhook | qutpay-sdk-php.zip · описание |
Python SDK: только стандартная библиотека, Python 3.8+, create_invoice и verify_webhook | qutpay-sdk-python.zip · описание |
| WooCommerce | плагин на WordPress.org · инструкция |
| OpenCart 4 | qutpay.ocmod.zip · описание |
| n8n: готовые workflow — создание счёта и приём событий с проверкой подписи | qutpay-n8n.zip · описание |
| 1С | интеграция с 1С |
| MCP-сервер для ИИ-агентов (Claude Code, Cursor, Claude Desktop): счета, статус, возвраты, симуляция оплаты в песочнице | npx -y @qutpay/mcp или удалённо https://api.qut.kz/mcp · руководство |
| Инструкция для ИИ-ассистента: Claude, Cursor или ChatGPT напишут интеграцию сами | api.qut.kz/for-ai · SKILL.md · llms.txt |
Без своего кода тоже можно: формы Tilda подключаются через форма-хук (кабинет → Интеграции), а бот в Salebot выставляет счёт одним блоком — Salebot и счёт Kaspi.
Мобильное приложение
Приложение не обращается к Qut Pay напрямую, только через ваш сервер:
Приложение → Ваш сервер → Qut Pay → Kaspi
Ключ внутри APK или IPA можно извлечь, поэтому он живёт только на сервере. Сервер создаёт счёт и отдаёт приложению payUrl или deepLink, на телефоне сразу открывается Kaspi; об оплате сервер узнаёт по webhook и сообщает приложению. Подробнее: приём оплаты в мобильном приложении.
Что нужно и сколько стоит
- Бизнес-аккаунт Kaspi Pay (ИП или ТОО).
- Отдельный номер для кассира, у которого есть только роль «Кассир», — почему и как его подключить.
- 7 дней пробного периода, отсчёт идёт с первого реального счёта. Дальше остаётся бесплатный тариф — 20 оплат в месяц; если больше — от 4 990 ₸ в месяц за 800 оплат. В лимит входят только оплаченные счета. API, webhook, возвраты, SDK и модули есть на всех тарифах.
- Платформа не берёт процент с платежей; комиссию Kaspi (0,95 % за QR) банк удерживает отдельно, как и без нас.
Подробнее: тарифы, сравнение сервисов приёма Kaspi с ценами и источниками.
Ограничения, о которых лучше знать заранее
- Qut Pay — независимый сервис, не партнёр Kaspi и не аффилирован с АО «Kaspi Bank». Он работает через штатную роль «Кассир» вашего бизнес-аккаунта. У Kaspi нет публичного API для сторонних сервисов, и Kaspi может ограничить такой доступ или кассира, через которого идёт аномально большой поток. Деньги, уже полученные на ваш счёт, это не затрагивает.
- Если связь с кассиром оборвалась (например, кто-то вошёл в Kaspi Pay с номера кассира), новые счета не создаются и API отвечает
409 kaspi_session_expired. Уведомление приходит в Telegram, кассира переподключают в кабинете. Обработайте этот код: покажите «Оплата временно недоступна» или предложите другой способ оплаты. - Без интернета не работает: счёт создаётся на стороне Kaspi.
- Договорного SLA нет. Статус, меры безопасности и риски описаны в центре доверия.
Частые вопросы
Есть ли официальный API Kaspi для сайта?
Публичного API для приёма оплат, который любой бизнес подключает по документации, у Kaspi нет. Официально есть приложение Kaspi Pay и индивидуальные интеграции по договору с Kaspi. Qut Pay даёт REST API поверх роли «Кассир» в вашем собственном аккаунте Kaspi Pay. Это независимый сервис, не партнёр Kaspi. Подробно: есть ли у Kaspi Pay API для сайта.
Проходят ли деньги через Qut Pay?
Нет. Счёт выставляется от имени вашего кассира, покупатель платит напрямую на ваш бизнес-счёт Kaspi Pay. Возврат тоже выполняет Kaspi с вашего счёта. У платформы нет доступа к вашим деньгам.
Как проверить интеграцию без кассира и без денег?
Ключом qp_test_… в песочнице. Создайте счёт, вызовите POST /api/v1/invoices/{id}/simulate со статусом paid, и на ваш адрес придёт настоящий webhook с подписью. Адрес в песочнице может быть http://localhost. Когда всё работает, подключите кассира и замените ключ на qp_live_….
Можно ли вызывать API прямо из браузера или мобильного приложения?
Нет. Ключ из JavaScript в браузере или из APK/IPA может достать любой желающий и выставлять счета от вашего имени. Браузер и приложение обращаются к вашему серверу, сервер — к Qut Pay.
Что будет, если повторить запрос на создание счёта?
С тем же заголовком Idempotency-Key вернётся уже созданный счёт (HTTP 200, idempotentReplay: true), второго не появится. Без этого заголовка каждый запрос создаёт новый счёт, даже с тем же externalOrderId.
Нужно ли давать сервису пароль от Kaspi Pay?
Нет. Кассир подключается по SMS-коду, который приходит на его номер. Пароль не запрашивается и не хранится.
Ещё по теме: счёт Kaspi по номеру телефона и вебхук, Kaspi и 1С, оплата Kaspi в Telegram-боте и WhatsApp, сравнение сервисов для приёма Kaspi.
Начните с тестового ключа
Зарегистрируйтесь, создайте ключ qp_test_… и прогоните весь сценарий в песочнице — без кассира и без денег.
Qut Pay — независимый сервис, не партнёр Kaspi и не аффилирован с АО «Kaspi Bank». Для работы нужен бизнес-аккаунт Kaspi Pay (ИП или ТОО). Подробнее: пошаговое подключение, тарифы, центр доверия, база знаний.