Как это работает у вас
Клиент платформы (например, садик) регистрируется в ApiPay → даёт вам код с номера кассира → у вас в базе появляется его API-ключ → ваша платформа выставляет счета родителям от имени садика → родитель получает push в Kaspi → оплатил → ApiPay шлёт вебхук на ваш URL → вы отмечаете оплату в своей системе.
Деньги при этом идут напрямую на Kaspi-счёт садика: схема «собрать всё на счёт платформы и потом распределить» в ApiPay не поддерживается. ApiPay берёт фиксированную подписку с каждой организации, не процент с оборота.
Три модели денег — выберите свою
| Модель | Кто получает деньги | Когда подходит |
|---|---|---|
| Каждый клиент на свой счёт | Под-бизнес | Основная модель: вы — софт, деньги не ваши |
| Всё от вашего счёта | Вы (платформа) | Услуга по сути ваша, клиенты — подрядчики |
| От бизнеса + постоплата вам | Под-бизнес, вы выставляете ему счёт за период | Агрегаторы: платежи от ресторана, в конце месяца — ваш счёт за сервис |
Компоненты ApiPay для платформы
Платформа получает полный Kaspi API и инструменты мультиаккаунта:
| Компонент | Зачем платформе |
|---|---|
API-ключ на организацию (X-API-Key) |
Вы храните ключи всех клиентов и подставляете нужный при выставлении счёта |
| Вебхуки per-key | Свой webhook_url на каждую организацию — статусы оплат прилетают в вашу систему |
Partner API (X-Partner-Key) |
Программное подключение клиентов: создание организаций, привязка кассира, выпуск ключей — без ручного онбординга |
| Мультиорганизации | Один клиент с несколькими юрлицами/точками = несколько организаций |
| Партнёрская программа | Вознаграждение за каждого приведённого клиента, пока тот платит; условия — индивидуально |
| Песочница | Отладка всей мульти-клиентской логики без реальных денег |
Важно про биллинг: каждая организация = отдельный тариф, лимиты не суммируются — ключевой момент для мультиорганизационных схем.
Пошаговый сетап
- Зарегистрируйте свой аккаунт на apipay.kz и изучите модель на одной организации (своей) в песочнице — см. «Песочница и рабочий режим».
- Выберите модель денег из трёх выше и зафиксируйте её в оферте с клиентами.
- Подключите первого клиента вручную: он регистрируется в ApiPay, заводит номер кассира (требования — в этой статье) и передаёт вам API-ключ.
- Постройте хранилище ключей: таблица «организация клиента → API-ключ → webhook-секрет», ключ подставляется в каждый запрос выставления счёта.
- Настройте вебхуки на каждую организацию — свой URL или один общий с маршрутизацией по подписи/ключу.
- Переходите на Partner API, когда клиентов станет больше нескольких: заявка в партнёрском разделе сайта →
X-Partner-Key→ создание организаций и привязка кассира программно. Ключ работает в песочнице сразу, боевые операции — после перевода партнёра в production, и этот перевод удаляет все тестовые организации партнёра: не держите в песочнице ничего, что жалко потерять. Порядок перевода, лимиты песочницы и коды ошибок — Партнёрский API и white label. - Подключите партнёрскую программу, чтобы возвращать себе часть тарифа клиентов — условия обсудим при подключении, напишите нам.
Грабли именно платформ
- От чьего имени уходит счёт. От той организации, чей API-ключ подставлен в запрос. В уведомлении покупатель видит номер кассира этой организации; что Kaspi показывает рядом — не в нашем контроле.
- Клиент сам пользуется номером кассира. Если сотрудник клиента заходит в приложение Kaspi Pay под номером кассира — привязку приходится подключать заново, счета встают (Почему слетела сессия кассира). Правило для всех клиентов платформы: номер кассира — отдельная SIM, в неё никто не заходит.
- Что действительно owner-only. Удаление организации, управление менеджерами и регенерация API-ключей. Создать организацию может любой пользователь аккаунта. Отдельный гард на кассиров — per-key флаг
can_manage_cashiers, по умолчанию выключен: без него/api/v1/connections*отдаёт403 cashier_management_disabled. - Несколько точек = несколько кассиров. 1 номер кассира может быть только в 1 точке продаж: у клиента 5 филиалов — 5 номеров. Все они живут внутри одной организации (несколько подключений, одно из них primary) — как при этом считается оплата, разобрано в «Два кассира на организацию».
- Подключение кассира может не пройти, и причину вам не покажут. И партнёрская, и мерчантская ветка на конфликте отвечают нейтральным отказом: различить причину программно нельзя, повтор не помогает — ведите клиента на другой номер или в поддержку. Есть и суточный лимит на новые номера кассиров, так что массовый онбординг растягивайте по дням. Разбор — Подключение организации партнёром.
- Развилка «один счёт или раздельные»: если клиенту нужны деньги на каждое юрлицо отдельно — это 2 кассира и 2 тарифа; если на один счёт, но с разделением потоков — 2 API-ключа и 2 вебхука внутри 1 организации.
- Партнёрский нюанс ключей: повторный выпуск ключа саб-мерчанта через Partner API перегенерирует ключ — старый мгновенно перестаёт работать. Обновляйте ключ в своей базе атомарно.
Частые вопросы
Проходят ли деньги через платформу?
Нет. Деньги идут с Kaspi покупателя на Kaspi-счёт вашего клиента напрямую — платформа только выставляет счета по его API-ключу.
Сколько это стоит клиентам платформы?
Каждая организация платит свой фиксированный тариф ApiPay, без процента с оборота — суммы и лесенка в статье Тарифы и комиссия. Платить может и сама платформа: по X-Partner-Key доступны состояние подписки клиента, её оплата и выставление счёта на оплату.
Что если клиент уйдёт с платформы?
Его организация в ApiPay — его собственность: аккаунт, ключи и деньги остаются у него. Вы просто перестаёте выставлять счета от его имени.