Ресторан и кафе

Коротко

В ресторане есть две разные вещи: постоянная ссылка (QR, который печатают на стол, сумма открытая) и динамический счёт (выставляется на кассе на точную сумму чека). Повседневная работа строится на втором: официант закрывает чек, на экране кассы или планшета появляется QR, гость сканирует его приложением Kaspi, и примерно через 5 секунд ваша система получает webhook об оплате и закрывает чек. Деньги идут напрямую на ваш счёт в Kaspi.

Сценарий за столом

Официант закрывает чек в POS, сумма — 14 300 ₸.
Ваша система отправляет POST /api/v1/invoices: amount: 14300, description: "Чек №418, стол 6", externalOrderId: "418".
В ответе приходят qrImageUrl и expiresAt. QR выводится на экран кассы, планшет или печатается на чековом принтере.
Гость сканирует приложением Kaspi и платит.
Приходит webhook invoice.paid. POS закрывает чек как оплаченный, стол освобождается.

Окно сканирования QR — около трёх минут, его задаёт Kaspi. Точное время берите из поля expiresAt, не зашивайте константу. Если гость не успел, выставляете новый счёт — это нормальная ситуация, а не сбой.

QR на столе и QR на кассе

Это две разные вещи, их легко перепутать.

	Печатный QR на столе	QR на кассе или планшете
Что это	Ссылка на оплату `qut.kz/p/<slug>` в виде QR	Kaspi QR конкретного счёта
Сумма	Открытая, гость вводит сам	Точная сумма чека
Срок	Постоянный, живёт месяцами	Около трёх минут
Когда удобно	Чайханы, фудкорт, быстрое обслуживание, чаевые	Зал с полным обслуживанием
Риск	Гость введёт неверную сумму	Окно истекло — нужен новый счёт

Многие заведения держат оба варианта: в зале — динамический QR с кассы, а на столах постоянная ссылка для чаевых и быстрой оплаты.

Счёт на сумму чека

POST /api/v1/invoices
{
  "amount": 14300,
  "kind": "qr",
  "description": "Чек №418, стол 6",
  "externalOrderId": "418",
  "metadata": { "table": "6", "waiter": "aigerim", "shift": "evening" }
}

description видит гость, для QR-счёта это максимум 100 символов. Пишите туда то, что понятно гостю: номера чека и стола достаточно. Перечислять блюда не нужно.

Отправляйте заголовок Idempotency-Key. Если официант дважды нажал «Показать QR» или запрос ушёл повторно из-за обрыва Wi-Fi, с тем же ключом новый счёт не создастся — вернётся прежний.

Раздельная оплата

Один счёт Kaspi не делится между несколькими плательщиками. Поэтому раздельная оплата — это несколько отдельных счетов.

Делите чек в POS: 14 300 ₸ → 7 150 + 7 150 или по позициям.
На каждую часть создаёте свой счёт со своим externalOrderId: 418-1, 418-2.
В metadata кладёте общий номер чека: { "bill": "418" } — потом по нему части собираются в одну группу в отчёте.
Части платятся независимо, на каждую приходит свой invoice.paid. Закрывайте чек только когда оплачены все.

Если одна часть оплачена, а вторая нет — незакрытую отменяете через POST /api/v1/invoices/{id}/cancel и выставляете остаток заново.

Учёт по официантам

Два рабочих способа.

Простой — metadata. В каждый счёт пишете metadata.waiter. Потом группируете по этому полю в выгрузке CSV или через GET /api/v1/invoices. Никакой отдельной настройки не нужно, смена одного человека считается за минуту.

Строгий — отдельный API-ключ. Для каждой кассы или точки заводите свой ключ и привязываете его к кассиру. Боевые счета такого ключа идут только через этого кассира, чужих счетов он не видит. Это удобно сети с несколькими залами: Раздельная отчётность по точкам.

Одному заведению обычно хватает metadata, отдельные ключи нужны филиалам.

Заказы на доставку

В доставке момент оплаты другой: при приёме заказа или у двери.

Предоплата. Оператор принимает заказ и отправляет счёт kind: "phone" — гостю приходит push в Kaspi. customer.phone в формате 7XXXXXXXXXX. Учтите: description здесь не длиннее 60 символов.
Оплата при доставке. Курьер выставляет счёт со своего телефона либо диспетчер выставляет и передаёт QR курьеру. Курьеру в Kaspi заходить не нужно, он только показывает QR.
Передавайте заказ на кухню после invoice.paid, а не в момент создания счёта.

Подробнее: Служба доставки.

Если у гостя нет приложения Kaspi

Встречается редко, но встречается. Главное помнить: счёт по телефону (kind: "phone") до такого гостя не дойдёт — push приходит в приложение Kaspi, а его нет.

Что делать:

Показать QR другому человеку за столом — спутник платит, между собой они рассчитываются сами.
Отправить ссылку payUrl в WhatsApp: она открывается в браузере.
Дальше — обычный порядок вашей кассы: наличные или карта. Qut Pay в этом случае не участвует.

Подробно: У покупателя нет приложения Kaspi.

Вариант без кода

Начать можно и без программиста:

Вручную из кабинета. В разделе Счета вводите сумму и описание, получаете QR. Достаточно компьютера или планшета на кассе.
Telegram-бот. С телефона официанта: /invoice 14300 Чек 418 — в ответ QR. /today — итог смены, /last — последние счета.
Постоянные ссылки. Их печатают на стол или на дверь, сумма открытая.
n8n. Если ваш POS умеет отдавать webhook, счёт можно выставлять автоматически через готовый сценарий, не написав ни строки кода.

Что учесть заранее

Не заходите в приложение Kaspi Pay с номера кассира. Kaspi разрешает одному кассиру только одно активное устройство: в момент входа наша привязка обрывается, и выставление счетов останавливается посреди вечернего зала. Это самая частая авария: Привязка кассира оборвалась.
Бывают поздние оплаты. Даже после того, как счёт стал expired, деньги могут прийти, и событие invoice.paid придёт с пометкой late: true. Если гость уже ушёл — делаете возврат: Поздняя оплата.
Номер кассира виден гостю в уведомлении о счёте. Так работает Kaspi, это нормально.
Фискальный чек — отдельный вопрос, Qut Pay его не решает: Фискальный чек.
Тариф считайте по числу чеков. 30 чеков в день — это около 900 счетов в месяц, то есть тариф Бизнес. Как считать: Какой тариф выбрать.

Вопросы и ответы

Можно напечатать отдельный QR на каждый стол? Можно, но это будет ссылка с открытой суммой — гость вводит её сам. Если нужна точная сумма чека, выставляйте динамический счёт с кассы.

Как принимать чаевые отдельно? Вторым счётом или ссылкой с открытой суммой. Сумму уже созданного счёта гость изменить не может.

Выставил счёт с неверной суммой — что делать? Если он не оплачен, отмените и выставьте правильный. Если оплачен — сделайте полный или частичный возврат.

Что будет, если пропадёт интернет? Для создания QR интернет нужен. Без связи работаете по обычному порядку кассы, после восстановления счёт выставляется заново.

У нас несколько филиалов, отчётность не перемешается? Заведите каждому филиалу свой ключ и привяжите к своему кассиру — счета и отчёты будут раздельными: Раздельная отчётность по точкам.

Qut Pay — независимый сервис, не аффилирован с АО «Kaspi Bank». Kaspi и Kaspi Pay — товарные знаки их правообладателя.