Қысқаша
Қайтару POST /api/v1/invoices/{id}/refund арқылы жасалады, денесі { amount?, reason? }. Қате келсе, ең бірінші error кодын қараңыз — әрі қарайғы әрекет соған байланысты. Ең маңызды ережесі: refund_unknown немесе refund_pending_unknown келсе, сұрауды қайталамаңыз. Бұл екі код «нәтижесі әлі белгісіз» дегенді білдіреді, ал қайталасаңыз ақшаны екі рет қайтарып жіберуіңіз мүмкін. Оның орнына счёттың күйін оқып, шын мәнінде не болғанын содан біліңіз.
Қате кодтары бойынша
| Код | HTTP | Не болды | Не істеу керек |
|---|---|---|---|
invoice_not_refundable | 409 | Бұл счётты қайтаруға болмайды | Счёт төленген бе, мерзімі өтпеген бе — күйін оқыңыз |
invalid_refund_amount | 422 | Сома дұрыс емес | Оң сан, төленген сомадан аспауы керек |
refund_failed | 502 | Kaspi қайтаруды орындамады | Kaspi шотында ақша жеткілікті ме, тексеріңіз |
refund_unknown | 502 | Kaspi жауап бермеді, нәтижесі белгісіз | Қайталамаңыз. Счёт күйін оқыңыз |
refund_pending_unknown | 409 | Алдыңғы қайтарудың нәтижесі әлі белгісіз | Қайталамаңыз. Күте тұрыңыз |
refund_state_conflict | 409 | Қайтару күйі күткеннен басқа | Счёт күйін қайта оқып, содан кейін шешіңіз |
invoice_not_found | 404 | Счёт жоқ немесе сізге көрінбейді | Идентификаторды және кілттің кассирін тексеріңіз |
Ең жиі кездесетін үш себеп
1. Счёт қайтаруға жарамайды. Қайтару тек төленген счётқа жасалады. pending, expired, cancelled счётта қайтарар ақша жоқ — оларда invoice_not_refundable келеді. Толық қайтарылып қойған счёт та екінші рет қайтарылмайды.
Алдымен GET /api/v1/invoices/{id} арқылы күйін оқыңыз: paid немесе partially_refunded болса ғана қайтаруға болады.
2. Kaspi шотында ақша жетпейді. Бұл refund_failed қатесінің ең жиі себебі. Қайтару ақшасы сіздің Kaspi шотыңыздан шығады, ол бізде емес — біз ақшаны ешқашан ұстамаймыз. Шотта қалдық жеткіліксіз болса, Kaspi операцияны орындамайды.
Шешімі қарапайым: Kaspi шотындағы қалдықты тексеріңіз, керек болса толтырыңыз да, қайтаруды қайталаңыз. refund_failed — қайталауға болатын аз ғана қатенің бірі, өйткені ол «орындалмады» дегенді нақты айтады.
3. Кассир байланысы белсенді емес. Қайтару да Kaspi-дегі «Кассир» рөлі арқылы жүреді. Байланыс үзілген болса, қайтару да, жаңа счёт та жасалмайды. Кабинет → Kaspi бөлімінде байланысты қалпына келтіріңіз.
Оның үстіне кассир өз счёттары бойынша ғана қайтару жасай алады. Егер API кілт нақты бір кассирге байланған болса, ол басқа кассир шығарған счётты мүлде көрмейді — сізге invoice_not_found келеді.
Нәтижесі белгісіз болса
refund_unknown — Kaspi сұрауға жауап бермеді. Қайтару өтті ме, өтпеді ме — біз де білмейміз. refund_pending_unknown — алдыңғы қайтарудың нәтижесі әлі анықталмаған, жаңасын қабылдамаймыз.
Екеуінде де реті бірдей:
- Сұрауды қайталамаңыз. Мұнда идемпоттылық кепілдігі жоқ: екінші сұрау екінші қайтару болып кетуі мүмкін.
- Біраз күтіңіз — бірнеше секунд, керек болса бір минут.
- Счёттың күйін оқыңыз:
GET /api/v1/invoices/{id}. Жауапта счёттың қайтарулары көрінеді. - Күйі
refundedнемесеpartially_refundedболса — қайтару өткен, қайталаудың қажеті жоқ. - Күйі әлі
paidболып, қайтару тізімі бос болса — сонда ғана қайталаңыз.
Клиентке «қайтардық» деп счёттың күйін көрмей тұрып айтпаңыз.
Ішінара қайтару
amount өрісін көрсетсеңіз, көрсетілген сома ғана қайтарылады, счёт partially_refunded күйіне ауысады. amount көрсетілмесе, толық қайтару болады.
- Сома төленген сомадан аспауы керек, әйтпесе
invalid_refund_amount - Бірнеше рет ішінара қайтарсаңыз, олардың қосындысы да төленген сомадан аспауы керек
reasonөрісін толтырған дұрыс: кейін есепте не үшін қайтарғаныңыз көрініп тұрады
Қайтару өткенде invoice.refunded немесе invoice.partially_refunded webhook оқиғасы келеді. Автоматты есеп жүргізсеңіз, күйді сұраудан гөрі осы оқиғаларға сүйенген жеңіл.
Мерзім
Қайтару мерзімсіз емес: Kaspi белгілі бір уақыттан кейін ескі операцияны қайтаруға рұқсат бермейді. Мерзімді Kaspi белгілейді, біз оны ұзарта алмаймыз. Мерзімі өткен счётта invoice_not_refundable келеді.
Сондықтан қайтару туралы шешімді кешіктірмеңіз, әсіресе клиент даулап жатса.
Жиі жіберілетін қателер
- Қатені
messageмәтіні бойынша өңдеу. Мәтін өзгеруі мүмкін,errorкоды өзгермейді. - Қате келгенде автоматты қайталау циклін қосу. Қайтаруда бұл қауіпті.
- Клиентке счёт күйін тексермей жауап беру.
- Sandbox-та сынамай, бірден нақты қайтаруды жазу. Sandbox-та бүкіл циклді қауіпсіз сынауға болады.
Жиі қойылатын сұрақтар
Ақша клиентке қашан жетеді? Оны Kaspi шешеді, біз мерзімге әсер ете алмаймыз.
Қайтаруды болдырмауға бола ма? Жоқ. Өткен қайтару кері қайтарылмайды — клиенттен қайта төлеуін сұрауға тура келеді.
Комиссия қайтарыла ма? Kaspi өз комиссиясын өзі анықтайды, оны Kaspi қолдауынан нақтылаңыз. Біз транзакциядан пайыз алмаймыз, сондықтан бізге қайтарылатын ештеңе жоқ.
Кілтте қандай құқық керек? refunds:write. Құқық жетпесе insufficient_scope келеді.
Екі рет қайтарып жіберсем не болады? Ақша екі рет шығады, ал оны кері қайтару жолы жоқ. Сондықтан белгісіз нәтижелі қатеде ешқашан қайталамаңыз: Счёттар қосарланып жатыр мақаласындағы қорғаныс принциптері бұған да қатысты.