Коротко
Эта страница — справочник. Встретили в документации или в кабинете незнакомое слово — ищите здесь. Термины сгруппированы: сначала основные понятия, затем виды счетов, технические термины, деньги и чеки, в конце — про подписки и тарифы.
Основные понятия
Кассир — роль с ограниченными правами в Kaspi Pay: выставлять счета, видеть их статус, делать возврат по своим счетам. Через эту роль мы и работаем. Пример: в приложении Kaspi Pay Настройки → Сотрудники → Добавить сотрудника, роль «Кассир».
Привязка (подключение) — состояние, когда номер кассира связан с нашим сервисом. В разделе Kaspi каждая привязка показана отдельной карточкой. Если привязка оборвалась, создание счетов останавливается.
API-ключ — секретная строка, которой ваша программа говорит нам «я пришла от имени такой-то организации». Передаётся в заголовке X-API-Key. Пример: qp_live_… или qp_test_…. Ключ должен лежать только на сервере — ни в браузерном коде, ни в мобильном приложении.
Scope (право доступа) — что именно ключу разрешено. Их шесть: invoices:read, invoices:write, refunds:write, subscriptions:manage, webhooks:manage, partner:manage. Пример: ключу для выгрузки отчётов дайте только invoices:read — он не сможет ни создать счёт, ни сделать возврат.
Sandbox (песочница, тестовый режим) — всё как в бою, но Kaspi не вызывается и деньги не двигаются. Ключ вида qp_test_…. Пример: собираете интеграцию в песочнице и сами симулируете оплату.
Live (боевой режим) — настоящий Kaspi QR и настоящие деньги. Ключ вида qp_live_…. В каком вы режиме, написано вверху кабинета.
Счёт и его виды
Счёт (invoice) — запись о том, что с покупателя запрошена определённая сумма. У неё есть идентификатор, сумма, статус и страница оплаты. Статусы: new → pending → paid / cancelled / expired.
QR-счёт — счёт, который покупатель оплачивает, отсканировав QR или открыв ссылку. Тип по умолчанию. Описание до 100 символов. Пример: показываете QR на экране у кассы.
Счёт на телефон — счёт, который приходит прямо в приложение Kaspi покупателя; нужен его номер (7XXXXXXXXXX). Описание до 60 символов, сумма — целые тенге. Пример: приняли заказ по телефону и сразу отправили счёт.
Ссылка на оплату — постоянная ссылка многоразового использования вида qut.kz/p/<slug>. Каждое открытие создаёт новый счёт. Пример: кладёте её в профиль Instagram или печатаете QR и клеите на кассе.
Открытая сумма — в ссылке сумма не зафиксирована, покупатель вводит её сам. Можно задать минимум и максимум. Пример: «поддержать проект» или услуга, стоимость которой заранее неизвестна.
Технические термины
Webhook — уведомление, которое мы отправляем на ваш сервер, когда меняется статус оплаты. Адрес указывается в разделе Интеграции. Пример: пришло invoice.paid — помечаете заказ оплаченным.
Секрет webhook — ключ, которым проверяют, что уведомление действительно от нас. Показывается один раз. Подпись считается как HMAC-SHA256(secret, timestamp + "." + rawBody); проверять нужно неизменённое тело в байтах, до разбора в JSON.
Идемпотентность — свойство, при котором одно и то же действие не выполняется дважды. Если при создании счёта передать заголовок Idempotency-Key, повторный запрос с тем же ключом не создаст новый счёт, а вернёт прежний. Пример: оборвалась связь, запрос ушёл повторно — покупателю не прилетят два счёта.
externalOrderId — ваш собственный номер заказа. Если записать его в счёт, он вернётся в webhook и по нему можно искать в кабинете. Пример: "externalOrderId": "1001".
metadata — произвольный JSON, который вы прикрепляете к счёту. Нам он ничего не значит, вам — пригодится. Пример: {"table": "12", "waiter": "Асан"}.
Poller — наш механизм, который опрашивает Kaspi, оплачен счёт или нет. Работает каждые 3 секунды, свежие счета проверяются чаще. На практике после оплаты webhook обычно приходит в течение 5 секунд.
Деньги, возвраты, чеки
Возврат (refund) — возврат денег покупателю по оплаченному счёту. POST /api/v1/invoices/{id}/refund, в кабинете — кнопка Возврат.
Частичный возврат — возврат только части суммы. Счёт переходит в статус partially_refunded. Пример: в заказе на 10 000 ₸ не оказалось одной позиции, возвращаете 2 500 ₸.
Чек — чек на нашей странице оплаты, покупатель открывает его по ссылке. Удобен для учёта, но фискальным документом не является.
Фискальный чек — документ, которого требует налоговая. Если у вас включена Kaspi Касса, чек по удалённой оплате Kaspi выпускает сам и отправляет покупателю. Обязанность выдать чек лежит на продавце: мы деньги не держим и поэтому не можем выдать чек от вашего имени.
Поздняя оплата — ситуация, когда деньги приходят по уже закрытому (cancelled или expired) счёту. В этом случае событие invoice.paid может прийти позже с пометкой late: true. Нужно либо оказать услугу, либо вернуть деньги.
Подписки и тарифы
Подписка (subscription) — автоматическое выставление счетов по расписанию: с периодом в день, неделю или месяц. Деньги со счёта клиента сами не уходят — подписка только создаёт счёт, а оплату покупатель каждый раз подтверждает сам. Пример: абонемент в спортзал, счёт раз в месяц.
Тариф — месячная плата за наш сервис: Старт 4 990 ₸, Бизнес 14 900 ₸, Про 39 900 ₸. Процент с транзакции мы не берём.
Месячный лимит — число счетов, входящих в тариф (например, 4 000 в месяц на Бизнесе). Считается по календарному месяцу, по времени Алматы. При достижении API возвращает ошибку tariff_limit_reached.
Суточная защита — предел числа счетов за сутки (200 на Старте, 1 500 на Бизнесе, 5 000 на Про). Это не бизнес-лимит, а защита от интеграции, ушедшей в цикл. Ошибка — tariff_daily_burst, не путайте её с ошибкой месячного лимита.
Вопросы и ответы
Песочница и тестовый режим — это одно и то же? Да, два названия одного и того же.
Кассир и сотрудник — это одно? Нет. Кассир — роль в Kaspi Pay. Сотрудник — человек, приглашённый в наш кабинет, он входит со своего номера.
Где нужна идемпотентность? При создании счёта (чтобы не появились дубли) и при обработке webhook (чтобы одно событие, пришедшее дважды, не привело к двум отгрузкам).
Термина здесь нет? Напишите в поддержку: WhatsApp +7 778 881 3333, Telegram @qutpaybot. Часто спрашиваемое добавим на эту страницу.