Қысқаша
Дүкенде, шеберханада, кофеханада жұмыс реті қарапайым: кассир соманы енгізеді, экранда QR пайда болады, клиент Kaspi қосымшасымен сканерлейді, төлем расталған соң кассир экраннан «төленді» дегенді көреді. QR әр төлемге жаңадан жасалады — бұл динамикалық QR, сканерлеу терезесі шектеулі. Терезенің нақты уақытын өзіңіз белгілей алмайсыз, оны expiresAt өрісінен оқисыз.
Сценарий
Кассада кезек тұр. Клиент 4 500 ₸ төлеуі керек. Терминал жоқ немесе терминалға қосымша жол керек.
Кассир планшеттен немесе компьютерден соманы енгізеді, экранда QR шығады, клиент телефонын алып сканерлейді, Kaspi қосымшасында соманы көреді, растайды. Бірнеше секундтан кейін кассир экранында «Төленді» жазуы пайда болады. Ақша тіке дүкеннің Kaspi шотына түседі.
Жұмыс схемасы қадамдап
- Кассир соманы енгізеді — кабинеттен, өз кассалық бағдарламаңыздан немесе Telegram бот арқылы.
- Счёт жасалады.
POST /api/v1/invoices,kind: "qr"(әдепкі). ЖауаптаqrUrl,qrImageUrl,deepLink,payUrlжәнеexpiresAtкеледі. - Экранда QR көрсетіледі. Планшет, монитор, чек принтері — қайсысы ыңғайлы болса.
- Клиент сканерлейді Kaspi қосымшасымен, соманы көреді, растайды.
- Күйі жаңарады. Webhook
invoice.paidкеледі немесе кассалық бетіңіз күйді сұрап тұрады. Іс жүзінде бұл клиент растағаннан кейін бірнеше секунд алады. - Кассир растауды көреді де, тауарды береді.
Қандай API әдісі керек
| Не істейді | Әдіс |
|---|---|
| QR счёт жасау | POST /api/v1/invoices, kind: "qr" |
| Телефонға счёт | POST /api/v1/invoices, kind: "phone", customer.phone |
| Күйін сұрау | GET /api/v1/invoices/{id} |
| Клиент ойын өзгертсе | POST /api/v1/invoices/{id}/cancel |
| Тауарды қайтарса | POST /api/v1/invoices/{id}/refund |
| Төлем туралы хабар | Webhook invoice.paid |
Кассада күйді тез білу маңызды, сондықтан webhook пен күйді сұрауды қатар жүргізген дұрыс: webhook негізгі, ал кассир экраны бірнеше секунд сайын GET /invoices/{id} сұрап отырады. Толығы: Webhook пен күйді сұрау.
Сканерлеу терезесі шектеулі
Бұл кассада ең жиі кездесетін мәселе. QR мәңгі тұрмайды — оның сканерлеу терезесі бар, оны Kaspi белгілейді. Терезе біткенде клиент сканерлегенде «кейінірек көріңіз» деген хабар шығады.
Не істеу керек:
- Уақытты
expiresAtөрісінен алыңыз. Кодқа тұрақты сан жазып қоймаңыз — терезе Kaspi жағында анықталады. - Экранда кері санақ көрсетіңіз. Кассир де, клиент те қанша уақыт қалғанын көрсін.
- Терезе біткенде QR-ды жаңартыңыз. Ескі счётты
cancelарқылы жауып, жаңа счёт жасайсыз. Клиент қайта сканерлейді. - QR суретін алдын ала басып қоймаңыз. Динамикалық QR әр төлемге жаңадан жасалады.
Егер клиент сканерлеп үлгермей қалса: QR «кейінірек көріңіз» деп тұр.
Қашан QR, қашан телефонға счёт
| Жағдай | Не таңдау керек |
|---|---|
| Клиент кассаның алдында тұр | QR — жылдам, телефон нөмірі керек емес |
| Клиент экранды көре алмайды (терезе арқылы, дәліз, қойма) | Телефонға счёт |
| Телефонның камерасы істемейді, экран жарқырап тұр | Телефонға счёт |
| Клиент тапсырысты алдын ала қоңыраумен берді | Телефонға счёт |
| Клиентте Kaspi қосымшасы жоқ | QR немесе payUrl сілтемесі |
| Сомада тиын бар | QR (телефонға счётта бүтін теңге керек) |
| Сипаттама ұзын | QR — 100 таңба, телефонға счёт — 60 |
Телефонға счёт жібергенде customer.phone дұрыс пішімде болуы керек: 7XXXXXXXXXX. Айырмашылығы толық: QR счёт пен телефонға счёт.
Кодсыз нұсқасы бар ма
Бар, үшеуі:
- Кабинеттен счёт. Кабинетке кіресіз, Счёттар бөлімінен счёт жасайсыз, экранда QR шығады. Кассир планшеттен осылай жұмыс істей береді.
- Telegram бот.
/invoiceкомандасымен счёт жасайсыз,/todayкүнделікті қорытындыны,/lastсоңғы счёттарды көрсетеді. Кассаға компьютер орнатудың қажеті жоқ — телефоннан жұмыс істейді. - Төлем сілтемесі. Тұрақты сомалы немесе ашық сомалы сілтеме. Оның QR-ын басып, кассада қойып қоюға болады, бірақ бұл — тұрақты сілтеме, сома клиенттен сұралады.
Толық автоматтандыру (кассалық бағдарламаға қосу) үшін API керек.
Бірнеше нүкте болса
Әр нүктеге бөлек API кілт жасаңыз. Себебі:
- есепте төлемнің қай нүктеден келгені көрінеді;
- бір кілт сыртқа шығып кетсе, тек соны жойып, қалғанын тимейсіз;
- кілтті нақты кассирге байлауға болады — сонда ол басқа кассирдің счёттарын көрмейді (бөтен счётқа 404 қайтады).
Айлық лимит ұйымға ортақ болып қалады, ол нүктелерге бөлінбейді — тариф таңдағанда бүкіл нүктенің қосынды көлемін есептеңіз. Толығы: Нүктелер бойынша бөлек есеп.
Kaspi-де бірнеше кассир қосуға да болады, әрқайсысы — жеке байланыс: Бір ұйымға бірнеше кассир қосуға бола ма.
Ерекше ескертулер
- Кассир нөмірімен Kaspi Pay қосымшасына кірмеңіз. Kaspi бір кассирге бір ғана белсенді құрылғыға рұқсат береді — біреу кірсе, байланыс үзіледі де счёт жасау тоқтайды.
- Кассир нөмірі клиентке көрінеді счёт туралы хабарламада. Бұл Kaspi-дің қалыпты жұмысы, сондықтан ол нөмір жеке нөміріңіз болмағаны дұрыс.
- Интернет керек. Нүктеде байланыс үзілсе, счёт жасалмайды. Кассада қосалқы мобильді интернет болғаны жөн.
- Тәуліктік қорғанысты есте ұстаңыз. Ол бизнес лимиті емес, циклге түскен интеграциядан сақтандырғыш, бірақ кассалық бағдарлама қате жазылса соған тіреледі.
- Кеш төлем болады. Мерзімі өткен счётқа ақша кейін келсе,
invoice.paidоқиғасыlate: trueбелгісімен келеді. Ондайда тауарды беріңіз немесе ақшаны қайтарыңыз. - Алдымен sandbox-та сынаңыз.
qp_test_…кілтімен нақты Kaspi шақырылмайды, төлемді өзіңіз симуляциялайсыз.
Жиі қойылатын сұрақтар
QR-ды бір рет басып, кассаға жапсырып қоюға бола ма? Динамикалық QR — жоқ, ол әр төлемге жаңадан жасалады. Тұрақты жапсыру керек болса, төлем сілтемесінің QR-ын қолданыңыз, бірақ сонда соманы клиент енгізеді.
Клиент QR-ды сканерледі, бірақ кассир экранында әлі «төленбеді» тұр. Растау бірнеше секунд алады. Бірнеше минут өтсе, алдымен тест режимінде емес екеніңізді тексеріңіз: Клиентке төлем келмей жатыр.
Ақша қашан түседі? Тіке дүкеннің Kaspi шотына, сол сәтте. Бізде ұсталмайды.
Бір кассада екі кассирді қатар қолдануға бола ма? Иә, әр кассир жеке байланыс. Кілтті нақты кассирге байласаңыз, есеп те бөлінеді.
Интернет үзілсе не істеймін? Счёт жасау мүмкін болмайды. Қосалқы байланыс көзін дайындап қойған дұрыс.