Сначала проверьте
- Укладываетесь в 5 минут? Засеките время от создания QR до сканирования. Больше ~5 минут — QR мёртв, и это не поломка.
- Не песочница ли? У тестового счёта
is_sandbox: true— такой QR в Kaspi не существует, покупатель увидит ошибку. - Описание короче 100 символов? Более длинное описание Kaspi отклоняет ещё на создании QR.
Ветки диагностики
| Признак | Причина (частота по данным поддержки) | Что сделать | Подробнее |
|---|---|---|---|
| Покупатель сканирует → «Попробуйте позже» | QR истёк: TTL ~5 минут, продления нет — чаще всего | Создать новый QR прямо перед оплатой | «Что на самом деле значит „Попробуйте позже“?» в «QR-счёте: TTL и лимиты» |
| QR «не работает» на тестах | Песочница: тестовый QR в Kaspi не существует — часто | Включить «Рабочий режим» | Песочница и рабочий режим |
| Ошибка при создании QR | Описание длиннее 100 символов — редко | Сократить description до 100 символов |
«Ограничения QR-счёта…» в «QR-счёте» |
| «Второй QR сломал первый» | Историческое поведение (до июня 2026); теперь QR сосуществуют | Пересоздание не отменяет старые — просто создавайте новый | «Можно ли держать несколько активных QR одновременно?» в «QR-счёте» |
| В интеграции «ошибка 401» | Развилка: HTTP-код или внутренний код Kaspi? | Разводка ниже | — |
«401» — это число или HTTP-код?
Диагностический вопрос, который экономит час разбора. HTTP 401 на запросе к ApiPay — невалидный API-ключ (перегенерировался? см. «API-ключ и вебхук-секрет»). А вот «401» внутри текста ошибки в JSON — внутренний код Kaspi, к HTTP-авторизации отношения не имеет; смотрите текстовое описание рядом с кодом и error_code. Присылая ошибку в поддержку, копируйте JSON целиком — так видно, какая из двух ситуаций у вас.
Покупатель платит не сразу? QR — не тот инструмент
QR — как касса в магазине: покупатель стоит рядом и платит сейчас. Если оплата «когда-нибудь в течение дня» — выставляйте счёт по номеру телефона: он живёт 24 часа, покупателю приходит push в Kaspi, и из счёта можно получить ссылку на оплату. Подробно — «Как создать счёт Kaspi по номеру».
Для вашего ИИ-агента
Смотрите: qr_expires_at в ответе создания (POST /invoices/qr, TTL ~5 минут), готовый PNG в qr_image_url; факт сканирования — вебхук invoice.qr_scanned (qr_substate: "scanned", один раз на QR); cancelled по QR — действие покупателя, а не системы. Различайте HTTP 401 (ключ) и «401» в теле ошибки Kaspi.
Частые вопросы
Можно продлить срок жизни QR?
Нет, QR живёт ~5 минут by design. Для сценариев «оплатит позже» — счёт по номеру телефона (24 часа).
Покупатель увидел «Попробуйте позже» — счёт пропал?
QR истёк, но это не страшно: создайте новый QR и дайте отсканировать сразу. Оплата по истёкшему QR невозможна, двойного списания не будет.
Можно держать несколько активных QR одновременно?
Да: QR-счета сосуществуют, создание нового не отменяет прежние (поведение с июня 2026; старые статьи могли описывать обратное).
Почему QR не работает в тестовом режиме?
Тестовый QR существует только в ApiPay, в Kaspi его нет — покупатель при сканировании получит ошибку. Включите рабочий режим.
QR отменился сам — это сбой?
Нет: cancelled по QR — действие покупателя (закрыл или свернул приложение). Создайте новый QR.