# Қайтару өтпей жатыр

> Қайтару қатесін код бойынша ажырату: счёт қайтаруға жарамайды, сома дұрыс емес, Kaspi орындамады немесе нәтижесі белгісіз. Қайсысында қайталауға болады, қайсысында мүлде болмайды.

## Қысқаша

Қайтару `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` — алдыңғы қайтарудың нәтижесі әлі анықталмаған, жаңасын қабылдамаймыз.

Екеуінде де реті бірдей:

1. **Сұрауды қайталамаңыз.** Мұнда идемпоттылық кепілдігі жоқ: екінші сұрау екінші қайтару болып кетуі мүмкін.
2. **Біраз күтіңіз** — бірнеше секунд, керек болса бір минут.
3. **Счёттың күйін оқыңыз:** `GET /api/v1/invoices/{id}`. Жауапта счёттың қайтарулары көрінеді.
4. Күйі `refunded` немесе `partially_refunded` болса — қайтару өткен, қайталаудың қажеті жоқ.
5. Күйі әлі `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` келеді.

**Екі рет қайтарып жіберсем не болады?** Ақша екі рет шығады, ал оны кері қайтару жолы жоқ. Сондықтан белгісіз нәтижелі қатеде ешқашан қайталамаңыз: [Счёттар қосарланып жатыр](/kb/duplicate-invoices) мақаласындағы қорғаныс принциптері бұған да қатысты.