# Төлем баяу расталады — неге және не істеу керек

> Клиент төледі, бірақ счёт бірден paid болмайды. Мұнда тексеру жиілігі жасына қарай қалай өзгеретіні, іс жүзіндегі уақыт және кідіріске сезімтал сценарийде не істеу керегі жазылған.

## Қысқаша

Біз 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 келген сәттің арасы, ал оның ішінде клиенттің ойланып тұрған уақыты да бар.

## Кідіріске сезімтал сценарий

Егер төлем расталған бойда физикалық әрекет болуы керек болса — шлагбаум ашылады, автомат тауар береді, эфирде тапсырыс бекітіледі — екі арнаны қатар жүргізіңіз:

1. **Webhook** — негізгі арна. Күйдің өзгергенін бізден сіз сұрамай-ақ білесіз.
2. **`GET /api/v1/invoices/{id}`** — қосалқы арна. Счёт шыққан соң алғашқы 1-2 минут бойы бірнеше секунд сайын сұрап тұрасыз.

Қайсысы бірінші «paid» десе, соны қабылдап, әрекетті орындайсыз. Екіншісі кейін келгенде қайта орындамау үшін өңдеуіңіз идемпотентті болуы керек: `(счёт id, күй)` жұбын журналға жазып, сол жұп бұрын өңделген болса, ештеңе істемеңіз.

Сұрауды мәңгі жүргізбеңіз. Ақылға қонымды тәртіп: алғашқы 2 минут — 2-3 секунд сайын, одан кейін сиретіп, счёттың `expiresAt` мерзімі өткенде тоқтату. Тым жиі сұрасаңыз `rate_limited` немесе `request_rate_limited` қатесін аласыз.

## Не кідіріс емес

Барлық кешігу poller-дің кінәсі емес. Мыналарды алдымен алып тастаңыз:

| Белгі | Шынымен не болып жатыр |
|---|---|
| Счёт мүлде paid болмайды | Клиент әлі төлемеген немесе тест режиміндесіз |
| Webhook мүлде келмейді, бірақ кабинетте счёт paid | Webhook жағында мәселе: [Webhook келмей жатыр](/kb/webhook-not-arriving) |
| Күй кабинетте бірден, ал сіздің жүйеңізде кеш | Сіздің кезегіңіз бітеліп тұр, өз өңдеуіңізді тексеріңіз |
| Счёт жабылған соң ақша келді | Бұл кеш төлем, `late: true` белгісімен келеді |
| Ақша Kaspi шотында көрінбейді | Бұл басқа мәселе: [Ақша қашан және қайда түседі](/kb/money-arrival) |

Кеш төлем туралы бөлек ескерту: `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 келгенге дейінгі уақыт.

**Клиентке «күте тұрыңыз» деп не көрсетейін?** Счёт жасалған соң күту экранын көрсетіп, фонда күйді сұрап тұрыңыз. Растау келгенде экранды ауыстырыңыз. Клиентке техникалық қате мәтіндерін көрсетпеңіз.