Как принимать Kaspi QR на офлайн-точке через ApiPay?

Как это работает у вас

Схема потока на точке (касса, шоурум, пункт проката, туристический офис):

Покупатель у кассы готов платить
        │
Ваша касса/планшет → POST /invoices/qr (сумма + описание ≤100 симв.)
        │
201: qr_image_url (готовый PNG) — показываете на экране
        │
Покупатель сканирует камерой Kaspi → подтверждает оплату
        │
Вебхук invoice.status_changed: status=paid  →  выдаёте товар/чек

Ни сайта, ни онлайн-витрины не нужно: достаточно любого устройства с интернетом, которое умеет вызвать API и показать картинку. Деньги идут напрямую на ваш Kaspi-счёт.

Что понадобится

Точке нужен минимум — устройство с интернетом и доступ к Kaspi API:

Пошаговый сетап

1. Зарегистрируйтесь на apipay.kz и подключите номер кассира в разделе «Настройки → Авторизация Kaspi» — мастер и разбор отказов в «Подключении кассира».
2. Проверьте всё в песочнице: QR-счёт в sandbox поддерживает simulate: paid|cancelled|expired — можно прогнать все исходы без реальных денег.
3. Подключите вебхук — URL, секрет и проверка подписи описаны в «Настройке вебхуков».
4. Встройте создание QR в кассовый сценарий:

curl -X POST https://api.apipay.kz/api/v1/invoices/qr \
  -H "X-API-Key: ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"amount": 12500, "description": "Заказ №481, шоурум"}'

Ответ приходит сразу (201, статус pending) и содержит qr_image_url — готовый PNG, который остаётся вывести на экран, — и qr_token_url (платёжная ссылка Kaspi).

5. Показывайте таймер: считайте его как qr_expires_at − now (окно меньше трёх минут), константу в коде не зашивайте. После истечения — кнопка «Создать новый QR», а не ожидание. Картинка qr_image_url доступна до qr_expires_at + 60 секунд, дальше отдаёт 404.
6. Выдавайте товар только по вебхуку paid, а не по слову «я оплатил».

Когда QR, а когда счёт по номеру?

Правило простое: QR — покупатель стоит рядом и платит сейчас; счёт по номеру — покупатель удалённо или «оплатит позже».

• Окно на скан у QR — меньше трёх минут, продления нет; точный момент берите из qr_expires_at (подробно — «Сколько живёт QR-счёт»).
• Счёт по номеру телефона живёт 24 часа: покупателю приходит push и счёт ждёт внутри приложения Kaspi. Ссылки на оплату у такого счёта нет — отправлять в WhatsApp нечего. Если нужна именно ссылка, это печатный QR под сделку.

В вебхуке об оплате приходят поля kaspi_source_type (значения GOLD, RED, LOAN, BUSINESSACCOUNT, BANKINTEGRATIONACCOUNT) и kaspi_sale_type (Remote, QR, Static, Restaurant) — обе строки приходят только когда они непустые, поэтому сравнивайте именно с этими значениями и держите ветку по умолчанию.

Грабли этого бизнеса

1. QR с кассы печатать нельзя. Меньше чем через три минуты наклейка с таким QR перестанет работать — показывайте его динамически, под конкретную оплату. Для бумаги есть отдельный печатный QR под сделку, он живёт месяцами.
2. QR-ссылку нельзя «отправить на потом» в мессенджер: пока клиент откроет сообщение, она истечёт. Для оплаты «когда увидит» — счёт по номеру, для бумаги — печатный QR под сделку.
3. Забытая песочница. Если оплаты «не проходят» сразу после подключения — проверьте, что включён рабочий режим, а не sandbox.

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