> Источник: https://apipay.kz/guides/apipay-dlya-oflayn-tochki-qr · Обновлено: 2026-09-26 · apipay.kz
> ApiPay — независимый сервис приёма платежей поверх вашего Kaspi Pay.

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

**TL;DR.** Офлайн-точке без сайта ApiPay даёт тот же сценарий, что терминал Kaspi: касса создаёт QR-счёт (`POST /invoices/qr`), показывает картинку QR на экране или планшете, покупатель сканирует и платит — подтверждение приходит вебхуком, обычно за секунды. Тот же счёт умеет доставляться ссылкой: в ответе есть `qr_token_url` — ссылка Kaspi на этот QR, на телефоне покупателя она открывает оплату в приложении Kaspi без сканирования, и её можно отправить в мессенджер, пока человек на связи. Окно на скан — **меньше трёх минут** (точный момент в `qr_expires_at`, длительность константой не зашивать), поэтому этот QR показывают динамически, под конкретную покупку, а не печатают на наклейке. Если оплата будет не сейчас и не при вас (бронь, предоплата, доставка) — используйте счёт по номеру телефона: он живёт **24 часа** и приходит push'ем в приложение Kaspi, либо статический QR под сделку ([как это работает](/guides/pechatnyy-qr-dlya-oplaty-po-sdelke)). Как выбрать — «[Какой QR выбрать](/guides/kakoy-qr-vybrat-qr-schet-ili-staticheskiy)».

## Как принимать Kaspi QR на точке без терминала?

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

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

Так же работает кафе или ресторан: когда гость просит счёт, касса выпускает QR на сумму чека и показывает его на планшете у стола или на экране кассы.

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

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

Точке нужен минимум — устройство с интернетом и доступ к [Kaspi API](/kaspi-api):

| Компонент | Зачем | Где подробнее |
|---|---|---|
| Номер кассира (отдельная SIM) | Штатная роль «Кассир» в Kaspi Pay, через неё выставляются счета | [Требования к номеру кассира](/guides/trebovaniya-k-nomeru-kassira) |
| API-ключ | Заголовок `X-API-Key` при создании QR | [API-ключ и вебхук-секрет](/guides/api-klyuch-i-webhook-secret) |
| Экран/планшет на точке | Динамический показ QR-счёта (печатать его нельзя — окно на скан меньше трёх минут); для бумаги — статический QR под сделку | [Статический QR](/guides/pechatnyy-qr-dlya-oplaty-po-sdelke) |
| Вебхук `invoice.status_changed` | Уведомление «оплачено» без опроса статуса — обычно за секунды | [Настройка вебхуков](/guides/nastroyka-webhookov-apipay) |
| Тариф по объёму | Лимит — по числу создаваемых счетов в день | [Тарифы и комиссия ApiPay](/guides/tarify-i-komissiya-apipay) |

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

1. **Зарегистрируйтесь на apipay.kz** и подключите номер кассира в разделе «Настройки → Авторизация Kaspi» — мастер и разбор отказов в «[Подключении кассира](/guides/podklyuchenie-kassira-kaspi)».
2. **Проверьте всё в песочнице**: QR-счёт в sandbox поддерживает `simulate: paid|cancelled|expired` — можно прогнать все исходы без реальных денег.
3. **Подключите вебхук** — URL, секрет и проверка подписи описаны в «[Настройке вебхуков](/guides/nastroyka-webhookov-apipay)».
4. **Встройте создание QR в кассовый сценарий** — поля запроса и ответа в [API-документации QR-счёта](/docs#invoices-qr):

```bash
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 на этот QR**: на телефоне покупателя она открывает оплату в приложении Kaspi, поэтому тот же счёт можно не показывать, а отправить в мессенджер, если человек оплатит сразу.

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

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

Правило простое: **QR-счёт — покупатель платит сейчас: стоит у кассы (покажите QR) или на связи в переписке (отправьте `qr_token_url`); счёт по номеру — покупатель оплатит позже**.

- Окно на скан у QR — меньше трёх минут, продления нет; точный момент берите из `qr_expires_at` (подробно — «[Сколько живёт QR-счёт](/guides/qr-schet-ttl-i-limity)»).
- [Счёт по номеру телефона](/invoice-by-phone) живёт **24 часа**: покупателю приходит push и счёт ждёт внутри приложения Kaspi. Ссылки на оплату у такого счёта нет. Ссылка на оплату «на потом» — поле `payment_url` (`POST /invoices/qr` со `static: true` или `POST /static-qr`); если режим ссылок выключен, отправляют `print_url` листа [статического QR](/guides/pechatnyy-qr-dlya-oplaty-po-sdelke). Покупателю, который платит прямо сейчас, подойдёт `qr_token_url` QR-счёта — он действует до `qr_expires_at`.

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

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

1. **QR с кассы печатать нельзя.** Меньше чем через три минуты наклейка с таким QR перестанет работать — показывайте его динамически, под конкретную оплату. Для бумаги есть отдельный [статический QR под сделку](/guides/pechatnyy-qr-dlya-oplaty-po-sdelke), он работает, пока лист не оплачен и не отключён.
2. **Ссылку QR-счёта отправляют «на сейчас», а не «на потом».** `qr_token_url` можно послать покупателю в мессенджер, и он оплатит без сканирования — но только если откроет её в течение окна на скан. Если человек прочитает сообщение через полчаса, ссылка уже истечёт. Для оплаты «когда увидит» — ссылка на оплату `payment_url` или счёт по номеру (24 часа), для бумаги — статический QR (`print_url`). Не пересоздавайте QR-счёт, пока покупатель думает: каждый созданный QR-счёт занимает место в [лимите тарифа](/guides/limit-schetov-po-tarifu). Разбор всех вариантов — «[Оплата по ссылке Kaspi](/guides/oplata-po-ssylke-kaspi)».
3. **Забытая песочница.** Если оплаты «не проходят» сразу после подключения — проверьте, что включён рабочий режим, а не sandbox.

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

**Можно ли распечатать QR и повесить у кассы?**
QR-счёт с кассы — нет: он создаётся под конкретную сумму и живёт минуты, поэтому его показывают динамически на экране. Для бумаги есть отдельный инструмент — «[Статический QR для оплаты по счёту или сделке](/guides/pechatnyy-qr-dlya-oplaty-po-sdelke)». Общего QR «на все покупки сразу» нет ни в одном из режимов.

**Нужен ли точке сайт или онлайн-касса?**
Нет. Достаточно устройства, которое вызывает API и показывает картинку: планшет, кассовое ПО, даже внутренний скрипт. Без кода можно выставлять счета по номеру прямо из кабинета apipay.kz.

**Как понять, что покупатель оплатил?**
Вебхуком `invoice.status_changed` со статусом `paid` — обычно за секунды после оплаты, в отдельных случаях — до 10 минут. Не выдавайте товар по устному «оплатил» и по факту скана (`invoice.qr_scanned` — ещё не оплата).

**Что если покупатель отсканировал, но передумал?**
Придёт `cancelled` (закрыл оплату или свернул приложение). QR-счета сосуществуют: можно сразу создать новый, старый ничего не блокирует.

**Берёт ли ApiPay процент с оплат на точке?**
Нет, модель — фиксированная подписка с дневным лимитом создаваемых счетов; цены — «[Тарифы и комиссия ApiPay](/guides/tarify-i-komissiya-apipay)». Деньги покупателей идут напрямую на ваш Kaspi-счёт.

---

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