Қысқаша
Төмендегі он екі тармақты ретімен өтіңіз. Әрқайсысының қасында не басу керек және қалай тексеру керек жазылған. Бәрі жасыл болса, нақты режимге қауіпсіз көшесіз.
Ең жиі кездесетін екі қате: кілт qp_test_… күйінде қалып қою және webhook адресінің live үшін қосылмауы. Тізімнің 2 және 3-тармағы дәл соған арналған.
1. Кассир белсенді
Не басу керек: Кабинет → Kaspi бөлімі. Байланыстың күйі «белсенді» болуы керек.
Қалай тексеру керек: күйі сұр немесе «үзілген» болса, қайта байланыстырыңыз — SMS коды кассир нөміріне келеді, бүкіл процесс бір терезеде, шамамен он минут.
Есте сақтаңыз: Kaspi бір кассирге бір ғана белсенді құрылғыға рұқсат береді. Байланыстырған соң ол нөмірмен Kaspi Pay қосымшасына кірмеңіз — сессия үзіледі.
Мәселе болса: Кассир байланысы үзілді, Кассир қосылмай жатыр.
2. Кілт live
Не басу керек: Кабинет → Интеграциялар → API кілттер. qp_live_… кілтін жасаңыз және оны серверде .env файлында ауыстырыңыз.
Қалай тексеру керек: серверде echo немесе журнал арқылы кілттің алғашқы жеті таңбасын қараңыз: qp_live_ болуы керек, qp_test_ емес.
Бұл ең жиі ұмытылатын қадам. Кілт test күйінде қалса, счёттар жасалады, бірақ клиентке нақты төлем келмейді. Белгілері: Тест режимі қосулы қалып қойған.
3. Webhook жария және https
Не басу керек: Кабинет → Интеграциялар → webhook адресі. Адрес тұрақты доменде және https болуы керек.
Қалай тексеру керек: сыртқы желіден (телефонның мобильді интернетінен, Wi-Fi-дан емес) адресіңізге POST жіберіп көріңіз. Жауап келуі керек. Егер:
- IP-мекенжай жазсаңыз —
webhook_url_requires_domain http://жазсаңыз —webhook_url_requires_https- Туннель адресі болса —
webhook_url_tunnel_forbidden
Адрес авторизациясыз ашық болуы керек: Basic Auth, IP-сүзгі немесе Cloudflare-дің «бот қорғанысы» webhook-ты бөгейді. Қайта бағыттау да ұсталмайды (тек сол адрестің өзіне 307/308 болмаса).
Мәселе болса: Webhook келмей жатыр.
4. Қолтаңба тексеріліп жатыр
Не істеу керек: кодыңызда X-Webhook-Signature тексерілетініне көз жеткізіңіз: sha256= + HMAC-SHA256(secret, timestamp + "." + rawBody).
Қалай тексеру керек: әдейі бұзылған қолтаңбамен өз адресіңізге сұрау жіберіңіз. Сервер 401 қайтарып, тапсырысты өзгертпеуі керек. Егер бұзылған қолтаңбамен де тапсырыс «төленді» болып кетсе — тексеру жоқ немесе жұмыс істемей тұр.
Қосымша: X-Webhook-Timestamp 5 минуттан ескі болса қабылдамау керек. Толығы: Webhook қауіпсіздігі.
5. Идемпоттылық бар
Не істеу керек: екі жерде.
- Счёт жасағанда —
Idempotency-Keyтақырыбын жіберіңіз. Желі үзіліп, сұрау қайталанса, жаңа счёт жасалмайды - Webhook өңдегенде —
(invoice.id, status)жұбы бойынша. Сол жұп екінші рет келсе, тапсырысты қайта өңдемеңіз
Қалай тексеру керек: sandbox-та бір Idempotency-Key мәнімен екі рет счёт жасаңыз — екіншісінде HTTP 200 және idempotentReplay: true келуі керек. Webhook үшін: бір денені екі рет өз адресіңізге жіберіңіз, екіншісінде тауар екінші рет жөнелтілмеуі керек.
Толығы: Идемпоттылық.
6. Кеш төлемге дайын
Не істеу керек: invoice.paid оқиғасында late: true белгісін тексеретін тармақ жазыңыз. Бұл — жабылған (cancelled немесе expired) счётқа ақша кешігіп келгені.
Қалай тексеру керек: sandbox-та счётты cancel қылып, сосын simulate {"status":"paid"} жіберіңіз. late: true келеді. Жүйеңіз не істейді?
Екі жол бар, алдын ала таңдаңыз: қызметті беру немесе ақшаны қайтару. Үшінші жол — қолмен қарау үшін хабарлама жіберу. Толығы: Кеш келген төлем.
7. Қате өңдеу бар
Не істеу керек: интеграцияны message мәтініне емес, error кодына қарап жазыңыз. Кемінде мына кодтар өңделсін:
| Код | Не істеу керек |
|---|---|
kaspi_session_expired | Қолдау қызметіне ескерту жіберу, счёт жасауды тоқтату |
tariff_limit_reached | Ескерту жіберу, тарифті көтеру |
tariff_daily_burst | Кодта цикл бар ма, тексеру |
rate_limited, 429 | Retry-After тақырыбын қарап, күтіп қайталау |
502, 503 | Өсіп отыратын кідіріспен қайталау (1, 2, 4, 8 секунд) |
refund_unknown | Қайталамау, счёт күйін оқу |
Қалай тексеру керек: sandbox-та әдейі бұзылған сұраулар жіберіп көріңіз. Барлық кодтар: Қателер каталогы.
8. Журнал жүргізіледі
Не істеу керек: әр счёт жасауды және әр келген webhook-ты жазыңыз: уақыты, invoice.id, externalOrderId, күйі, HTTP коды, X-Webhook-Delivery.
Журналға жазбаңыз: API кілттің өзін, webhook құпиясын.
Қалай тексеру керек: сынақ төлемін жасап, журналда қалғанын қараңыз. Журналсыз бірінші мәселені шеше алмайсыз.
9. Тариф белсенді және лимит жетеді
Не басу керек: Кабинет → Тариф. Тариф белсенді ме, айлық лимит айына жоспарланған счёт санына жете ме?
| Тариф | Айына счёт | Тәуліктік қорғаныс |
|---|---|---|
| Бастау | 800 | 200 |
| Бизнес | 4 000 | 1 500 |
| Про | 15 000 | 5 000 |
Тәуліктік сан — бизнес лимиті емес, циклге түскен интеграциядан қорғаныс. Егер тәулігіне 200-ден көп счёт жоспарласаңыз, тарифті сәйкесінше таңдаңыз.
Сынақ мерзімі 7 күн, тәулігіне 50 счёт және бірінші нақты счёттан басталады. Толығы: Тарифтер және лимиттер.
10. Telegram ескертуі қосулы
Не басу керек: Кабинет → Баптау → Telegram байланыстыру коды. Ботты байланыстырыңыз.
Неге керек: кассир байланысы үзілгенін журналдан емес, хабарламадан бірден білесіз. Түнде байланыс үзілсе, таңертең емес, сол сәтте көресіз.
Қосу реті: Telegram ботын қосу.
11. Қайтару реті ойластырылған
Не істеу керек: мына сұрақтарға жауабыңыз болсын.
- Қайтаруды кім жасайды: кабинеттен қолмен бе, әлде сіздің жүйеңіз API арқылы ма?
- Ішінара қайтару керек пе?
refund_unknownнемесеrefund_pending_unknownкелсе не істейсіз? (Жауабы: қайталамайсыз, счёт күйін оқисыз)
Қалай тексеру керек: sandbox-та толық және ішінара қайтаруды өткізіңіз. Толығы: Қайтару API, Екі рет қайтарып жіберуден сақтану.
12. Бірінші нақты төлем — кіші сомамен
Не істеу керек: live режимге көшкен соң, өз телефоныңыздан ең кіші сомаға (мысалы 100 ₸) счёт жасап, нақты төлеңіз.
Не тексеріледі: бірден бәрі — кілт, кассир, QR, webhook, сіздің жүйеңіздегі күй өзгерісі, Kaspi шотына ақшаның түсуі.
Содан кейін сол счётты қайтарыңыз — қайтару жолы да тексерілді. Бұл бес минуттық әрекет бірінші нақты клиентте шығатын мәселелерді алдын ала табады.
Өтпесе: Нақты режимге көштім, бірақ істемей жатыр.
Қысқаша тізім
Бір көзбен шолу үшін:
- Кассир белсенді
- Кілт
qp_live_… - Webhook жария,
https, тұрақты домен - Қолтаңба тексеріледі, timestamp 5 минут
Idempotency-Keyжіберіледі, webhook идемпотенттіlate: trueөңделеді- Қате кодтары өңделеді
- Журнал бар, кілтсіз
- Тариф белсенді, лимит жетеді
- Telegram ескертуі қосулы
- Қайтару реті белгілі
- Бірінші нақты төлем кіші сомамен өтті
Жиі қойылатын сұрақтар
Режимді ауыстырғанда sandbox счёттарым не болады? Олар орнында қалады, бірақ live тізімде көрінбейді. Лимитке де кірмейді.
Sandbox кілтім live режимде жұмыс істей ме? Жоқ. Режим мен кілт сәйкес келуі керек, әйтпесе 401 аласыз.
Қай кезде тарифті төлеу керек? Сынақ мерзімі бірінші live счёттан басталып, 7 күн жүреді. Сол уақытта таңдап, төлей саласыз: Тарифті қалай төлеу керек.
Тізімнің қай тармағын өткізіп жіберуге болады? Ешқайсысын. Бірақ ретін өзгертуге болады — 12-тармақ соңында тұруы керек, өйткені ол қалғандарының бәрін бір уақытта тексереді.