Алфавитный указатель
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-кода, который покупатель сканирует камерой и оплачивает — без ввода номера телефона. В отличие от счёта по номеру, живёт недолго: окно на скан — меньше трёх минут. Удобно для офлайн-точки. Подробнее: QR-счёт: TTL и лимиты.
<a id="vebhuk"></a>Вебхук
Автоматическое уведомление, которое ApiPay сам присылает на ваш адрес, когда со счётом что-то происходит (оплачен, отменён, истёк). Как звонок в дверь: не вы бегаете проверять — вам сообщают, когда событие случилось. Противоположность — поллинг. Подробнее: Настройка вебхуков.
<a id="vebhuk-sekret"></a>Вебхук-секрет
Пароль, которым ApiPay «подписывает» каждый вебхук, чтобы вы могли убедиться, что уведомление пришло действительно от нас, а не от постороннего. Подробнее: API-ключ и вебхук-секрет.
<a id="idempotentnost"></a>Идемпотентность
Защита от двойного счёта: если вы передадите один и тот же ключ заказа (external_order_id_idempotency), пока прежний счёт жив, ApiPay не создаст второй счёт, а вернёт данные уже созданного — по ним и работайте дальше. Если прежний счёт уже истёк, отменён или завершился ошибкой, тот же ключ создаст новый счёт. Подробнее: Как создать счёт.
<a id="kassir"></a>Кассир
Роль сотрудника в Kaspi Pay с минимальными правами: выставить счёт, посмотреть статус, сделать возврат по своим счетам. Через эту роль работает ApiPay — как сотрудник за кассой, только вместо человека счета выставляет программа. Кассир не имеет доступа к вашим деньгам. Подробнее: Требования к номеру кассира.
<a id="korzina"></a>Корзина / cart_items
Список позиций счёта (товар, количество, цена) — то, из чего складывается сумма. У организации с каталогом (Kaspi Касса / ОФД) корзина обязательна для QR-счетов, а счёт по номеру проходит и одной суммой. Подробнее: Счёт с корзиной.
<a id="lichnyy-nomer"></a>Личный номер
Ваш номер телефона для входа в кабинет apipay.kz (подтверждение приходит в WhatsApp) и для получения уведомлений. Это не номер кассира и не номер покупателя — три разных номера, которые часто путают. Подробнее: Вход в кабинет.
<a id="menedzher"></a>Менеджер
Сотрудник, которого вы приглашаете в свой кабинет ApiPay, чтобы он мог смотреть и создавать счета, — до 10 менеджеров на организацию. Менеджер работает в кабинете, но не является отдельным кассиром 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>Поллинг
Способ узнавать статус счёта повторными запросами GET /invoices/{id}. Разрешён, но статус меняется не мгновенно, поэтому вебхуки дешевле и быстрее. Противоположность — вебхук. Частота запросов — Лимиты и квоты ApiPay.
<a id="rabochiy-rezhim"></a>Рабочий режим
Боевой режим, где счета реальные и покупатели платят настоящими деньгами. Противоположность песочнице — что происходит при переключении, см. выше в термине «Песочница».
<a id="sessiya-kassira"></a>Сессия кассира
Активное «подключение» кассира к Kaspi — как открытый сеанс в приложении. Пока сессия жива, ApiPay может выставлять счета. Под номером кассира не входите в приложение Kaspi Pay для бизнеса; если привязка оборвалась — переподключите её за минуту. Подробнее: Привязка кассира разорвалась.
<a id="sposob-1"></a>Способ 1 / авторизация «Кассир»
Самостоятельное подключение кассира за минуту: кабинет ApiPay → Настройки → «Авторизация Kaspi» → ввод SMS-кода. Подробнее: Настройка ApiPay за 15 минут.
<a id="schet-po-nomeru"></a>Счёт по номеру
Счёт, который приходит покупателю прямо в приложение Kaspi по номеру телефона — покупателю остаётся нажать «Оплатить». Живёт в Kaspi 24 часа, описание — до 60 символов: Kaspi показывает покупателю только первые 60. Подробнее: Как создать счёт Kaspi по номеру.
Частые вопросы
Чем кассир отличается от менеджера?
Кассир — это роль в Kaspi (держатель Kaspi-сессии, через которую счёт уходит в Kaspi). Менеджер — сотрудник в кабинете ApiPay, который создаёт счета из кабинета, но своего Kaspi-входа не держит. Два человека, которые просто хотят вести один кабинет, — это менеджеры, а не два кассира.
Чем API-ключ отличается от вебхук-секрета?
API-ключ вы отправляете в ApiPay, чтобы создавать счета (исходящее направление). Вебхук-секрет — наоборот: им ApiPay подписывает уведомления вам, чтобы вы проверили подлинность (входящее направление). Это два разных секрета.