← qut.kz

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

Интеграция 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 QRkind: "qr" (по умолчанию), картинка qrImageUrl (SVG) или qrPngUrlСайт, экран киоска, витрина
Счёт на номер покупателяkind: "phone" и customer.phone в формате 7XXXXXXXXXXПродажа в чате, по телефону, подписки
Ссылка на оплатуpayUrl — готовая страница оплаты, deepLink сразу открывает приложение KaspiСсылка в мессенджере, редирект с сайта

Подробнее: 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 ) )

Четыре правила:

  1. Считайте подпись по сырому телу запроса, до разбора JSON. После JSON.stringify(req.body) байты другие, и подпись не сойдётся.
  2. Не принимайте timestamp старше 5 минут. Сравнивайте подпись за постоянное время: timingSafeEqual, hash_equals, hmac.compare_digest.
  3. Сначала ответьте 2xx, работу делайте после. На ответ не 2xx доставка повторяется до 11 раз, с паузой от 10 секунд до часа.
  4. Обрабатывайте событие один раз по паре (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 и номер заказа.

Песочница, ключи, лимиты

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\Webhookqutpay-sdk-php.zip · описание
Python SDK: только стандартная библиотека, Python 3.8+, create_invoice и verify_webhookqutpay-sdk-python.zip · описание
WooCommerceплагин на WordPress.org · инструкция
OpenCart 4qutpay.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 с ценами и источниками.

Ограничения, о которых лучше знать заранее

Частые вопросы

Есть ли официальный 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_… и прогоните весь сценарий в песочнице — без кассира и без денег.

Зарегистрироваться Документация API

Qut Pay — независимый сервис, не партнёр Kaspi и не аффилирован с АО «Kaspi Bank». Для работы нужен бизнес-аккаунт Kaspi Pay (ИП или ТОО). Подробнее: пошаговое подключение, тарифы, центр доверия, база знаний.

Обновлено: 2026-11-22