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

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

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

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

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

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

Автомату нужен выход в интернет и доступ к Kaspi API:

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

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

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 — настройка). Покажите на экране «Ожидаем оплату…» и таймер: у счёта окно 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 позиции явно и считайте скидки на своей стороне.

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