Partner API

Коротко

Partner API — набор эндпоинтов, которые позволяют интегратору вести клиентов из собственного интерфейса. Вы заводите клиенту организацию, подключаете его кассира Kaspi, выдаёте API-ключ, переводите в боевой режим и видите статистику.

Клиенту при этом не обязательно заходить в кабинет: во время подключения он только называет код, который пришёл ему из Kaspi по SMS. Остальное делаете вы.

Деньги в любом случае приходят на счёт Kaspi самого клиента — Partner API этого не меняет.

Кому это нужно

Доступ выдаётся не всем: есть два условия.

Условия доступа

1. Ваша организация должна быть на тарифе «Партнёр». Этот тариф ставит платформа, самостоятельно в кабинете переключиться нельзя — напишите в поддержку
2. У вашего API-ключа должен быть scope partner:manage

Без этого эндпоинты /partner/... отвечают insufficient_scope (403). О правах: Права доступа (scopes).

Эндпоинты

Всё от базы https://api.qut.kz/api/v1, с заголовком X-API-Key.

1. Завести организацию клиенту

POST /api/v1/partner/organizations
X-API-Key: qp_live_…

{
  "name": "Магазин «Алтын»",
  "ownerPhone": "77011234567",
  "ownerName": "Асхат",
  "legalName": "ИП Асхат",
  "idn": "…"
}

Что происходит:

• По ownerPhone находится аккаунт владельца, а если его нет — создаётся
• Организация открывается в режиме песочницы с семидневным пробным тарифом
• Вы добавляетесь в эту организацию участником с ролью developer — сможете смотреть её из кабинета
• В ответе приходит apiKey. Он показывается один раз, сохраните его

ownerPhone — это личный номер клиента для входа в кабинет. Не номер кассира. Чем отличаются три номера: Номер кассира и ваш личный номер.

2. Подключить кассира клиента

Это самая полезная часть Partner API. Клиент никуда не заходит — он только называет пришедший ему код.

Четыре шага:

POST /partner/organizations/{id}/connections
  → в ответе идентификатор подключения {cid}

POST /partner/organizations/{id}/connections/{cid}/kaspi/init
  → в ответе {processId}

POST /partner/organizations/{id}/connections/{cid}/kaspi/send-phone
  { "processId": "…", "phone": "77XXXXXXXXX" }
  → на номер кассира приходит SMS от Kaspi

POST /partner/organizations/{id}/connections/{cid}/kaspi/verify-otp
  { "processId": "…", "otp": "123456" }
  → подключение активно

Практические замечания:

• Код из SMS живёт около минуты. Проводите привязку, пока клиент на связи, а не «созвонимся позже»
• Весь процесс — одно окно примерно на десять минут. Если оно прервалось, начинайте заново с init
• Заранее проверьте три условия для номера кассира, иначе вместо SMS Kaspi запросит пароль и видеоверификацию: Три условия для номера кассира
• Роль кассира создаётся в приложении Kaspi Pay (не в веб-кабинете): Настройки → Сотрудники → Добавить сотрудника, роль «Кассир»

Если что-то пошло не так: Кассир Kaspi не подключается.

3. Перевести в боевой режим

POST /api/v1/partner/organizations/{id}/mode
{ "mode": "live" }

Без активной привязки Kaspi переключение не пройдёт — сначала нужно завершить шаг 2.

После перехода пробный период клиента стартует с первого боевого счёта, а не со дня регистрации. Счета песочницы пробный период не запускают.

4. Выдать ключ

POST /api/v1/partner/organizations/{id}/api-keys
{ "name": "Сайт", "scopes": ["invoices:write", "invoices:read"] }

Ключ принадлежит организации клиента и создаётся под её текущий режим. В ответе он показывается один раз.

Ключ можно привязать к конкретному кассиру — полезно, когда точек или кассиров несколько: Привязка API-ключа к кассиру.

5. Статистика

GET /api/v1/partner/organizations

По каждому клиенту: режим, тариф, статистика платежей, активные привязки Kaspi.

GET /api/v1/partner/earnings

Ваш реферальный код, пришедшие по нему клиенты и начисленное вознаграждение. Подробно: Реферальная программа.

Кто управляет счетами клиента

Два пути:

Через Partner API счета не создаются. Счёт всегда выставляется ключом клиента через обычные эндпоинты. Partner API — это только слой управления.

Если вам приходится хранить ключи клиентов, храните их зашифрованными и никогда не пишите в логи: Безопасность интеграции.

Вопросы и ответы

Как получить партнёрский тариф? Напишите в поддержку: WhatsApp +7 778 881 3333 или Telegram @qutpaybot. Тариф договорный, количество счетов не ограничено.

Деньги клиентов проходят через меня? Нет. Деньги идут напрямую на счёт Kaspi самого клиента. Ни мы, ни вы их не удерживаем.

Может ли клиент вообще не заходить в кабинет? Да. Но право входа как владельца остаётся за его личным номером — он в любой момент может войти и, например, убрать ваше членство с ролью developer.

Можно ли использовать один номер кассира для нескольких клиентов? Нет. У каждой организации должен быть свой кассир в своём аккаунте Kaspi. Kaspi разрешает одно активное устройство на кассира.

Могу ли я оплачивать тариф за клиента? Тариф привязан к организации клиента. Порядок оплаты согласуйте с поддержкой.

Где полное описание API? На api.qut.kz/docs, тег Partner. Руководство: api.qut.kz/docs/guide/partner.