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 туралы қысқаша
- Негізгі адрес:
https://api.qut.kz/api/v1, JSON, тек HTTPS. - Кілт
X-API-Keyтақырыбында (немесеAuthorization: Bearer …):qp_test_…— sandbox,qp_live_…— нақты төлем. - Счёттар: жасау, күйін алу, тізім, болдырмау, ақша қайтару; бір сұраумен 100 счётқа дейін (
POST /api/v1/invoices/bulk). - Нәтиже: HMAC-SHA256 қолтаңбалы webhook немесе
GET /api/v1/invoices/{id}сұрауы. - Сипаттама: OpenAPI (JSON), анықтамалық api.qut.kz/docs, сайтқа интеграция нұсқаулығы.
Сайтыңыз 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 QR | kind: "qr" (әдепкі), сурет qrImageUrl (SVG) не qrPngUrl | Сайт, киоск экраны, витрина |
| Сатып алушының нөміріне счёт | kind: "phone" және 7XXXXXXXXXX пішіміндегі customer.phone | Чатта, телефонмен сату, жазылым |
| Төлем сілтемесі | payUrl — дайын төлем беті, deepLink Kaspi қосымшасын бірден ашады | Мессенджердегі сілтеме, сайттан бағыттау |
- QR-ды сканерлеуге шамамен үш минут беріледі, бұл уақытты Kaspi белгілейді. Санды кодқа жазып қоймаңыз, жауаптағы
expiresAt-ты алыңыз. - Телефонға счёт — тек бүтін теңге, сипаттамасы 60 таңбаға дейін (QR-да — 100). Нөмір Kaspi клиенті болмаса,
422 kaspi_customer_not_foundкеледі: сұрауды қайталамаңыз, QR ұсыныңыз. - Тапсырысқа байланбаған тұрақты сілтеме (Instagram, басылған QR, баланс толтыру пакеттері):
POST /api/v1/payment-linksqut.kz/p/<slug>бетін жасайды. Ол арқылы өткен әр төлем — кәдімгі счёт, webhook-тары да сол.
Толығы: 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 ) )
Төрт ереже:
- Қолтаңбаны денені JSON-ға айналдырмай тұрып, сұраудың өзгертілмеген денесі (raw body) бойынша есептеңіз.
JSON.stringify(req.body)-дан кейін байттар өзгереді де, қолтаңба сәйкес келмейді. - 5 минуттан ескі
timestamp-ты қабылдамаңыз. Қолтаңбаны тұрақты уақытта салыстырыңыз: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 қауіпсіздігі» мақаласында, оқиғалар мен жеткізу журналы — «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, кілттер, лимиттер
- Sandbox.
qp_test_…кілті кассирсіз, нақты ақшасыз жұмыс істейді, Kaspi-ге ешнәрсе жіберілмейді. ТөлемдіPOST /api/v1/invoices/{id}/simulateсұрауы{"status":"paid"}денесімен имитациялайды (failedпенexpiredте бар). Webhook шын жіберіледі, адресhttpжәнеlocalhostбола алады. Sandbox счёттары тариф лимитіне кірмейді, сынақ мерзімін де бастамайды. Sandbox-та төлемді симуляциялау. - Кілттер. Кабинетте (Интеграциялар → API кілттері) жасалады, бір рет қана көрсетіледі. Кілт тек серверде тұрады. Әр интеграцияға бөлек кілт жасаңыз. Әдепкі кілтте
invoices:readпенinvoices:writeқұқығы бар, қайтаруға бөлекrefunds:writeқұқығы керек. Нүкте не жоба бірнешеу болса, кілтті нақты кассирге байлауға болады. Толығы: API кілттер, құқықтар (scopes). - Сұрау жиілігі. Бір кілтке минутына 600 оқу (GET) және 200 жазу сұрауы. Асып кетсе,
Retry-Afterтақырыбымен429 request_rate_limitedкеледі, қалған санды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 · сипаттама |
| 1C | 1C интеграциясы (орысша) |
| ЖИ-агентке арналған 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 Pay бизнес-аккаунты (ЖК немесе ЖШС).
- Кассирге бөлек нөмір, онда тек «Кассир» рөлі болуы керек — неге және қалай жалғайды.
- 7 күн сынақ, есеп бірінші нақты счёттан басталады. Одан кейін тегін тариф қалады — айына 20 төлем; көбірек болса, айына 4 990 ₸-ден, 800 төлем. Лимитке тек төленген счёттар кіреді. API, webhook, қайтару, SDK мен модульдер барлық тарифте бар.
- Платформа төлемнен пайыз алмайды; Kaspi өз комиссиясын (QR үшін 0,95 %) бөлек ұстайды, бізсіз де солай.
Толығы: тарифтер, Kaspi қабылдау сервистерінің бағасы мен дереккөзі бар салыстыруы.
Алдын ала білген жөн
- Qut Pay — тәуелсіз сервис, Kaspi серіктесі емес, «Kaspi Bank» АҚ-мен аффилирленбеген. Ол бизнес-аккаунтыңыздағы штаттық «Кассир» рөлі арқылы жұмыс істейді. Kaspi-де бөгде сервистерге арналған ашық API жоқ, және Kaspi мұндай қолжетімділікті немесе аномальды көп ағын өтетін кассирді шектей алады. Шотыңызға түсіп үлгерген ақшаға бұл әсер етпейді.
- Кассир байланысы үзілсе (мысалы, біреу кассир нөмірімен Kaspi Pay-ге кірсе), жаңа счёт жасалмайды, API
409 kaspi_session_expiredқайтарады. Хабар Telegram-ға келеді, кассирді кабинетте қайта жалғайсыз. Бұл кодты бағдарламаңыз өңдесін: «Төлем уақытша қолжетімсіз» деп көрсетсін не басқа төлем тәсілін ұсынсын. - Интернетсіз жұмыс істемейді: счёт Kaspi жағында жасалады.
- Шартта бекітілген SLA жоқ. Сервистің күйі, қауіпсіздік шаралары мен тәуекелдер — сенім орталығында.
Жиі қойылатын сұрақтар
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-та тексеріңіз — кассирсіз, ақшасыз.
Qut Pay — тәуелсіз сервис, Kaspi серіктесі емес, «Kaspi Bank» АҚ-мен аффилирленбеген. Жұмыс істеу үшін Kaspi Pay бизнес-аккаунты (ЖК немесе ЖШС) керек. Толығы: қадамдық қосу нұсқаулығы, тарифтер, сенім орталығы, білім базасы.