Сначала проверьте
- Счёт оплачен? Возврат возможен только по оплаченному счёту, который ещё не возвращён полностью.
- На Kaspi-счёте хватает денег на полную сумму возврата? Помните про комиссию Kaspi — «полученное» всегда чуть меньше «оплаченного».
- Прошло меньше пары минут? Возврат асинхронный: «создан» ещё не значит «выполнен», итог придёт вебхуком
invoice.refunded. - Кассир отключён? Тогда возврат через 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».
Если возврат по счёту не проходит — возврат по QR
Вторая ветка: покупатель подтверждает возврат сканом возвратного QR, после чего вы выбираете его покупку и возвращаете сумму целиком или частично. Работает и там, где оплата шла мимо ваших счетов. Флоу, коды ошибок и песочница — «Возврат по QR».
Кросс-чек: повторите возврат из приложения
Сделайте тот же возврат вручную из приложения 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».