Как это работает у вас
Схема потока на точке (касса, шоурум, пункт проката, туристический офис):
Покупатель у кассы готов платить
│
Ваша касса/планшет → POST /invoices/qr (сумма + описание ≤100 симв.)
│
201: qr_image_url (готовый PNG) — показываете на экране
│
Покупатель сканирует камерой Kaspi → подтверждает оплату
│
Вебхук invoice.status_changed: status=paid → выдаёте товар/чек
Ни сайта, ни онлайн-витрины не нужно: достаточно любого устройства с интернетом, которое умеет вызвать API и показать картинку. Деньги идут напрямую на ваш Kaspi-счёт — ApiPay является независимым сервисом поверх вашего Kaspi Pay и к деньгам доступа не имеет.
Что понадобится
Точке нужен минимум — устройство с интернетом и доступ к Kaspi API:
| Компонент | Зачем | Где подробнее |
|---|---|---|
| Номер кассира (отдельная SIM) | Штатная роль «Кассир» в Kaspi Pay, через неё выставляются счета | Требования к номеру кассира |
| API-ключ | Заголовок X-API-Key при создании QR |
API-ключ и вебхук-секрет |
| Экран/планшет на точке | Динамический показ QR (печать не работает — TTL 5 минут) | эта статья |
Вебхук invoice.status_changed |
Мгновенное «оплачено» без опроса статуса | Настройка вебхуков |
| Тариф по объёму | Лимит — по числу создаваемых счетов в день | тарифы — на apipay.kz |
Пошаговый сетап
- Зарегистрируйтесь на apipay.kz (вход по WhatsApp-OTP на ваш личный номер) и подключите номер кассира способом 1 — «Настройки → Авторизация Kaspi».
- Проверьте всё в песочнице: QR-счёт в sandbox поддерживает
simulate: paid|cancelled|expired— можно прогнать все исходы без реальных денег. - Подключите вебхук: укажите URL и секрет, проверяйте подпись
X-Webhook-Signature: sha256=<hex>по сырому телу запроса. - Встройте создание 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).
- Показывайте таймер: QR истекает через ~5 минут (
qr_expires_at). После истечения — кнопка «Создать новый QR», а не ожидание. - Выдавайте товар только по вебхуку
paid, а не по слову «я оплатил».
Когда QR, а когда счёт по номеру?
Правило простое: QR — покупатель стоит рядом и платит сейчас; счёт по номеру — покупатель удалённо или «оплатит позже».
- QR живёт ~5 минут и не продлевается — это устройство платёжного QR Kaspi, как на терминале.
- Счёт по номеру телефона живёт 24 часа, приходит push'ем в приложение Kaspi, а из него можно получить и платёжную ссылку для WhatsApp — она проживёт те же 24 часа.
- Технически QR всегда вторичен от счёта: сначала создаётся счёт, из него получается QR. Поэтому оба инструмента живут в одном API и одном кабинете.
В вебхуке об оплате приходят поля kaspi_source_type (чем оплатили: Gold, Red, кредит/рассрочка, бизнес-счёт) и kaspi_sale_type (Remote/QR/Static/Restaurant) — офлайн-точкам это полезно для сверки и аналитики по способам оплаты.
Грабли этого бизнеса
- Напечатанный QR = мёртвый QR. Через 5 минут наклейка на кассе перестанет работать, покупатели увидят «Попробуйте позже». Только динамический показ под конкретную оплату.
- «Попробуйте позже» — это не сбой. Почти всегда это истёкший QR: создайте новый. Паниковать и ждать бесполезно — подробно в статье о TTL QR.
- QR-ссылку нельзя «отправить на потом» в мессенджер: пока клиент откроет сообщение, она истечёт. Для отправки ссылок — счёт по номеру (24 часа).
- Антипаттерн «выставлю счета на свой личный номер, чтобы ссылки жили 24 часа» — не делайте так: массовое выставление счетов самому себе — антипаттерн и повод для блокировки. Выставляйте счета реальным покупателям.
- Описание QR-счёта — до 100 символов (у счёта по номеру — до 500). Длинное описание API отклонит.
- Забытая песочница. Если оплаты «не проходят» сразу после подключения — проверьте, что включён рабочий режим, а не 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.