Өз құрылғыңызға Kaspi төлемін API арқылы қосыңыз

Өзіңіз жасаған немесе бағдарламасын өзіңіз жазатын құрылғы бар болса — өзіне-өзі қызмет көрсету киоскі, терминал, планшеттегі касса, ойын аппараты, зарядтау станциясы, кез келген «сатып алу» батырмасы бар қондырғы — оған Kaspi төлемін бір HTTP сұраныспен қосасыз. Құрылғы Qut Pay-ден счёт сұрайды, экранға QR шығарады, клиент Kaspi.kz қосымшасымен сканерлеп төлейді, құрылғы «төленді» деген жауап алып, тауарды береді.

Ақша тікелей сіздің Kaspi Pay шотыңызға түседі. Qut Pay ақшаны ұстамайды, тек счёт жасайды, күйін бақылайды және сізге хабарлайды.

Кімге арналған

• Құрылғыда экран (немесе жанында планшет) және интернет бар.
• Құрылғының бағдарламасын өзіңіз не әзірлеушіңіз жазады, яғни оған HTTP сұраныс қосуға болады.
• Сізде ЖК немесе ЖШС атына ашылған Kaspi Pay бар.

Экраны жоқ, импульспен не MDB арқылы басқарылатын дайын вендинг-автоматтарға (су, кофе, жуу) арнайы модуль сататын жеткізушілер ыңғайлырақ: ол жерде мәселе — API емес, автоматтың платасына жалғайтын «темір». Qut Pay құрылғы да, модуль де сатпайды, тек бағдарламалық API береді.

Қалай жұмыс істейді

Клиент «Төлеу» басады
  → құрылғы POST /invoices жасайды
  → экранға QR шығады (≈3 минут жарамды)
  → клиент Kaspi.kz-пен сканерлейді
  → Qut Pay күйді «paid» етеді
  → құрылғы жауап алады → тауар беріледі

Счёт жасау:

POST https://api.qut.kz/api/v1/invoices
X-API-Key: qp_live_…
Idempotency-Key: kiosk7-000154
{ "amount": 500, "externalOrderId": "kiosk7-000154", "description": "Киоск №7, 500 ₸" }
→ { "id": "inv_…", "status": "pending", "qrImageUrl": "https://qut.kz/pay/inv_…/qr.svg", "deepLink": "https://kaspi.kz/pay/…", "expiresAt": "…" }

Құрылғы qrImageUrl (SVG) суретін экранға шығарады. Экранды QR-ды телефонмен сканерлеу ыңғайсыз болса, клиенттің нөмірін енгізіп, счётты оның Kaspi.kz қосымшасына жіберуге болады: "kind": "phone" және customer.phone (сома бүтін теңге болуы керек).

Төлемді қалай білу керек

Екі жол бар, екеуін бірге қолдануға да болады:

1. Webhook. Қолтаңбалы (HMAC-SHA256) invoice.paid хабарын Qut Pay сіздің серверге жібереді. Құрылғылар бір серверге бағынса, сервер құрылғыға «бер» командасын жібереді. Бұл ең сенімді жол.

2. Сұрау (polling). Құрылғы NAT артында, GSM-модеммен, тұрақты адресі жоқ болса — сыртқы сұранысты қабылдай алмайды. Онда құрылғы өзі 2–3 секунд сайын GET /invoices/{id} сұрайды, status paid болғанда тауарды береді. expiresAt өткенде экранды тазартып, қажет болса жаңа счёт жасайды.

Кеш төлем болуы мүмкін: клиент соңғы секундта сканерлесе, expired болған счёт сәлден кейін paid болады. Бағдарламаңыз мұны өңдеуі керек — тауарды беру немесе ақшаны қайтару.

Кілтті қалай сақтау керек

• Әр құрылғыға бөлек API кілт жасаңыз (кабинет → Интеграциялар). Құрылғы ұрланса не бұзылса, тек сол кілтті өшіресіз, қалғандары жұмыс істей береді.
• Әдепкі кілтте тек invoices:read пен invoices:write құқығы бар — қайтаруға рұқсат жоқ. Құрылғыға қайтару құқығын бермеңіз.
• Құрылғылар көп болса және бір серверге қосылса, кілтті серверде ұстап, құрылғы тек серверге жүгінгені дұрысырақ.
• Idempotency-Key жіберіңіз: байланыс үзіліп, сұраныс қайталанса, екінші счёт жасалмайды.

Бірнеше нүкте, бірнеше кассир

Кабинетте бірнеше Kaspi кассир қосуға және API кілтті нақты кассирге байлауға болады. Әр нүктенің төлемі өз кассирі арқылы өтеді, есепті нүкте бойынша бөлек көресіз. externalOrderId пен metadata ішіне құрылғы нөмірін жазсаңыз, кез келген төлемді қай аппараттан өткенін табасыз.

Не дайын

• REST API және OpenAPI: api.qut.kz/docs
• Node, PHP, Python SDK; интеграция нұсқаулығы: api.qut.kz/docs/guide/integration
• ЖИ-агентке дайын нұсқаулық — Claude, Cursor, ChatGPT құрылғыңыздың кодына төлемді өзі қосады: api.qut.kz/for-ai
• Sandbox: qp_test_… кілті Kaspi-сіз, нақты ақшасыз жұмыс істейді. Төлемді POST /invoices/{id}/simulate арқылы жасайсыз, webhook шын жетеді. Құрылғыны кассир қоспай-ақ толық тексересіз.

Қанша тұрады

7 күн тегін, бірінші нақты счёттан басталады. Одан кейін айына 4 990 ₸-ден, 800 счёт. Платформа төлемнен пайыз алмайды; Kaspi өз комиссиясын (QR үшін 0,95 %) бөлек ұстайды, бізсіз де солай. Құрылғы көп болса, тарифті счёт саны бойынша таңдайсыз: тарифтер.

Шектеулер, алдын ала білу керек

• Интернет міндетті. Счёт Kaspi жағында жасалады; байланыссыз құрылғы QR шығара алмайды.
• QR ≈3 минут жарамды — Kaspi-дің шегі. Клиент кешіксе, жаңа счёт жасалады.
• Kaspi кассир байланысы үзілсе (біреу кассир нөмірімен Kaspi Pay-ге кірсе), счёттар жасалмайды, API kaspi_session_expired қайтарады. Хабар Telegram-ға келеді, кабинетте қайта жалғайсыз. Құрылғы бұл қатені көрсе, экранға «Төлем уақытша қолжетімсіз» деп жазғаны жөн.
• Qut Pay — сіздің өз Kaspi Pay аккаунтыңыздың үстінде «Кассир» рөлімен жұмыс істейтін тәуелсіз сервис. Біз «Kaspi Bank» АҚ-мен аффилирленбегенбіз. Kaspi-дің шарттары мен тәуекелдері: сенім орталығы.

Құрылғыңыздың сұлбасы бойынша сұрақ болса — кабинеттегі Қолдау бөліміне немесе байланыстарға жазыңыз, қай жолды (webhook не сұрау) таңдау керегін бірге шешеміз.

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