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

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

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

## Вы покупатель и хотите вернуть деньги за покупку?

Эта страница — для продавцов, которые делают возвраты. Если вы покупатель, по вопросу возврата обратитесь к продавцу, у которого покупали, или в поддержку Kaspi. ApiPay делает инструмент для продавца и заявки покупателей на возврат не рассматривает. Если вы продавец — читайте дальше.

## Что проверить в первую очередь?

1. **Счёт оплачен?** Возврат возможен только по оплаченному счёту, который ещё не возвращён полностью.
2. **На Kaspi-счёте хватает денег на полную сумму возврата?** Помните про комиссию Kaspi — «полученное» всегда чуть меньше «оплаченного».
3. **Прошло меньше пары минут?** Возврат асинхронный: «создан» ещё не значит «выполнен», итог придёт вебхуком `invoice.refunded`.
4. **Кассир отключён или сменён на другой номер?** После «Отключить» возврат через ApiPay не пройдёт — только вручную в приложении Kaspi Pay под аккаунтом владельца. После смены на другой номер возврат по оплате прежнего кассира может не пройти: обычный возврат придёт со статусом `failed`, возврат по ссылке — с ошибкой `qr_refund_operation_not_found`; тогда тоже делайте его вручную в Kaspi Pay. Если по счетам последних двух недель возможны возвраты, меняйте или отключайте кассира только после закрытия этого окна ([Смена и отключение кассира](/guides/smena-kassira-nomera-vladeltsa)).

## Почему возврат не проходит и что делать в каждом случае?

| Признак | Причина | Что сделать |
|---|---|---|
| `failed` с `error_code: refund_insufficient_funds` (в кабинете — «Недостаточно денег на счёте») | На Kaspi-счёте нет полной суммы возврата | Пополнить Kaspi-счёт и создать возврат заново (через API — с новым `Idempotency-Key`) |
| `failed` по счёту, оплаченному через кассира, которого уже отключили | Без подключённого кассира ApiPay возврат провести не может | Сделать возврат вручную в приложении Kaspi Pay под аккаунтом владельца |
| `failed` с `error_code: refund_window_expired` | Истёк срок возврата (ориентир ~14 дней, границу держит Kaspi) или возврат уже сделан | Повторы бесполезны. Сначала проверьте историю возвратов счёта в кабинете или `GET /invoices/{id}/refunds`; если возврата там нет и срок вышел — возвращайте вне ApiPay по своим правилам торговли |
| `failed` с `error_code: refund_requires_buyer_confirmation` | Kaspi требует, чтобы покупатель подтвердил возврат | Сделать возврат по ссылке для покупателя — раздел ниже |
| `failed` с `error_code: refund_rejected_by_kaspi` | Kaspi отклонил возврат по этой операции, отказ бывает временным | Возврат по ссылке с `source_refund_id` этого возврата; без удержания можно сначала повторить позже; либо вручную в приложении Kaspi Pay — сначала отзовите ссылки по счёту и проверьте возвраты (ниже, «Как понять, проблема у Kaspi или в ApiPay?») |
| `422` или `failed` с `error_code: partial_refund_requires_return_items` | Частичный возврат корзинного счёта отправлен плоским `amount` | Передать `return_items[]` |
| `403 tariff_inactive` при создании возврата | Не оплачена подписка ApiPay | Оплатить тариф: без него закрыты и обычный возврат, и возврат по ссылке |
| «Создан, жду» — и тишина пару минут | Возврат в `pending`/`processing`, итог придёт вебхуком `invoice.refunded` | Дождаться вебхука или прочитать `GET /invoices/{id}/refunds`. Дубль не создавать: пока возврат не завершён, второй возврат по этому счёту не создастся — ни обычный, ни по ссылке (`409 qr_refund_link_invoice_busy`) |
| Ответ на запрос возврата не пришёл (таймаут, обрыв связи) | Неизвестно, принят ли возврат | Повторить запрос с тем же `Idempotency-Key` и тем же телом: придёт `200` с `idempotent_replay: true` и прежний возврат. Без ключа или с новым ключом частичный возврат может пройти дважды |
| Возврат остаётся `processing` с `error_code: refund_execution_uncertain` | Результат денежного запроса не подтверждён — деньги могли уже уйти | ⛔ Не повторять, не выпускать ссылку-возврат и не делать тот же возврат вручную в приложении. Сверить историю операций в Kaspi Pay и отметить исход в карточке счёта в кабинете ApiPay; если не уверены — написать в поддержку ApiPay |

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

## Что делать, если Kaspi требует подтверждения покупателя?

Вернуть деньги можно возвратом с подтверждением покупателя: вы отправляете ему ссылку «Возврат ApiPay», он открывает её и сканирует возвратный QR тем Kaspi, которым платил. В API ссылку выпускает `POST /qr-refunds/links`. С `invoice_id` она привязана к оплаченному счёту и возврат проводится сам после подтверждения покупателя; с `source_refund_id` сумма, товары и причина берутся из отказанного возврата. Работает и там, где оплата шла мимо ваших счетов. Флоу, два срока и коды ошибок — «[Возврат по QR](/guides/vozvrat-po-qr-cherez-api)».

## Как сделать возврат по ссылке из кабинета?

Если Kaspi не разрешил обычный возврат, откройте его статус в счёте и нажмите
«Создать ссылку для клиента». Сумма, выбранные товары и причина сохранятся.
Отправьте ссылку через WhatsApp или скопируйте её в сообщение клиенту.
Клиенту нужен второй экран: ссылка открывается на компьютере или другом телефоне,
а QR сканируется в том аккаунте Kaspi, которым была оплачена покупка.

Окно кабинета можно закрыть. После подтверждения клиента возврат проводится автоматически;
«Клиент подтверждает возврат» ещё не означает, что деньги возвращены. Завершение обозначено
«Возврат выполнен». При статусе «Проверяем результат возврата» не запускайте повторный возврат.

Владелец может включить «Делать все возвраты по ссылке» и изменить выбор в настройках
организации. Выбор действует для всех устройств кабинета; права сотрудников и поведение
API-интеграций не меняются. После перезагрузки страницы статус сохранится, но секретный адрес
ссылки повторно не выдаётся. Если клиент его не получил, отзовите ссылку, пока клиент её
не открыл, и создайте новую.

## Как понять, проблема у Kaspi или в ApiPay?

Только после итога `failed` сделайте **тот же возврат вручную из приложения Kaspi Pay под аккаунтом владельца**, а не под номером кассира — вход под номером кассира вытесняет сессию и разрывает привязку кассы к ApiPay. Пока возврат в `pending` или `processing`, вручную его не дублируйте: иначе покупатель может получить деньги дважды.

Перед ручным возвратом проверьте весь счёт в `GET /invoices/{id}/refunds`: деньги могут уйти и по ссылке, выпущенной без `source_refund_id`, — своего `operation_state` у неё нет, она видна только в `qr_refund_sessions`.

1. Отзовите все живые ссылки по счёту: в кабинете — кнопка «Отозвать ссылку» в разделе «Возвраты», по API — `DELETE /qr-refunds/links/{id}`. Отзыв не прерывает уже открытое окно сканирования: если покупатель успеет подтвердить, деньги уйдут. Дождитесь, пока окно закроется: оно длится не больше 90 секунд, после него статус ссылки сменится (шаг 2).
2. В `qr_refund_sessions` у ссылок должны остаться только статусы `completed`, `expired` или `failed`. `completed` значит, что деньги по этой ссылке уже вернулись: вручную возвращайте только остаток, если он ещё нужен, — его показывает `available_for_refund` в блоке `invoice`. `execution_uncertain` значит, что деньги, возможно, уже ушли: вручную не возвращайте и обратитесь в поддержку ApiPay — этот статус сам не изменится.
3. У каждого возврата счёта `operation_state` — `completed`, `failed`, `awaiting_buyer` или `released`. У самого отклонённого возврата — только `failed`, `awaiting_buyer` или `released`: если у него `completed`, деньги уже вернулись, в том числе по ссылке, и вручную возвращать не нужно. При `processing`, `buyer_link_active` или `uncertain` — ждите итога.

Только после этого возвращайте вручную, иначе покупатель получит деньги второй раз. `409 qr_refund_link_not_revocable` значит, что ссылку уже нельзя отозвать: покупатель подтвердил возврат или ссылка завершилась. Решайте по тем же полям.

Если и приложение не даёт — причина на стороне Kaspi (обычно деньги или срок), условия возврата описаны в [справке Kaspi](https://guide.kaspi.kz/). Если из приложения прошло, а через ApiPay нет — пишите в поддержку ApiPay: номер счёта, сумма, скриншот ошибки.

## Как делать возвраты без ручной работы?

Ручной возврат из приложения работает, пока возвратов единицы. Дорого становится, когда:

- возвратов много и каждый приходится искать в истории операций;
- заказы приходят с сайта, из бота или 1С, и учётная система должна сама узнать, что деньги вернулись;
- возвращать нужно не всю сумму, а отдельные товары из корзины.

В ApiPay возврат делается кнопкой в кабинете или запросом `POST /invoices/{id}/refund` — полный, на часть суммы или по позициям `return_items[]`. Итог приходит вебхуком `invoice.refunded`: `completed` или `failed` с причиной в `refund.error_code`, по таблице выше. Если Kaspi требует подтверждения покупателя, ссылка для него действует 24 часа. Это тот же кабинет и тот же тариф, что для счетов, — отдельно подключать ничего не нужно. Подробнее — «[Как принимать оплату Kaspi через API](/kaspi-api)» и [документация API](/docs); код интеграции может написать ваш ИИ-агент — дайте ему [apipay.kz/for-ai](https://apipay.kz/for-ai).

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

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

## Вопросы и ответы

**Почему не проходит возврат в Kaspi Pay?**
Чаще всего на Kaspi-счёте продавца не хватает денег: Kaspi удерживает комиссию при оплате, а возврат уходит на полную сумму. Вторая причина — прошёл срок возврата. Пополните счёт и сделайте возврат заново.

**Как сделать возврат клиенту, если он платил через Kaspi Pay (ТОО или ИП)?**
Вручную — в приложении Kaspi Pay под аккаунтом владельца. Через ApiPay — кнопкой в кабинете или запросом `POST /invoices/{id}/refund`, итог придёт вебхуком `invoice.refunded`. Если Kaspi требует подтверждения покупателя — отправьте ему ссылку на возврат.

**Какой срок возврата у Kaspi?**
Ориентир — около 14 дней с момента оплаты, точную границу определяет Kaspi. После срока возврат через ApiPay откажет с кодом `refund_window_expired`, и деньги возвращают вне ApiPay по правилам вашей торговли.

**Возврат создан, но деньги не вернулись — что делать?**
Возврат асинхронный: подождите несколько минут, итог придёт вебхуком `invoice.refunded` или будет виден в `GET /invoices/{id}/refunds`. Дубль не создавайте. Если возврат остаётся `processing` с `refund_execution_uncertain`, не повторяйте его: сверьте историю операций в Kaspi Pay и отметьте исход в карточке счёта в кабинете ApiPay; если не уверены — напишите в поддержку ApiPay.

**Я покупатель — как вернуть деньги после покупки в Kaspi?**
Обратитесь к продавцу, у которого покупали, или в поддержку Kaspi. ApiPay делает инструмент для продавцов и заявки покупателей на возврат не рассматривает.

---

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