Қысқаша
Біз Kaspi-ден счёттың күйін сұрап отырамыз, ал ол сұрау бірден емес, кезекпен жүреді. Сондықтан клиент төлеген сәт пен сіздің жүйеңіз «төленді» деп білген сәттің арасында әрқашан шағын кідіріс болады. Іс жүзінде webhook әдетте бес секунд ішінде келеді. Егер сіздің сценарийіңіз кідіріске сезімтал болса (турникет, шлагбаум, вендинг, тікелей эфир), webhook күтумен қатар GET /api/v1/invoices/{id} сұрауын да жүргізіңіз — қайсысы бірінші келсе, соны қабылдаңыз.
Тексеру қалай жүреді
Poller — счёттардың күйін Kaspi-ден сұрап отыратын ішкі процесс. Ол әр 3 секунд сайын бір айналым жасайды, бірақ бір айналымда барлық ашық счётты сұрамайды: счёттың жасына қарай жиілік бөлінеді.
| Счёттың жасы | Қаншалықты жиі тексеріледі |
|---|---|
| 3 минуттан жас | Әр айналымда, яғни ең жиі |
| 3 минуттан 30 минутқа дейін | Шамамен 20 секунд сайын |
| 30 минуттан ескі | Шамамен 90 секунд сайын |
Кезек ең жаңа счёттан басталады. Логикасы қарапайым: жаңа ғана шығарылған счёт дәл қазір төленуі ықтимал, ал бір сағат бұрын шығарылған счёт әдетте төленбей қалғаны. Сондықтан жаңа счёттар ең жылдам расталады.
Бұдан шығатын практикалық қорытынды: клиентті счёт шыққан бойда төлеуге бағыттасаңыз, растау да ең жылдам болады. Егер счёт шығарып қойып, клиент оны жарты сағаттан кейін төлесе, растау 90 секундқа дейін кешігуі мүмкін.
Іс жүзінде қанша уақыт кетеді
Әдеттегі жағдайда клиент QR-ды сканерлеп, Kaspi-де растағаннан кейін сіздің webhook адресіңізге invoice.paid бес секунд шамасында келеді. Бұл — біздің бақылауымыздағы орташа мән, кепілдік емес: Kaspi жағындағы жүктеме мен желі жағдайы оны ұзартуы мүмкін.
Маңызды бір нәрсе. Kaspi payload-та төлемнің дәл уақытын бермейді. Яғни «клиент растаған сәттен бізге жеткенге дейін қанша уақыт өтті» деген аралықты Kaspi деректерінен өлшеу мүмкін емес — ондай өріс жоқ. Кез келген «нақты кідіріс» есебі болжам болып шығады. Өз жағыңызда өлшеуге болатыны — счёт жасалған сәт пен webhook келген сәттің арасы, ал оның ішінде клиенттің ойланып тұрған уақыты да бар.
Кідіріске сезімтал сценарий
Егер төлем расталған бойда физикалық әрекет болуы керек болса — шлагбаум ашылады, автомат тауар береді, эфирде тапсырыс бекітіледі — екі арнаны қатар жүргізіңіз:
- Webhook — негізгі арна. Күйдің өзгергенін бізден сіз сұрамай-ақ білесіз.
GET /api/v1/invoices/{id}— қосалқы арна. Счёт шыққан соң алғашқы 1-2 минут бойы бірнеше секунд сайын сұрап тұрасыз.
Қайсысы бірінші «paid» десе, соны қабылдап, әрекетті орындайсыз. Екіншісі кейін келгенде қайта орындамау үшін өңдеуіңіз идемпотентті болуы керек: (счёт id, күй) жұбын журналға жазып, сол жұп бұрын өңделген болса, ештеңе істемеңіз.
Сұрауды мәңгі жүргізбеңіз. Ақылға қонымды тәртіп: алғашқы 2 минут — 2-3 секунд сайын, одан кейін сиретіп, счёттың expiresAt мерзімі өткенде тоқтату. Тым жиі сұрасаңыз rate_limited немесе request_rate_limited қатесін аласыз.
Не кідіріс емес
Барлық кешігу poller-дің кінәсі емес. Мыналарды алдымен алып тастаңыз:
| Белгі | Шынымен не болып жатыр |
|---|---|
| Счёт мүлде paid болмайды | Клиент әлі төлемеген немесе тест режиміндесіз |
| Webhook мүлде келмейді, бірақ кабинетте счёт paid | Webhook жағында мәселе: Webhook келмей жатыр |
| Күй кабинетте бірден, ал сіздің жүйеңізде кеш | Сіздің кезегіңіз бітеліп тұр, өз өңдеуіңізді тексеріңіз |
| Счёт жабылған соң ақша келді | Бұл кеш төлем, late: true белгісімен келеді |
| Ақша Kaspi шотында көрінбейді | Бұл басқа мәселе: Ақша қашан және қайда түседі |
Кеш төлем туралы бөлек ескерту: cancelled немесе expired счётқа ақша кешігіп келуі мүмкін, сонда invoice.paid оқиғасы late: true белгісімен кейін де келеді. Ондай счётты елемеңіз деп жаппаңыз — не қызметті беріңіз, не ақшаны қайтарыңыз.
Sandbox-та кідіріс болмайды
Sandbox режимінде Kaspi шақырылмайды, күйді сіз POST /api/v1/invoices/{id}/simulate арқылы өзіңіз қоясыз. Сондықтан ол жерде растау лезде болады. Бұл — тест ортасының ерекшелігі, нақты режимдегі жылдамдықты sandbox бойынша бағаламаңыз.
Жиі қойылатын сұрақтар
Poller жиілігін өзгертуге бола ма? Жоқ, ол бәріне ортақ және счёттың жасына қарай өзі реттеледі.
Неге бір счёт 3 секундта, екіншісі 40 секундта расталды? Екеуінің жасы әртүрлі болған. Жаңа счёт әр айналымда тексеріледі, жарты сағаттан ескісі — 90 секунд сайын.
Сұрауды жиілетсем, растау жылдамдай ма? Біраз, иә: сіздің GET /invoices/{id} сұрауыңыз poller кезегінен тәуелсіз. Бірақ шектен шықпаңыз, әйтпесе 429 аласыз. Екі арнаны қатар жүргізу — ең дұрыс жолы.
Кідірісті нақты секундпен өлшеп бере аласыз ба? Kaspi төлем уақытын бермегендіктен, «клиент растағаннан бізге дейін» деген аралықты ешкім өлшей алмайды. Өлшеуге болатыны — счёт жасалғаннан webhook келгенге дейінгі уақыт.
Клиентке «күте тұрыңыз» деп не көрсетейін? Счёт жасалған соң күту экранын көрсетіп, фонда күйді сұрап тұрыңыз. Растау келгенде экранды ауыстырыңыз. Клиентке техникалық қате мәтіндерін көрсетпеңіз.