Kaspi шотын нөмірге жіберу
Qut Pay-де Kaspi шотын нөмірге жіберу дегеніміз — «телефонға» түріндегі шот: сомасы мен клиенттің нөмірін жазасыз, шот хабарлама болып тікелей клиенттің Kaspi қосымшасына түседі, клиент оны ашып, төлемді растайды. Мұндай шотты кабинеттен, Telegram-бот командасымен, CSV тізімімен немесе API-ге бір сұраныспен жібересіз. Төлем түскенін сізге жүйенің өзі хабарлайды: HMAC-SHA256 қолтаңбалы invoice.paid webhook-ы, күйін сұрау немесе Telegram хабары арқылы. Ақша тікелей сіздің Kaspi Pay шотыңызға түседі.
Qut Pay сіздің өз Kaspi Pay-іңіздегі «Кассир» рөлі арқылы жұмыс істейді: бөлек нөмірмен кассир қосып, оны кабинетте жалғайсыз — 15 минутта қалай қосу керек. Kaspi Pay бизнес-аккаунты (ЖК немесе ЖШС) керек.
Клиент не көреді
- Kaspi қосымшасына шот туралы хабарлама келеді. QR сканерлеудің де, сілтеме ашудың да қажеті жоқ.
- Шотта сома, сіз жазған сипаттама (60 таңбаға дейін), Kaspi Pay-де қалай жазылса, солай дүкен атауы және кассир нөмірі көрінеді. Кассир нөмірін Kaspi өзі көрсетеді, оны жасыруға болмайды — сондықтан кассирге жеке нөміріңізді емес, бөлек нөмір берген дұрыс.
- Клиент шотты ашып, төлемді растайды. Ол растамайынша ақша ешқайда кетпейді: шот — төлем сұрауы ғана, клиенттің шотынан ақша өздігінен шешілмейді.
- Төлегеннен кейін клиентте Kaspi чегі қалады; оған қоса Qut Pay чек бетін (
receiptUrl) жіберуге болады. - Тапсырыс нөміріңізді (
externalOrderId) жәнеmetadata-ны клиент көрмейді.
Толығы: клиент не көреді.
Клиентке Kaspi шот жіберу
Кабинеттен
Счёттар бөлімі → түрі «Телефонға счёт (Kaspi қосымшасы)» → сома, клиенттің нөмірі, сипаттама және тапсырыс нөмірі → Жасау. Алдымен нөмірді жазсаңыз, түрі «телефонға» өзі ауысады. Шот бірден тізімде күйімен бірге көрінеді.
Telegram-бот командасымен
Чатты @QutPayBot-та ұйымға байланыстырыңыз (код кабинетте: Баптау → Telegram-бот), сосын былай жазыңыз:
/invoice 5000 77001234567 Консультация
Шот клиенттің Kaspi қосымшасына кетеді. Бот нөмірді қалай жазсаңыз да таниды: 8 700 123 45 67, +77001234567. /invoice орнына /шот не /счёт деп жазуға да болады. Боттың барлық командасы.
Тізіммен: кабинетте CSV, API-де bulk
Счёттар бөлімінде «Топтап (CSV)» батырмасы бар: сома;телефон;сипаттама;тапсырыс № түріндегі жолдарды қойыңыз (бөлгіш — ; не табуляция), бір ретте 200 жолға дейін. Телефоны жоқ жол QR шот болып жасалады.
5000;77011234567;Абонемент, қараша;M-101
5000;87017654321;Абонемент, қараша;M-102
API-де мұны POST /api/v1/invoices/bulk істейді: бір сұраныста 100 шотқа дейін, әрқайсысы бөлек тексеріледі, жауап 207 кодымен әр жолдың нәтижесін қайтарады. Бір нөмірдегі қате қалғандарын тоқтатпайды. Топтап шот жасау.
API арқылы
API арқылы Kaspi шоты — kind: "phone" бар бір сұраныс:
curl -X POST https://api.qut.kz/api/v1/invoices \
-H 'X-API-Key: qp_live_…' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: order-1001' \
-d '{
"amount": 2500,
"kind": "phone",
"description": "Тапсырыс №1001",
"externalOrderId": "1001",
"customer": { "phone": "77011234567" }
}'
Жауапта HTTP 201: id (inv_…), status: "pending", payUrl және expiresAt. Телефонға шоттың да payUrl-ы бар: клиент хабарламаны байқамай қалса, сілтемені бөлек жіберуге болады. Idempotency-Key қос шоттан сақтайды: сол кілтпен қайта жіберсеңіз, екінші шот жасалмай, сол шот қайтады.
Телефонға шоттың ережелері:
- сома — тек бүтін теңге, тиын жазсаңыз
amount_must_be_whole_tengeқатесі келеді; - сипаттама — 60 таңбаға дейін;
- нөмір —
77011234567;+7 701 123 45 67пен87011234567түрінде жазылғанын API өзі осы пішімге келтіреді; - нөмір Kaspi клиенті болмаса,
422 kaspi_customer_not_foundкеледі — сол нөмірге қайталамаңыз, клиентке QR не сілтеме беріңіз.
Барлық өріс пен қате: шот жасау, сайтқа интеграция, OpenAPI — api.qut.kz/docs. Дайын SDK: Node.js, PHP, Python. Salebot-тағы бот үшін — бөлек нұсқаулық, есеп жүйесі үшін — Kaspi және 1С.
Төлемді автоматты тексеру
Төлем түскенін үш жолмен білесіз, оларды қатар қолдануға болады.
Webhook
Адресті кабинетте жазасыз: Интеграциялар → webhook. Клиент төлеген соң Qut Pay сол адреске invoice.paid оқиғасымен POST жібереді — іс жүзінде 5 секунд ішінде:
{
"event": "invoice.paid",
"invoice": {
"id": "inv_…",
"externalOrderId": "1001",
"status": "paid",
"amount": 2500,
"paidAt": "…"
},
"sentAt": "…"
}
Әр сұраныс қолтаңбамен келеді. Тақырыптарда X-Webhook-Timestamp пен X-Webhook-Signature бар:
X-Webhook-Signature = "sha256=" + hex( HMAC-SHA256( secret, timestamp + "." + rawBody ) )
Қолтаңбаны сұраныстың өңделмеген денесімен, JSON-ға айналдырмай тұрып тексеріңіз, 5 минуттан ескі сұранысты қабылдамаңыз. Алдымен 2xx деп жауап беріп, тапсырысты содан кейін өңдеңіз: қате не таймаут болса, жеткізу 11 ретке дейін қайталанады, сондықтан бір (invoice.id, status) жұбы бір-ақ рет өңделсін. Құпия кілт (secret) адресті қосқанда бір рет қана көрсетіледі. Live режимде адрес — тек https, нақты доменде, паролмен жабылмаған. Webhook баптау, қолтаңбаны тексеру: Express, Laravel, Django мысалдары.
Күйін сұрау
Webhook қабылдайтын, сырттан ашық сервер болмаса, күйін өзіңіз сұрайсыз:
curl https://api.qut.kz/api/v1/invoices/inv_… -H 'X-API-Key: qp_live_…'
paid болса — төленді. 3–5 секундтан жиі сұраудың мәні жоқ: жауап тезірек келмейді, ал жиі сұраныс жиілік шегіне тіреледі. Клиент қасыңызда тұрып күтетін жерде екеуін қатар ұстаңыз: webhook — негізгі жол, сұрау — сақтандырғыш. Webhook па, күйді сұрау ма.
Telegram хабары
@QutPayBot-қа байланысқан чатқа «✅ ТӨЛЕНДІ» хабары келеді: сомасы, сипаттамасы, тапсырыс нөмірі, клиент деректері және чек нөмірі. Оған интеграция керек емес — шотты менеджер қолмен жіберсе, осының өзі жетеді. Сол чатқа қайтару, мерзімі өткен шот және кассир байланысы үзілгені туралы да хабар келеді.
QR ма, телефонға шот па
| Телефонға шот | QR шот | |
|---|---|---|
| Клиентке қалай жетеді | Kaspi қосымшасындағы хабарлама | Экрандағы QR не payUrl сілтемесі |
| Клиент туралы не білу керек | Телефон нөмірін | Ештеңе |
| Клиенттің Kaspi қосымшасы | Міндетті | Міндетті емес: сілтеме браузерде де ашылады |
| Сома | Тек бүтін теңге | Ең көбі 2 ондық белгі |
| Сипаттама | 60 таңбаға дейін | 100 таңбаға дейін |
| Төлемді қанша күтеді | QR-дан әлдеқайда ұзақ | Сканерлеу терезесі — шамамен 3 минут |
| Қай жерде ыңғайлы | Қоңыраудан кейін, хат алмасқанда, ай сайынғы шот, база бойынша тарату | Дүкендегі экран, сайт, витрина, вендинг |
Қысқа ереже: клиент экраныңызға қарап тұрса — QR, алыста болса және нөмірі белгілі болса — телефонға шот. Толық салыстыру.
Шоттың мерзімі және шектеулер
Шоттың мерзімі expiresAt өрісінде келеді — кодқа тұрақты сан қылып жазбай, сол өрістен алыңыз: мерзімді Kaspi белгілейді. Телефонға шот клиенттің қосымшасында QR терезесінен әлдеқайда ұзақ тұрады, сондықтан клиент бірден емес, кейінірек те төлей алады. Мерзімі өткенде шот expired күйіне өтіп, invoice.expired келеді; оны ұзарту мүмкін емес — жаңа шот жасайсыз, сол externalOrderId-ді қайта беруге болады.
Жабылған шотқа да ақша кешігіп түсуі мүмкін: клиент соңғы сәтте растаса, invoice.paid оқиғасы late: true белгісімен келеді. Бұл — нақты ақша: тапсырысты орындаңыз не ақшаны қайтарыңыз. Шоттың мерзімі.
- Тарифтің айлық лимитіне тек төленген шоттар саналады: төленбеген, мерзімі өткен, болдырылмаған шоттар есепке кірмейді.
- Бөлек күндік қорғаныс шегі бүгін жасалған шоттарды санайды: «Тегін»-де — 50, «Бастау»-да — 200. Тарифтер мен лимиттер.
- API-ге сұраныс жиілігі — бір кілтке минутына 200 жазу және 600 оқу.
Қайтару
Төленген шот бойынша ақшаны қайтаруға болады:
- кабинетте: Счёттар → шотты ашыңыз → Қайтару; ішінара қайтару үшін аз соманы жазасыз;
- API арқылы:
POST /api/v1/invoices/{id}/refund;amountбермесеңіз — толық қайтару, берсеңіз — ішінара. Кілттеrefunds:writeқұқығы болуы керек.
curl -X POST https://api.qut.kz/api/v1/invoices/inv_…/refund \
-H 'X-API-Key: qp_live_…' \
-H 'Content-Type: application/json' \
-d '{"amount": 1000, "reason": "Клиент бас тартты"}'
Ақша сіздің Kaspi Pay шотыңыздан қайтарылады: қайтаруды Kaspi өзі орындайды, оны қанша уақытқа дейін жасауға болатынын да Kaspi белгілейді. Қайтарудан кейін invoice.refunded не invoice.partially_refunded оқиғасы және Telegram хабары келеді. Telegram-бот арқылы қайтару жасалмайды — бұл әдейі солай. refund_unknown жауабы келсе, сұранысты қайталамаңыз: алдымен шоттың күйін оқыңыз. Әлі төленбеген шотқа қайтару жасалмайды, оны жабасыз: POST /api/v1/invoices/{id}/cancel, кабинеттегі Болдырмау батырмасы не боттағы /cancel командасы. Қайтару API.
Алдымен sandbox
qp_test_… кілті нақты ақшасыз жұмыс істейді: шот жасалады, төлемді өзіңіз қоясыз (POST /api/v1/invoices/{id}/simulate, денесі {"status":"paid"}), ал webhook шынымен келеді. Sandbox-та 77000000404 нөмірі kaspi_customer_not_found қайтарады — «нөмір Kaspi-де жоқ» тармағын осылай тексересіз. Sandbox-та төлемді имитациялау.
Жиі қойылатын сұрақтар
Сайтсыз, бағдарламашысыз нөмірге шот жіберуге бола ма?
Иә. Телефонға шотты кабинеттен («Счёттар» бөлімі), Telegram-ботта /invoice 5000 77011234567 командасымен немесе CSV тізімімен жібересіз. API шот өздігінен жасалуы керек болғанда ғана қажет: сайттан, CRM-нен, боттан не 1С-тен.
Клиент төлегенін қалай білемін?
Хабар өзі келеді: HMAC-SHA256 қолтаңбалы invoice.paid webhook-ы төлемнен кейін әдетте 5 секунд ішінде серверіңізге жетеді, күйін GET /api/v1/invoices/{id} сұранысымен білуге болады, ал байланысқан Telegram чатқа төлем туралы хабар түседі. Барлық шот пен оның күйі кабинетте көрінеді.
Клиентте Kaspi қосымшасы жоқ болса ше?
Нөмір Kaspi клиенті болмаса, API бірден kaspi_customer_not_found деп жауап береді — сол нөмірге қайталаудың қажеті жоқ. Ал ол нөмірде Kaspi қосымшасы болмаса, шот pending күйінде тұрып, мерзімі өтеді. Екі жағдайда да QR шот жасап, клиентке payUrl сілтемесін жіберіңіз: ол браузерде де ашылады.
Ақша клиенттің келісімінсіз шешіліп кете ме?
Жоқ. Әр шотты клиент Kaspi қосымшасында өзі ашып, өзі растайды. Жазылым бойынша ай сайынғы шоттар да кесте бойынша жасалатын жаңа шоттар, әрқайсысын клиент өзі төлейді.
Нөмірді қандай пішімде жазу керек?
77011234567. API +7 701 123 45 67 және 87011234567 түріндегі нөмірді де қабылдап, осы пішімге келтіреді. Telegram-бот нөмірді қалай жазсаңыз да таниды.
Бұл қанша тұрады?
Qut Pay — төлемнен пайыз алмайтын тұрақты жазылым: «Тегін» тариф — айына 20 төлем, мерзімсіз; «Бастау» — айына 4 990 ₸, 800 төлем. Лимитке тек төленген шоттар саналады. Kaspi өз комиссиясын өз шартымен бөлек ұстайды, бізсіз де солай. Толығырақ: тарифтер.
Тақырып бойынша тағы: Kaspi Pay API сайтқа, Kaspi және 1С, Telegram мен WhatsApp-та Kaspi төлем, Kaspi сервистерін салыстыру.
Алғашқы шотты нөмірге жіберіңіз
Тіркеліп, Kaspi Pay кассирін қосыңыз да, бүкіл сценарийді sandbox-та тексеріңіз.
Qut Pay — тәуелсіз сервис, Kaspi-дің серіктесі емес және «Kaspi Bank» АҚ-мен аффилирленбеген. Ол сіздің Kaspi Pay-дегі «Кассир» рөлі арқылы жұмыс істейді, ақша тікелей Kaspi Pay шотыңызға түседі. Kaspi Pay бизнес-аккаунты (ЖК не ЖШС) керек. Тағы қараңыз: сайтқа Kaspi API, Telegram мен WhatsApp-та Kaspi шоты, Kaspi және 1С, Salebot-тан Kaspi шоты, тарифтер, сенім орталығы.