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

Флоу в API

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

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

1. Выпустить ссылку покупателю

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

В ответе — одноразовая ссылка «Возврат ApiPay» и её срок:

{
  "id": 42,
  "status": "awaiting_customer",
  "customer_url": "https://qr.apipay.kz/refund/ОДНОРАЗОВЫЙ_ТОКЕН",
  "link_expires_at": "2026-07-28T17:27:09+05:00"
}

⛔ customer_url отдаётся ровно один раз — сохраните сразу. Получить адрес повторно нельзя ни через GET /qr-refunds/{id}, ни как-либо ещё. Ссылка предъявительская: кто её открыл, тот и подтверждает возврат — не публикуйте её и не пишите в логи и аналитику.

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

⚠️ Отправляйте ссылку только тому покупателю, которому возвращаете деньги. Сессия опознаёт того, кто открыл ссылку и подтвердил возврат в Kaspi, и покажет ЕГО покупки у вас.

Окно скана начинается не при выпуске, а когда покупатель откроет ссылку и нажмёт кнопку. Неоткрытую ссылку можно погасить: DELETE https://api.apipay.kz/api/v1/qr-refunds/links/42 — сессия перейдёт в expired с error_code qr_refund_link_revoked. Уже открытую отозвать нельзя (409 qr_refund_link_not_revocable). Потеряли адрес — отзовите ссылку и выпустите новую; неотозванная действует до link_expires_at.

Немедленный старт POST /qr-refunds оставлен для совместимости: возвратный QR живёт не более 90 секунд и требует, чтобы покупатель стоял у кассы.

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

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. Посмотреть покупки

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

{
  "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. Детали покупки

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

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

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

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 необязателен: без него вернётся вся её доступная сумма.

Ответ приходит сразу. 200 — деньги вернулись, и это доказано. 202 — запрос ушёл, а исход не доказан: возврат мог быть применён. ⛔ Повторять execute в этом случае нельзя ни при каких условиях — второй запрос вернёт покупателю деньги ещё раз. Обратитесь в поддержку.

Ответ 200:

{
  "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 никому не уходит, а шаги покупателя двигаются вручную:

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:

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

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

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