← qut.kz

Kaspi Pay API сайтқа және қосымшаға

Kaspi-де кез келген дүкен құжаттамаға қарап өзі қосып ала алатын, төлем қабылдауға арналған ашық Kaspi Pay API жоқ (Kaspi Магазин API-і маркетплейс тапсырыстарына арналған, сайттағы төлемге емес). Qut Pay әзірлеушіге сіздің өз Kaspi Pay аккаунтыңыздың үстінде жұмыс істейтін кәдімгі REST API береді: сервер бір сұраумен счёт жасайды, сатып алушы Kaspi QR арқылы, өз нөміріне Kaspi.kz қосымшасына келген счёт арқылы не сілтеме арқылы төлейді, ал сіздің серверіңіз қолтаңбалы invoice.paid webhook алады. Мұның бәрі Kaspi Pay бизнес-аккаунтыңыздағы «Кассир» рөлі арқылы жүреді. Ақша тікелей сіздің Kaspi Pay шотыңызға түседі, Qut Pay оған тимейді.

Бұл бет — интернет-дүкен, SaaS, мобильді қосымша, бот не CRM жасайтын әзірлеушіге Kaspi интеграциясы бойынша анықтамалық. Кассирді қалай жалғау керегі (бес қадам, шамамен 15 минут) қадамдық нұсқаулықта жазылған.

API туралы қысқаша

Сайтыңыз Qut 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" және 7XXXXXXXXXX пішіміндегі customer.phoneЧатта, телефонмен сату, жазылым
Төлем сілтемесіpayUrl — дайын төлем беті, deepLink Kaspi қосымшасын бірден ашадыМессенджердегі сілтеме, сайттан бағыттау

Толығы: QR счёт пен телефонға счёт, төлем сілтемелері.

Kaspi төлемінің webhook-ы және қолтаңбаны тексеру

Адрес кабинеттегі Интеграциялар бөлімінде қосылады: оқиғалар да сонда таңдалады, ал құпия бір рет қана көрсетіледі. Live режимде адрес 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-ға айналдырмай тұрып, сұраудың өзгертілмеген денесі (raw body) бойынша есептеңіз. JSON.stringify(req.body)-дан кейін байттар өзгереді де, қолтаңба сәйкес келмейді.
  2. 5 минуттан ескі timestamp-ты қабылдамаңыз. Қолтаңбаны тұрақты уақытта салыстырыңыз: 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 қауіпсіздігі» мақаласында, оқиғалар мен жеткізу журналы — «Webhook баптау» мақаласында.

Webhook орнына күйді сұрау

Жүйеңізде сырттан кіруге болатын адрес болмаса (құрылғы NAT артында не GSM-модеммен жұмыс істейді, бот конструкторы), күйді өзіңіз сұраңыз:

GET https://api.qut.kz/api/v1/invoices/{id}
X-API-Key: qp_live_…
→ { "id": "inv_…", "status": "paid", … }

Сатып алушы экран алдында күтіп тұрса, екі арнаны қатар ұстаңыз. Webhook негізгі арна болып қалады, әдетте 5 секунд ішінде келеді; ал алғашқы 30 секунд күйді шамамен секунд сайын сұрап тұрыңыз. Қайсысы бұрын келсе, соны қабылдайсыз. Толығы: webhook пен күйді сұрау; киоск пен терминалға бөлек бет бар: өз құрылғыңызға Kaspi төлемін API арқылы қосу.

Қайтару, идемпоттылық, metadata

Қайтару — POST /api/v1/invoices/{id}/refund, денесі { "amount": 1500, "reason": "Тауар қайтарылды" }. 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 және тапсырыс нөмірі.

Sandbox, кілттер, лимиттер

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_webhookqutpay-sdk-python.zip · сипаттама
WooCommerceWordPress.org-тағы плагин · нұсқаулық
OpenCart 4qutpay.ocmod.zip · сипаттама
n8n: дайын workflow-тар — счёт жасау және қолтаңбасын тексеріп оқиға қабылдауqutpay-n8n.zip · сипаттама
1C1C интеграциясы (орысша)
ЖИ-агентке арналған MCP сервер (Claude Code, Cursor, Claude Desktop): счёт, күй, қайтару, sandbox-та төлем симуляциясы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 қабылдау сервистерінің бағасы мен дереккөзі бар салыстыруы.

Алдын ала білген жөн

Жиі қойылатын сұрақтар

Kaspi-дің сайтқа арналған ресми API-і бар ма?

Кез келген бизнес құжаттама бойынша қоса алатын, төлем қабылдауға арналған ашық API Kaspi-де жоқ. Ресми түрде Kaspi Pay қосымшасы және Kaspi-мен шарт бойынша жеке интеграция бар. Qut Pay сіздің өз Kaspi Pay аккаунтыңыздағы «Кассир» рөлінің үстінен REST API береді. Бұл тәуелсіз сервис, Kaspi серіктесі емес. Толығы: Kaspi Pay-дің сайтқа арналған API-і бар ма.

Ақша Qut Pay арқылы өте ме?

Жоқ. Счёт сіздің кассиріңіздің атынан шығады, сатып алушы тікелей сіздің Kaspi Pay бизнес-шотыңызға төлейді. Қайтаруды да Kaspi сіздің шотыңыздан жасайды. Платформаның сіздің ақшаңызға қолы жетпейді.

Интеграцияны кассирсіз, ақшасыз қалай тексеремін?

qp_test_… кілтімен sandbox-та. Счёт жасап, POST /api/v1/invoices/{id}/simulate сұрауын paid күйімен жіберіңіз — адресіңізге қолтаңбасы бар шын webhook келеді. Sandbox-та адрес http://localhost бола алады. Бәрі жұмыс істегенде кассирді жалғап, кілтті qp_live_…-ке ауыстырасыз.

API-ді браузерден не мобильді қосымшадан тікелей шақыруға бола ма?

Жоқ. Браузердегі JavaScript-тен не APK/IPA ішінен кілтті кез келген адам алып, сіздің атыңыздан счёт шығара алады. Браузер мен қосымша сіздің серверге жүгінеді, сервер — Qut Pay-ге.

Счёт жасау сұрауын қайталасам не болады?

Сол Idempotency-Key тақырыбымен бұрын жасалған счёт қайтады (HTTP 200, idempotentReplay: true), екіншісі пайда болмайды. Бұл тақырып болмаса, externalOrderId бірдей болса да, әр сұрау жаңа счёт жасайды.

Сервиске Kaspi Pay паролін беру керек пе?

Жоқ. Кассир өз нөміріне келген SMS-кодпен жалғанады. Пароль сұралмайды және сақталмайды.

Тақырып бойынша тағы: Kaspi шотын нөмірге жіберу және вебхук, Kaspi және 1С, Telegram мен WhatsApp-та Kaspi төлем, Kaspi сервистерін салыстыру.

Тест кілтінен бастаңыз

Тіркеліңіз, qp_test_… кілтін жасап, бүкіл сценарийді sandbox-та тексеріңіз — кассирсіз, ақшасыз.

Тіркелу API құжаттамасы

Qut Pay — тәуелсіз сервис, Kaspi серіктесі емес, «Kaspi Bank» АҚ-мен аффилирленбеген. Жұмыс істеу үшін Kaspi Pay бизнес-аккаунты (ЖК немесе ЖШС) керек. Толығы: қадамдық қосу нұсқаулығы, тарифтер, сенім орталығы, білім базасы.

Жаңартылды: 2026-11-22