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

Флоу в API

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

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

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

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

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

{
  "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. Дождаться подтверждения

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

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

{
  "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.

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