Қысқаша
Әр счёттың өз мерзімі бар, ол expiresAt өрісінде келеді. Интеграцияңыз әрқашан осы өрісті оқысын — тұрақты сан жазып қоймаңыз, мерзімді Kaspi белгілейді және ол өзгеруі мүмкін.
Жалпы ереже: QR счёттың сканерлеу терезесі қысқа, телефонға жіберілген счёт әлдеқайда ұзақ тұрады. Мерзімі өткен счёт expired күйіне ауысады, оны «жандандыру» мүмкін емес — жаңасын жасайсыз.
Ең маңыздысы: жабылған счётқа ақша кешігіп келуі мүмкін. Ондай жағдайда invoice.paid оқиғасы late: true белгісімен келеді, оны өңдеуге дайын болыңыз.
QR счёттың терезесі
QR счёт жасалғанда Kaspi оны сканерлеуге қысқа ғана уақыт береді — бұл әдейі, QR суреті ұзақ жүрмеуі үшін. Нақты уақытты Kaspi белгілейді, біз оны жауаптағы expiresAt өрісінде қайтарамыз.
Практикалық қорытындылары:
- QR-ды алдын ала жасап қоймаңыз. Клиент касса алдында тұрғанда немесе төлем бетін ашқанда жасаңыз
- Экрандағы QR-ды терезе біткенше жаңартып отырыңыз: терезе аяқталса, жаңа счёт жасап, жаңа QR көрсетіңіз
- Счётты чатқа немесе электрондық поштаға жібермеңіз — адам ашқанша мерзімі өтіп кетеді. Оның орнына тұрақты төлем сілтемесін беріңіз
- Клиент «кейінірек көріңіз» дегенді көрсе, себебі әдетте осы: QR «кейінірек көріңіз» деп тұр
Телефонға счёттың мерзімі
kind: "phone" счёты клиенттің Kaspi қосымшасына хабарлама болып түседі және әлдеқайда ұзақ тұрады — адам оны бірден емес, кейінірек ашып төлей алады.
Нақты мерзімді дәл сол сияқты expiresAt өрісінен алыңыз.
| QR счёт | Телефонға счёт | |
|---|---|---|
| Терезесі | Қысқа, сканерлеуге арналған | Ұзақ, клиент кейін ашады |
| Қайда көрінеді | Экранда, басып шығарылған қағазда, төлем бетінде | Клиенттің Kaspi қосымшасында |
| Алдын ала жасауға бола ма | Жоқ | Иә |
| Клиент нөмірі керек пе | Жоқ | Иә |
Екеуінің толық салыстыруы: QR счёт пен телефонға счёт.
expiresAt-ты қалай дұрыс пайдалану
Счёт жасаған жауапта (201) expiresAt ISO уақыт болып келеді. Дұрыс қолдану реті:
- Жауаптан
expiresAtмәнін алып, өз базаңызға сақтаңыз - Бетте кері санауды сол мәнге қарап көрсетіңіз
- Уақыт біткенде «QR мерзімі өтті, жаңасын жасаңыз» батырмасын көрсетіңіз
- Батырма басылғанда жаңа счёт жасаңыз — ескісін қайта пайдаланбайсыз
Кодыңызға қандай да бір тұрақты санды жазып қоймаңыз: мерзім провайдер жағында өзгеруі мүмкін, сонда сіздің таймеріңіз шындыққа сәйкес келмей қалады.
expired күйі
Мерзімі өткен счёт expired күйіне ауысады және invoice.expired оқиғасы келеді. Бұл қалыпты аяқталу, қате емес: клиент жай төлемеген.
expired — соңғы күй. Ондай счётты:
- ❌ Қайта ашуға болмайды
- ❌ Мерзімін ұзартуға болмайды
- ❌ Оның QR-ын қайта көрсетудің мәні жоқ
- ✅ Орнына жаңа счёт жасайсыз,
externalOrderIdсол тапсырыс нөмірін қайта жазуға болады
Күйі expired болғаннан кейін бірден жоғалып кетпейді: ол тізімде қалады, есепке кіреді, тарихы сақталады. Счёттың өмірлік циклі.
Счёт күтілгеннен ұзақ pending тұрып қалса, ол бөлек жағдай: Счёт pending күйінде тұрып қалды.
Кеш төлем: жабылған счётқа ақша келуі
Бұл ең маңызды бөлім. Мерзімі өткен (expired) немесе болдырылған (cancelled) счётқа ақша кейін де келуі мүмкін — клиент терезенің соңғы секундында растаған, ал ақпарат бізге кейінірек жеткен.
Ондай жағдайда:
- Счёт
paidкүйіне ауысады - Сізге
invoice.paidоқиғасыlate: trueбелгісімен келеді - Бұл нақты ақша: ол сіздің Kaspi шотыңызға түскен
Не істеу керек:
- Webhook өңдеуіңіз
expiredнемесеcancelledкүйінен кейін келгенinvoice.paid-ты қабылдай алатын болсын. «Бұл счёт жабылған, елемеймін» деп тастап кетпеңіз - Қызметті беріңіз немесе ақшаны қайтарыңыз — екеуінің бірі
- Клиентке қайта төлеуді ұсынбаңыз: ақша бір рет түскен
- Өңдеуіңіз идемпотентті болсын —
(счёт идентификаторы, күй)жұбы бойынша. Идемпоттылық
Толық сценарий: Кеш келген төлем.
Сондықтан «терезе бітті, енді ештеңе болмайды» деп есептемеңіз: счётты жапқаннан кейін де біраз уақыт оның күйі өзгеруі мүмкін. Тауарды бірден жіберіп жатқан жүйелерде бұл жағдайды бөлек қарастырыңыз.
Жиі қойылатын сұрақтар
Мерзімді ұзартуға бола ма? Жоқ. Терезені Kaspi белгілейді, біз оны өзгерте алмаймыз. Клиентке уақыт керек болса, телефонға счёт жіберіңіз.
Счётты өзім жапсам, ақша келе ме? cancelled счётқа да ақша кешігіп келуі мүмкін — жоғарыдағы «кеш төлем» бөлімі толық күшінде.
Мерзімі өткен счёт лимитке кіре ме? Айлық лимит жасалған счёттармен есептеледі, төленгендерімен емес. Сондықтан артық счёт жасамаңыз: Тарифтер және лимиттер.
Sandbox-та мерзім сол күйінде ме? Sandbox-та күйлерді өзіңіз симуляциялайсыз, оның ішінде expired де бар: Sandbox-та төлемді симуляциялау.
Терезе қанша минут екенін айтып бере аласыз ба? Оны тұрақты сан ретінде беру дұрыс емес — Kaspi өзгертуі мүмкін. Нақты мәнді әрқашан expiresAt өрісінен оқыңыз.