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

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

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

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

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

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

Ни сайта, ни онлайн-витрины не нужно: достаточно любого устройства с интернетом, которое умеет вызвать 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.kz |

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

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

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

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

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

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

В вебхуке об оплате приходят поля `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 под сделку.
3. **Забытая песочница.** Если оплаты «не проходят» сразу после подключения — проверьте, что включён рабочий режим, а не sandbox.

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

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

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

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

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

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

---

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