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

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

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

ApiPay работает по механике счёта на номер покупателя: автомату не нужен экран под QR, покупатель подтверждает оплату в своём телефоне.

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

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

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

1. Подключите первую организацию: регистрация на apipay.kz, номер кассира, 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. Масштабирование на точки: внутри одного юрлица добавляйте кассиров в ту же организацию и передавайте kaspi_connection_id в каждом POST /invoices — ключ, вебхук и тариф остаются общими. Отдельное юрлицо (второй ИП) — отдельная организация со своим кассиром, ключом, вебхуком и тарифом (несколько организаций).

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

1. Частота выставления счетов. Потолок по объёму — дневной лимит тарифа организации, счета из кабинета в него не входят (см. Лимит счетов по тарифу). При систематическом превышении POST /invoices начинает отдавать 429 tariff_limit_reached — обработайте этот код в ПО автомата и покажите покупателю «оплата временно недоступна».
2. Покупатель ушёл, не оплатив. Счёт живёт 24 часа — он может «догнать» покупателя позже, когда товар уже никто не ждёт. Решение: короткий таймер сессии и выдача только по вебхуку, привязанному к конкретному счёту.
3. Выдача по слову «оплатил». У автомата некому проверить — только вебхук paid, ничего другого.
4. Каталог и скидки. Если нужен состав покупки в чеке (Kaspi ОФД) — cart_items обязателен; при своих ценах/скидках надёжнее передавать price позиции явно и считать скидки на своей стороне.
5. Одна организация = одно юрлицо (ИП/ТОО), кассиров в ней может быть несколько. Если активных кассиров больше одного и primary не задан, запрос без kaspi_connection_id вернёт 422 connection_ambiguous. SIM считайте по числу торговых точек, тарифы — по числу организаций.
6. Оплата прошла, товар не выдан. Автомат заклинило или слот пуст — деньги уже на вашем Kaspi-счёте, автоматического отката нет: возврат делаете вы, POST /invoices/{id}/refund (как устроены возвраты).

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