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

# Как вендинговому автомату принимать оплату Kaspi без терминала?

**TL;DR.** Автомату не нужен платёжный терминал: покупатель вводит свой номер Kaspi на экране автомата → ему прилетает счёт в приложение Kaspi (сумма + описание корзины) → он нажимает «Оплатить» → ApiPay шлёт вашему ПО вебхук `paid` → автомат выдаёт товар. Цикл занимает секунды. Схема рассчитана на вендинговые сети с собственным ПО и хорошо держит поток оплат на автомат. Каждая точка (ИП/организация) подключается отдельно — со своим номером кассира и своим API-ключом.

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

Флоу простой: пользователь вводит свой номер → получает счёт → оплачивает → приходит вебхук → автомат выдаёт товар.

```
Покупатель у автомата (наличных и карты нет — есть телефон с Kaspi)
        │
Экран автомата: «Введите номер телефона»
        │
ПО автомата → POST /invoices { phone_number, amount, cart_items/описание }
        │
Покупателю приходит push в Kaspi: счёт с суммой и составом покупки
        │
«Оплатить» в приложении Kaspi
        │
Вебхук invoice.status_changed: paid → контроллер автомата выдаёт товар
```

Генерация собственного QR «на сумму» на экране автомата — это сценарий официальной «Виртуальной кассы» Kaspi; ApiPay работает по другой механике — [счёт на номер покупателя](/invoice-by-phone). Для автомата она даже удобнее: не нужен экран высокого разрешения под QR, а покупатель подтверждает оплату в своём телефоне.

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

Автомату нужен выход в интернет и доступ к [Kaspi API](/kaspi-api):

| Компонент | Зачем | Где подробнее |
|---|---|---|
| ПО автомата с интернетом | Ввод номера, вызов API, приём вебхука, команда выдачи | ваше/вендора |
| Номер кассира на каждую точку | Каждая организация (ИП/точка) = свой кассир | [Требования к номеру](/guides/trebovaniya-k-nomeru-kassira) |
| API-ключ + вебхук на организацию | Ключи и вебхуки настраиваются в каждом кабинете отдельно | [Ключ и секрет](/guides/api-klyuch-i-webhook-secret) |
| Каталог/cart_items (при Kaspi ОФД) | Чтобы в чеке был состав покупки | [cart_items и 422](/guides/scheta-s-korzinoy-cart-items-ofd) |
| Тариф на организацию | Лимит — счетов в день; на лето можно даунгрейдиться | тарифы — на apipay.kz |

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

1. **Подключите первую организацию**: регистрация на apipay.kz, номер кассира способом 1 («Настройки → Авторизация Kaspi»), API-ключ и вебхук-секрет.
2. **Прогоните цикл в песочнице**: создание счёта → simulate-оплата → вебхук → команда «выдать». Отладьте выдачу до боевых денег.
3. **Экран ввода номера**: формат `8XXXXXXXXXX`; после ввода автомат вызывает:

```bash
curl -X POST https://api.apipay.kz/api/v1/invoices \
  -H "X-API-Key: КЛЮЧ_ТОЧКИ" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "8701XXXXXXX",
    "amount": 500,
    "description": "Автомат №3: кофе американо",
    "external_order_id_idempotency": "vend-3-slot-12-1720180000"
  }'
```

4. **Выдача строго по вебхуку `paid`** (подпись `X-Webhook-Signature` по raw body — [настройка](/guides/nastroyka-webhookov-apipay)). Покажите на экране «Ожидаем оплату…» и таймер: у счёта окно 24 часа, но для автомата разумно закрывать сессию через 2–3 минуты и предлагать попробовать снова.
5. **Идемпотентность обязательна**: ключ вида `автомат-слот-время` защитит от двойного счёта при сетевых ретраях контроллера; повтор вернёт `409` с данными уже созданного счёта.
6. **Масштабирование на точки**: каждая точка/ИП — отдельная организация со своим кассиром, ключом и вебхуком. Один и тот же URL вебхука можно указать в обоих кабинетах — но настроить его «в одном кабинете сразу на два» нельзя: настройка живёт в каждой организации отдельно.

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

1. **Страх «забанят за частоту».** Снят практикой: частые оплачиваемые счета — нормальный оборот. Ограничение возможно только при массовых НЕоплаченных счетах.
2. **Покупатель ушёл, не оплатив.** Счёт живёт 24 часа — он может «догнать» покупателя позже, когда товар уже никто не ждёт. Решение: короткий таймер сессии на автомате и выдача только по вебхуку, привязанному к конкретному счёту.
3. **Выдача по слову «оплатил».** У автомата некому проверить — только вебхук `paid`, ничего другого.
4. **Каталог и скидки.** Если нужен состав покупки в чеке (Kaspi ОФД) — `cart_items` обязателен; при своих ценах/скидках надёжнее передавать `price` позиции явно и считать скидки на своей стороне.
5. **Один кабинет на все точки — нельзя.** Каждая организация подключается отдельно: свой кассир, свои ключи, свой вебхук. Планируйте SIM-карты и тарифы по числу юрлиц/точек.
6. **Сезонность.** Автоматы в учебных заведениях летом простаивают — тариф можно понизить на сезон и вернуть осенью.

## Как это выглядит на практике

Типичный сценарий для сети вендинговых автоматов с собственным ПО. Часто на старте владельцы хотят выводить на экране автомата собственный QR «на сумму» — как на терминале. Но такой сценарий — это официальная «Виртуальная касса» Kaspi, отдельный продукт банка; у ApiPay механика другая: номер → счёт → оплата → вебхук → выдача. Экран автомата переделывают под ввод номера — и это оказывается удобнее: покупатель подтверждает оплату в своём телефоне, автомату не нужен платёжный экран.

Отдельно снимается частый страх «забанят за частоту запросов»: частые оплачиваемые счета — нормальный оборот, ограничение возможно только при массовых неоплаченных счетах. При этом именно вендинг раньше всего упирается в тонкости каталога и скидок — из этого опыта и выросли рекомендации пункта 4: при своих ценах передавайте `price` позиции явно и считайте скидки на своей стороне.

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

**Почему не QR на экране автомата?**
Динамический QR-счёт ApiPay живёт ~5 минут и требует экрана под QR; сценарий «QR на сумму как терминал» — это официальная «Виртуальная касса» Kaspi, отдельный продукт самого банка. Механика ApiPay для автомата — счёт на номер покупателя: проще экран, подтверждение в телефоне покупателя.

**Что если покупатель ввёл чужой/несуществующий номер?**
Счёт просто не будет оплачен (или вернётся ошибка `client_not_found`, если номера нет в Kaspi). Автомат ничего не выдаёт без вебхука `paid` — рисков нет, сессия закроется по таймеру.

**Не будет ли проблем из-за сотен счетов в день с одного кассира?**
Как правило — нет: оплачиваемые счета это нормальный оборот. Избегайте только лавин неоплаченных счетов (защита — идемпотентность и таймер сессии).

**У меня 5 автоматов на 2 ИП — сколько подключений нужно?**
По числу организаций: 2 организации = 2 кассира, 2 ключа, 2 вебхука, 2 тарифа. Автоматы одного ИП делят одну организацию; различайте их через `external_order_id`/описание.

**Можно ли принимать и наличные, и Kaspi?**
Да, ApiPay не трогает остальную обвязку автомата — это независимый сервис поверх вашего Kaspi Pay; деньги от оплат идут напрямую на Kaspi-счёт вашего ИП.

---

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