Алфавитный указатель
ApiPay · API-ключ · Kaspi Pay · QR-счёт · Вебхук · Вебхук-секрет · Идемпотентность · Кассир · Корзина / cart_items · Личный номер · Менеджер · Номер кассира · Организация · Песочница · Подписка · Поллинг · Рабочий режим · Сессия кассира · Способ 1 / авторизация «Кассир» · Счёт по номеру
Термины
<a id="apipay"></a>ApiPay
Независимый сервис, который автоматизирует выставление счетов через ваш Kaspi Pay. Деньги покупателей идут напрямую на ваш Kaspi-счёт — ApiPay к ним не прикасается, а берёт фиксированную подписку, а не процент с оборота. Подробнее о модели работы — «Как принимать оплату Kaspi через API».
<a id="api-klyuch"></a>API-ключ
Секретная строка, которой ваша программа «представляется» ApiPay при каждом запросе — передаётся в заголовке X-API-Key. Как логин и пароль в одном, только для кода: кто знает ключ — может выставлять счета от вашего имени, поэтому его не публикуют. Подробнее: API-ключ и вебхук-секрет.
<a id="kaspi-pay"></a>Kaspi Pay
Приложение и кабинет Kaspi для бизнеса, через которые проходят платежи и где предприниматель добавляет сотрудников — в том числе кассира с ролью «Кассир». В наших текстах это единый термин «Kaspi Pay» (кабинет юрлица и мобильное приложение). ApiPay работает поверх вашего Kaspi Pay — как надстройка, которая делает рутину за вас.
<a id="qr-schet"></a>QR-счёт
Счёт в виде QR-кода, который покупатель сканирует камерой и оплачивает — без ввода номера телефона. В отличие от счёта по номеру, живёт недолго: около 5 минут, описание — до 100 символов. Удобно для офлайн-точки. Подробнее: QR-счёт: TTL и лимиты.
<a id="vebhuk"></a>Вебхук
Автоматическое уведомление, которое ApiPay сам присылает на ваш адрес, когда со счётом что-то происходит (оплачен, отменён, истёк). Как звонок в дверь: не вы бегаете проверять — вам сообщают, когда событие случилось. Противоположность — поллинг. Подробнее: Настройка вебхуков.
<a id="vebhuk-sekret"></a>Вебхук-секрет
Пароль, которым ApiPay «подписывает» каждый вебхук, чтобы вы могли убедиться, что уведомление пришло действительно от нас, а не от постороннего. Подпись передаётся в заголовке X-Webhook-Signature: sha256=<hex> и проверяется по «сырому» телу запроса. Подробнее: API-ключ и вебхук-секрет.
<a id="idempotentnost"></a>Идемпотентность
Защита от двойного счёта: если вы передадите один и тот же ключ заказа (external_order_id_idempotency), ApiPay не создаст второй счёт, а вернёт ссылку на уже существующий (ответ 409). Как штрих-код на товаре — сколько ни сканируй, товар один. Подробнее: Как создать счёт.
<a id="kassir"></a>Кассир
Роль сотрудника в Kaspi Pay с минимальными правами: выставить счёт, посмотреть статус, сделать возврат по своим счетам. Через эту роль работает ApiPay — как сотрудник за кассой, только вместо человека счета выставляет программа. Кассир не имеет доступа к вашим деньгам. Подробнее: Требования к номеру кассира.
<a id="korzina"></a>Корзина / cart_items
Список позиций счёта (товар, количество, цена) — то, из чего складывается сумма. С 9 июня 2026 корзина при фискализации (ОФД) не обязательна: сумму можно передать и без позиций, в том числе при подключённой Kaspi Кассе. Подробнее: Счёт с корзиной.
<a id="lichnyy-nomer"></a>Личный номер
Ваш номер телефона для входа в кабинет apipay.kz (подтверждение приходит в WhatsApp) и для получения уведомлений. Это не номер кассира и не номер покупателя — три разных номера, которые часто путают. Подробнее: Вход в кабинет.
<a id="menedzher"></a>Менеджер
Сотрудник, которого вы приглашаете в свой кабинет ApiPay, чтобы он мог смотреть и создавать счета, — до 5 менеджеров на организацию. Менеджер работает в кабинете, но не является отдельным кассиром Kaspi. Приглашает только владелец.
<a id="nomer-kassira"></a>Номер кассира
Отдельный реальный номер с ролью «Кассир», который вы добавляете в Kaspi Pay и через который ApiPay подключается к Kaspi. Не должен быть привязан к ИП/ТОО в Kaspi Pay. Используется только для одной привязки. Подробнее: Требования к номеру кассира.
<a id="organizatsiya"></a>Организация
Ваш «профиль бизнеса» в ApiPay: у каждой организации свой тариф, свой Kaspi-вход, свой список счетов и свои деньги. В одном аккаунте можно вести несколько организаций — для разных брендов или раздельной отчётности. Подробнее: Раздельная отчётность по точкам.
<a id="pesochnitsa"></a>Песочница
Тестовый режим, где счета создаются «понарошку» — без реальных денег, чтобы вы могли всё проверить перед запуском. Песочница бесплатна всегда. При переходе в рабочий режим тестовые данные и ключи удаляются. Подробнее: Песочница и рабочий режим.
<a id="podpiska"></a>Подписка
Регулярный счёт, который ApiPay выставляет клиенту сам по расписанию (раз в месяц и т.п.). Важно: это не автосписание с карты — клиент каждый раз оплачивает счёт в приложении Kaspi сам. Подробнее: Подписки ApiPay.
<a id="polling"></a>Поллинг
Способ узнавать статус счёта, постоянно переспрашивая ApiPay «ну что, оплатили?». Работает, но грузит систему и упирается в лимиты — поэтому вместо поллинга лучше подключить вебхуки, которые сообщают об оплате сами. Подробнее: Настройка вебхуков.
<a id="rabochiy-rezhim"></a>Рабочий режим
Боевой режим, где счета реальные и покупатели платят настоящими деньгами. Противоположность песочнице. Переход в рабочий режим удаляет тестовые организации и деактивирует тестовые ключи — «чистый старт». Подробнее: Песочница и рабочий режим.
<a id="sessiya-kassira"></a>Сессия кассира
Активное «подключение» кассира к Kaspi — как открытый сеанс в приложении. Пока сессия жива, ApiPay может выставлять счета. Под номером кассира не входите в приложение Kaspi Pay для бизнеса; если привязка оборвалась — переподключите её за минуту. Подробнее: Почему слетала сессия кассира.
<a id="sposob-1"></a>Способ 1 / авторизация «Кассир»
Самостоятельное подключение кассира за минуту: кабинет ApiPay → Настройки → «Авторизация Kaspi» → ввод SMS-кода. При подключении этим способом даётся 3 дня бесплатного доступа. Подробнее: Настройка ApiPay за 15 минут.
<a id="schet-po-nomeru"></a>Счёт по номеру
Счёт, который приходит покупателю прямо в приложение Kaspi по номеру телефона — покупателю остаётся нажать «Оплатить». Живёт в Kaspi 24 часа, описание — до 500 символов. Подробнее: Как создать счёт Kaspi по номеру.
Частые вопросы
Чем кассир отличается от менеджера?
Кассир — это роль в Kaspi (держатель Kaspi-сессии, через которую счёт уходит в Kaspi). Менеджер — сотрудник в кабинете ApiPay, который создаёт счета из кабинета, но своего Kaspi-входа не держит. Два человека, которые просто хотят вести один кабинет, — это менеджеры, а не два кассира.
Чем API-ключ отличается от вебхук-секрета?
API-ключ вы отправляете в ApiPay, чтобы создавать счета (исходящее направление). Вебхук-секрет — наоборот: им ApiPay подписывает уведомления вам, чтобы вы проверили подлинность (входящее направление). Это два разных секрета.
Подписка — это автосписание с карты?
Нет. Подписка в ApiPay — это авто-выставление счёта по расписанию; оплачивает каждый счёт клиент сам в приложении Kaspi. Списать деньги с карты автоматически ApiPay не может.
Сколько всего номеров участвует в работе?
Три: личный номер (вход в кабинет), номер кассира (отдельная SIM для Kaspi) и номер покупателя (на него выставляется счёт). Их часто путают — держите роли в голове раздельно.