> Источник: https://apipay.kz/guides/vozvrat-ne-prohodit · Обновлено: 2026-07-06 · apipay.kz
> ApiPay — независимый сервис приёма платежей поверх вашего Kaspi Pay.

# Возврат Kaspi не проходит — в чём причина?

**TL;DR.** Начните с `refund.error_code` в вебхуке `invoice.refunded` — он называет причину. Частая причина — **нехватка денег на Kaspi-счёте организации**: Kaspi удерживает свою комиссию сразу при оплате, поэтому на счёт зачисляется меньше, чем заплатил покупатель, — а возврат уходит на полную сумму покупки, и с пустого счёта её не хватит. Kaspi отвечает: «Возврат отклонён. Недостаточно денег на счёте». Первое действие: пополните Kaspi-счёт на недостающую сумму и создайте возврат заново — после `failed` сумма освобождается.

## Сначала проверьте

1. **Счёт оплачен?** Возврат возможен только по оплаченному счёту, который ещё не возвращён полностью.
2. **На Kaspi-счёте хватает денег на полную сумму возврата?** Помните про комиссию Kaspi — «полученное» всегда чуть меньше «оплаченного».
3. **Прошло меньше пары минут?** Возврат асинхронный: «создан» ещё не значит «выполнен», итог придёт вебхуком `invoice.refunded`.
4. **Кассир отключён?** Тогда возврат через ApiPay провести нельзя — только вручную в приложении Kaspi Pay под аккаунтом владельца. Если по счетам последних двух недель возможны возвраты, отключайте кассира только после закрытия этого окна.

## Ветки диагностики

| Признак | Причина | Что сделать |
|---|---|---|
| «Возврат создан», но статус стал `failed`, Kaspi пишет «Недостаточно денег на счёте» | На Kaspi-счёте нет полной суммы возврата | Пополнить Kaspi-счёт и создать возврат заново |
| `failed` с `error_code: refund_window_expired` | Истёк срок возврата (ориентир ~14 дней, границу держит Kaspi) или возврат уже сделан | Ретраи бесполезны, возвращайте вне ApiPay по своим правилам торговли |
| `422` или `failed` с `error_code: partial_refund_requires_return_items` | Частичный возврат корзинного счёта отправлен плоским `amount` | Передать `return_items[]` |
| `403 tariff_inactive` при создании возврата | Не оплачена подписка ApiPay | Оплатить тариф: без него закрыты и обычный возврат, и возврат по QR |
| «Создан, жду» — и тишина пару минут | Возврат в `pending`/`processing`, итог придёт вебхуком `invoice.refunded` | Дождаться вебхука или прочитать `GET /invoices/{id}/refunds`. Дубль не создавать: сумма незавершённого возврата уже вычтена из `available_for_refund` |

Разбор каждой ветки — коды ошибок, частичный возврат, окно возврата — в «[Возвратах Kaspi через API](/guides/vozvraty-kaspi-cherez-api)».

## Если возврат по счёту не проходит — возврат по QR

Вторая ветка: покупатель подтверждает возврат сканом возвратного QR, после чего вы выбираете его покупку и возвращаете сумму целиком или частично. Работает и там, где оплата шла мимо ваших счетов. Флоу, коды ошибок и песочница — «[Возврат по QR](/guides/vozvrat-po-qr-cherez-api)».

## Кросс-чек: повторите возврат из приложения

Сделайте **тот же возврат вручную из приложения Kaspi Pay под аккаунтом владельца**, а не под номером кассира — вход под номером кассира вытесняет сессию и разрывает привязку кассы к ApiPay. Если и приложение не даёт — причина на стороне Kaspi (обычно деньги или срок), и API здесь ни при чём. Если из приложения прошло, а через API нет — вот это уже к нам, пишите в поддержку с деталями.

## Для вашего ИИ-агента

Смотрите `refund.status` (`pending → processing → completed | failed`). Причина отказа — в `refund.error_code` вебхука `invoice.refunded`, текст берите из `GET /api/v1/invoices/{id}/refunds`. Доступная сумма — `available_for_refund` (уже за вычетом незавершённых возвратов), признак полного возврата — `is_fully_refunded: true`, статуса `refunded` у счёта не существует. Полный список синхронных отказов — в «[Возвратах Kaspi через API](/guides/vozvraty-kaspi-cherez-api)».

---

ApiPay — независимый сервис и не аффилирован с АО «Kaspi Bank». Kaspi и Kaspi Pay — товарные знаки их правообладателя.
База знаний: https://apipay.kz/guides