Сначала проверьте
- Счёт оплачен? Возврат возможен только по оплаченному счёту, который ещё не возвращён полностью.
- На Kaspi-счёте хватает денег на полную сумму возврата? Помните про комиссию Kaspi — «полученное» всегда чуть меньше «оплаченного».
- Прошло меньше пары минут? Возврат асинхронный: «создан» ещё не значит «выполнен» — система делает до 3 попыток, итог придёт вебхуком.
Ветки диагностики
| Признак | Вероятная причина (частота по данным поддержки) | Что сделать | Подробнее |
|---|---|---|---|
«Возврат создан», но статус стал failed / Kaspi пишет «Недостаточно денег на счёте» |
Не хватает средств из-за удержанной комиссии Kaspi — чаще всего | Пополнить Kaspi-счёт и создать возврат заново (сумма не блокируется) | Раздел «„Возврат создан, но не проходит“ — что происходит?» в «Возвратах Kaspi через API» |
failed по давнему счёту |
Истекло окно возврата — ориентир ~14 дней, точную границу определяет Kaspi — редко | Возврат вне ApiPay (наличными/через Kaspi) — правила окна на стороне Kaspi | «Сроки: окно возврата и зачисление покупателю» в «Возвратах» |
| Полный возврат проходит, частичный — нет | Весь чек забит одной позицией, а возврат в Kaspi работает поштучно — редко | Для неделимой позиции — частичный возврат по сумме (amount); впредь разбивать чек на позиции |
«Частичный возврат: по сумме или по штукам?» в «Возвратах» |
| «Создан, жду» — и тишина пару минут | Нормальная асинхронность: до 3 попыток, итог вебхуком invoice.refunded — часто пугает, но не ошибка |
Дождаться вебхука или обновить статус; не создавать дубль раньше времени | Возвраты Kaspi через API |
Кросс-чек за минуту: попробуйте из приложения
Рабочий приём поддержки: сделайте тот же возврат из приложения Kaspi Pay (вручную, с телефона кассира). Если и приложение не даёт — причина на стороне Kaspi (обычно деньги или срок), и API здесь ни при чём. Если из приложения прошло, а через API нет — вот это уже к нам, пишите в поддержку с деталями.
Математика комиссии на пальцах
Покупатель оплатил 2 000 ₸ → Kaspi удержал комиссию (~0,95%) → на счёт организации поступило ~1 981 ₸. Возврат покупателю делается на полные 2 000 ₸ — значит, на счёте должна быть вся сумма. Если возвратов много, разница накапливается: держите на Kaspi-счёте запас.
Для вашего ИИ-агента
Смотрите: refund.status (pending → processing → completed | failed); вебхук invoice.refunded приходит и на completed, и на failed; refund.error_message в вебхуке отсутствует by design — детали берите из GET /refunds/{id}; доступную сумму — из available_for_refund; признак полного возврата — is_fully_refunded: true (статуса refunded у счёта не существует).
Частые вопросы
Почему возврат «создан», но деньги покупателю не вернулись?
Возврат асинхронный: система делает до 3 попыток и присылает итог вебхуком. Если итог failed — чаще всего на Kaspi-счёте не хватило средств из-за удержанной комиссии Kaspi.
Сколько дней действует возможность возврата?
Ориентир — около 14 дней с оплаты; точную границу определяет Kaspi. Для старых счетов возврат через API может быть уже недоступен.
После неудачного возврата сумма блокируется?
Нет: после failed система ничего не блокирует — пополните счёт и создайте возврат заново.
Почему статус счёта не изменился на «refunded»?
Такого статуса нет: после полного возврата счёт остаётся paid (или partially_refunded) с флагом is_fully_refunded: true.
Можно проверить возврат без API?
Да — из приложения Kaspi Pay. Это лучший кросс-чек: если и там не проходит, причина на стороне Kaspi.