> Источник: 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 живёт **~5 минут** — ровно как QR на кассе магазина, поэтому его **нельзя напечатать и повесить на стену**: показывать нужно динамически, под конкретную покупку. Если покупатель не рядом (бронь, предоплата, доставка) — используйте счёт по номеру телефона: он живёт **24 часа** и приходит push'ем в приложение Kaspi.

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

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

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

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

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

Точке нужен минимум — устройство с интернетом и доступ к [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 (печать не работает — TTL 5 минут) | эта статья |
| Вебхук `invoice.status_changed` | Мгновенное «оплачено» без опроса статуса | [Настройка вебхуков](/guides/nastroyka-webhookov-apipay) |
| Тариф по объёму | Лимит — по числу создаваемых счетов в день | тарифы — на apipay.kz |

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

1. **Зарегистрируйтесь на apipay.kz** (вход по WhatsApp-OTP на ваш личный номер) и подключите номер кассира способом 1 — «Настройки → Авторизация Kaspi».
2. **Проверьте всё в песочнице**: QR-счёт в sandbox поддерживает `simulate: paid|cancelled|expired` — можно прогнать все исходы без реальных денег.
3. **Подключите вебхук**: укажите URL и секрет, проверяйте подпись `X-Webhook-Signature: sha256=<hex>` по сырому телу запроса.
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 истекает через ~5 минут (`qr_expires_at`). После истечения — кнопка «Создать новый QR», а не ожидание.
6. **Выдавайте товар только по вебхуку `paid`**, а не по слову «я оплатил».

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

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

- QR живёт ~5 минут и не продлевается — это устройство платёжного QR Kaspi, как на терминале.
- [Счёт по номеру телефона](/invoice-by-phone) живёт **24 часа**, приходит push'ем в приложение Kaspi, а из него можно получить и платёжную ссылку для WhatsApp — она проживёт те же 24 часа.
- Технически QR всегда вторичен от счёта: сначала создаётся счёт, из него получается QR. Поэтому оба инструмента живут в одном API и одном кабинете.

В вебхуке об оплате приходят поля `kaspi_source_type` (чем оплатили: Gold, Red, кредит/рассрочка, бизнес-счёт) и `kaspi_sale_type` (Remote/QR/Static/Restaurant) — офлайн-точкам это полезно для сверки и аналитики по способам оплаты.

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

1. **Напечатанный QR = мёртвый QR.** Через 5 минут наклейка на кассе перестанет работать, покупатели увидят «Попробуйте позже». Только динамический показ под конкретную оплату.
2. **«Попробуйте позже» — это не сбой.** Почти всегда это истёкший QR: создайте новый. Паниковать и ждать бесполезно — подробно в [статье о TTL QR](/guides/qr-schet-ttl-i-limity).
3. **QR-ссылку нельзя «отправить на потом»** в мессенджер: пока клиент откроет сообщение, она истечёт. Для отправки ссылок — счёт по номеру (24 часа).
4. **Антипаттерн «выставлю счета на свой личный номер, чтобы ссылки жили 24 часа»** — не делайте так: массовое выставление счетов самому себе — антипаттерн и повод для блокировки. Выставляйте счета реальным покупателям.
5. **Описание QR-счёта — до 100 символов** (у счёта по номеру — до 500). Длинное описание API отклонит.
6. **Забытая песочница.** Если оплаты «не проходят» сразу после подключения — проверьте, что включён рабочий режим, а не sandbox.

## Пример: розничная точка без терминальной очереди

Разберём типовой сценарий розничной точки (например, шоурума), где покупатель выбирает товар с менеджером и оплачивает на месте. Частая первая мысль владельца — повесить один общий QR на стойке. Так делать нельзя: QR живёт 5 минут, как на терминале, и печатать его бессмысленно. Правильная механика — менеджер в момент оплаты создаёт QR под конкретный заказ и показывает его с планшета. Отдельная ситуация — когда покупатель хочет оплатить позже и удалённо (например, из дома после замера). В этом случае подойдёт счёт по номеру телефона: он приходит push'ем в приложение Kaspi и даёт 24 часа на оплату. Итог: QR на планшете для зала и счета по номеру для предоплат — обе механики работают из одного кабинета ApiPay, и точка обходится без покупки терминала под этот поток.

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

**Можно ли распечатать QR и повесить у кассы?**
Нет. QR-счёт живёт ~5 минут и создаётся под конкретную сумму. Статического «QR навсегда» в ApiPay нет — показывайте QR динамически на экране в момент оплаты.

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

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

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

**Берёт ли ApiPay процент с оплат на точке?**
Нет, модель — фиксированная подписка с лимитом создаваемых счетов в день; деньги покупателей идут напрямую на ваш Kaspi-счёт. Цифры тарифов — на apipay.kz.

---

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