# Словарь терминов

> Часть обращений в поддержку — просто непонятый термин. Здесь 25 терминов простыми словами, к каждому одно-два предложения и пример.

## Коротко

Эта страница — справочник. Встретили в документации или в кабинете незнакомое слово — ищите здесь. Термины сгруппированы: сначала основные понятия, затем виды счетов, технические термины, деньги и чеки, в конце — про подписки и тарифы.

## Основные понятия

**Кассир** — роль с ограниченными правами в 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. Часто спрашиваемое добавим на эту страницу.