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

# Возврат по QR: покупатель подтверждает возврат в Kaspi

**TL;DR.** У Kaspi есть вторая механика возврата — с подтверждением покупателя: деньги возвращаются после того, как **покупатель отсканирует возвратный QR тем Kaspi, которым платил**. Только после этого вы видите список его покупок и выбираете нужную. Применяют, когда [обычный возврат по счёту](/guides/vozvraty-kaspi-cherez-api) не проходит или оплата шла мимо ваших счетов. В кабинете это раздел **«Возврат с подтверждением»** на странице возвратов, в API — `/qr-refunds`.

## Коротко

| Вопрос | Ответ |
|---|---|
| Когда нужен | Когда обычный возврат по счёту не проходит или оплата шла мимо ваших счетов |
| Кто подтверждает | Покупатель — сканирует возвратный QR в приложении Kaspi |
| Чем сканировать | Тем же Kaspi, которым оплачивал: с другого аккаунта покупка не найдётся |
| Сколько живёт QR | Окно на скан задаёт Kaspi — берите `expires_at` и `scan_wait_timeout_seconds` из ответа старта, константу в код не зашивайте |
| Второй срок | После подтверждения на выбор покупки и возврат есть около **5 минут**, дальше `409 qr_refund_expired` |
| Частичный возврат | Да: суммой (`amount`) либо по товарам (`items`) — взаимоисключимо |
| Как узнать итог | Ответ `execute` приходит сразу; плюс вебхуки `qr_refund.*` |

## Флоу в API

Со стороны продавца это три шага: начать возврат и отправить покупателю ссылку любым мессенджером → дождаться, пока он подтвердит возврат в Kaspi → выбрать его покупку и вернуть деньги целиком или частично.

Все запросы — с вашим ключом в заголовке `X-API-Key`.

### 1. Начать возврат

```bash
curl -X POST https://api.apipay.kz/api/v1/qr-refunds \
  -H "X-API-Key: ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{}'
```

В ответе — ссылка и картинка QR для покупателя, срок действия и рекомендованный интервал опроса:

```json
{
  "id": 42,
  "status": "awaiting_scan",
  "qr_token_url": "https://qr.kaspi.kz/return/…",
  "qr_image_url": "https://…/storage/qr/uuid.png",
  "expires_at": "2026-07-27T17:27:09+05:00",
  "poll_interval_seconds": 3,
  "scan_wait_timeout_seconds": 90
}
```

Кассир выбирается так: явный `kaspi_connection_id` → основная касса организации → единственная активная.

⚠️ **Отправляйте ссылку только тому покупателю, которому возвращаете деньги.** Сессия опознаёт того, кто отсканировал QR своим Kaspi, и покажет его покупки у вас — по ссылке, попавшей не тому человеку, деньги вернутся ему. Не создавайте сессию заранее: сначала убедитесь, что покупатель у телефона.

### 2. Дождаться подтверждения

```bash
curl https://api.apipay.kz/api/v1/qr-refunds/42 -H "X-API-Key: ВАШ_КЛЮЧ"
```

Опрашивайте с интервалом из `poll_interval_seconds`, пока статус не станет `customer_identified` (покупатель подтвердил) или `expired` (срок вышел, нужна новая сессия). Вместо опроса можно слушать вебхуки `qr_refund.*`.

⚠️ **Не прекращайте опрос после `customer_identified`.** У сессии два срока: окно на скан задаёт Kaspi (`expires_at`, `scan_wait_timeout_seconds`), а после подтверждения на выбор покупки и возврат остаётся около **5 минут**. Если продавец задумался, сессия истечёт — и запрос на возврат вернёт `409 qr_refund_expired` уже после того, как человек выбрал покупку и ввёл сумму.

### 3. Посмотреть покупки

```bash
curl https://api.apipay.kz/api/v1/qr-refunds/42/operations -H "X-API-Key: ВАШ_КЛЮЧ"
```

```json
{
  "client_name": "Иван И.",
  "operations": [
    { "ref": "…", "amount": 500, "date": "2026-07-25T16:12:52+05:00", "returnable": "full" },
    { "ref": "…", "amount": 10,  "date": "2026-07-25T16:16:54+05:00", "returnable": "partial" },
    { "ref": "…", "amount": 10,  "date": "2026-06-30T20:19:31+05:00", "returnable": "none" }
  ],
  "has_more": false,
  "next_cursor": null,
  "remaining_count": 0
}
```

`returnable` говорит, что Kaspi разрешает по этой покупке: `full` — только целиком, `partial` — можно частично, `none` — возврат недоступен. Если покупок больше, передавайте `next_cursor` в `?cursor=`.

⚠️ **`ref` непрозрачен и привязан к сессии.** Не разбирайте его на части, не показывайте покупателю и не сохраняйте между сессиями — просто возвращайте обратно как есть.

### 4. Детали покупки

```bash
curl https://api.apipay.kz/api/v1/qr-refunds/42/operations/REF -H "X-API-Key: ВАШ_КЛЮЧ"
```

Приходят доступная к возврату сумма, уже возвращённое, ссылка на чек и позиции корзины — у каждой свой `ref` и свой остаток.

### 5. Вернуть деньги

```bash
# целиком
curl -X POST https://api.apipay.kz/api/v1/qr-refunds/42/execute \
  -H "X-API-Key: ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"operation_ref":"REF"}'

# частично, суммой
  -d '{"operation_ref":"REF","amount":7}'

# частично, по товарам
  -d '{"operation_ref":"REF","items":[{"ref":"ITEM_REF","amount":5}]}'
```

`amount` и `items` **взаимоисключимы** — вместе их присылать нельзя. У позиции `amount` необязателен: без него вернётся вся её доступная сумма.

Запрос синхронный, итог приходит сразу:

```json
{
  "id": 42,
  "status": "completed",
  "refunded_amount": "500.00",
  "receipt_url": "https://receipt.kaspi.kz/…",
  "client_name": "Иван И.",
  "completed_at": "2026-07-27T17:20:11+05:00"
}
```

## Частые ошибки

| Код | Что означает | Что делать |
|---|---|---|
| `qr_refund_not_identified` (409) | Покупатель ещё не подтвердил возврат | Дождитесь `customer_identified` |
| `qr_refund_expired` (409) | Срок сессии истёк | Начните новый возврат и отправьте свежую ссылку |
| `qr_refund_completed` (409) | Возврат по этой сессии уже выполнен | Не повторяйте: запросите статус и покажите результат оттуда |
| `operation_not_returnable` (422) | Kaspi не разрешает возврат по этой покупке | Выберите другую покупку |
| `refund_amount_exceeds_available` (422) | Сумма больше доступной к возврату | Проверьте `available_for_refund` в деталях покупки |
| `partial_refund_requires_return_items` (422) | Эту покупку Kaspi возвращает только по товарам | Пришлите `items` вместо `amount` |
| `connection_ambiguous` (422) | Активных касс несколько, основная не назначена | Передайте `kaspi_connection_id` при старте |
| `kaspi_session_invalid` (503) | Сессия кассира недоступна | Переподключите кассира, затем начните возврат заново |
| `organization_not_verified` (400) | Организация не верифицирована | Пройдите верификацию в кабинете |
| `tariff_inactive` (403) | Подписка ApiPay неактивна | Оплатите тариф. Старт и `execute` закрыты, чтение сессии продолжает работать |
| `not_sandbox` (403) | Поле `simulate` отправлено на боевой сессии | Уберите `simulate` или работайте в песочнице |
| `429` | Превышены **30 запросов в минуту** на ветку `/qr-refunds` — лимит держат в том числе `operations` и `operations/{ref}` | Опрашивайте по `poll_interval_seconds` и не перебирайте операции циклом |

При ошибках `422` сессия остаётся живой — можно повторить с другой покупкой или суммой, не начиная заново.

## Как проверить без реального покупателя

В песочнице реальный QR никому не уходит, а шаги покупателя двигаются вручную:

```bash
# покупатель подтвердил
curl -X POST https://api.apipay.kz/api/v1/qr-refunds/42/simulate \
  -H "X-API-Key: ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"event":"identified"}'

# срок истёк
  -d '{"event":"expired"}'
```

После `identified` отдаются три покупки: 500 ₸ с `returnable: full`, 10 ₸ с `partial` и 10 ₸ с `none`. Неуспех возврата форсируется полем `simulate` в теле `execute`:

```json
{ "operation_ref": "REF", "simulate": { "status": "failed", "error_code": "refund_amount_exceeds_available" } }
```

Вне песочницы поле `simulate` даёт `403 not_sandbox`.

## Частые вопросы

**Можно вернуть несколько покупок за одну сессию?**
Нет. Одна сессия — один возврат. Для второй покупки начните новый возврат.

**Приходят ли вебхуки?**
Да: `qr_refund.identified` при подтверждении покупателем, `qr_refund.completed` при успешном возврате и `qr_refund.expired` при истечении срока. Ретраи возможны — дедуплицируйте по паре `(event, qr_refund.id)`. Вебхуки равноправны поллингу `GET /qr-refunds/{id}`, статус в payload соответствует событию, а не текущему состоянию сессии.

---

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