← qut.kz

Kaspi шотын нөмірге жіберу

Qut Pay-де Kaspi шотын нөмірге жіберу дегеніміз — «телефонға» түріндегі шот: сомасы мен клиенттің нөмірін жазасыз, шот хабарлама болып тікелей клиенттің Kaspi қосымшасына түседі, клиент оны ашып, төлемді растайды. Мұндай шотты кабинеттен, Telegram-бот командасымен, CSV тізімімен немесе API-ге бір сұраныспен жібересіз. Төлем түскенін сізге жүйенің өзі хабарлайды: HMAC-SHA256 қолтаңбалы invoice.paid webhook-ы, күйін сұрау немесе Telegram хабары арқылы. Ақша тікелей сіздің Kaspi Pay шотыңызға түседі.

Qut Pay сіздің өз Kaspi Pay-іңіздегі «Кассир» рөлі арқылы жұмыс істейді: бөлек нөмірмен кассир қосып, оны кабинетте жалғайсыз — 15 минутта қалай қосу керек. Kaspi Pay бизнес-аккаунты (ЖК немесе ЖШС) керек.

Клиент не көреді

Толығы: клиент не көреді.

Клиентке 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 қос шоттан сақтайды: сол кілтпен қайта жіберсеңіз, екінші шот жасалмай, сол шот қайтады.

Телефонға шоттың ережелері:

Барлық өріс пен қате: шот жасау, сайтқа интеграция, 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 белгісімен келеді. Бұл — нақты ақша: тапсырысты орындаңыз не ақшаны қайтарыңыз. Шоттың мерзімі.

Қайтару

Төленген шот бойынша ақшаны қайтаруға болады:

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-та тексеріңіз.

Тіркелу API нұсқаулығы

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

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