Коротко
Если вы делаете платформу для бизнеса (система записи, конструктор магазинов, сервис учёта), вы можете дать своим клиентам приём Kaspi. Главный принцип: деньги каждого клиента приходят на его собственный Kaspi-счёт, через ваш счёт они не проходят. Есть два пути — хранить API-ключ клиента у себя и выставлять счета от его имени, либо через Partner API автоматизировать весь процесс от создания организации до выдачи ключа.
Сценарий
На вашей платформе сидят 300 салонов, магазинов или мастерских. Каждый берёт деньги со своих клиентов. Вы к этим деньгам не прикасаетесь — ваш доход это подписка на саму платформу.
Клиенту нужно: зайти в настройки, включить приём Kaspi и увидеть в своих заказах кнопку «Оплатить через Kaspi». Деньги должны прийти на Kaspi-счёт именно этого салона, а не на ваш.
Два пути
| Путь | Как работает | Кому подходит |
|---|---|---|
| Хранение ключа клиента | Клиент регистрируется сам, вводит ключ в вашей платформе, вы выставляете счета от его имени | Небольшое или среднее число клиентов, ручная настройка приемлема |
| Partner API | Платформа сама создаёт организацию клиента, помогает подключить кассира, выдаёт ключ, читает статистику | Много клиентов, регистрация должна проходить внутри платформы |
В обоих случаях движение денег одинаковое: напрямую на Kaspi-счёт клиента.
Путь 1: хранение ключа клиента
Шаги на стороне клиента. Клиент регистрируется на qut.kz, подключает своего кассира Kaspi (заводит сотрудника в приложении Kaspi Pay и привязывает его в кабинете), создаёт в кабинете API-ключ и вводит его в настройках вашей платформы.
Шаги на стороне платформы.
- Храните ключ клиента на сервере в зашифрованном виде.
- Когда заказ нужно оплатить, вызываете
POST /api/v1/invoicesключом именно этого клиента. - Показываете
payUrlиз ответа покупателю вашего клиента. - При оплате приходит вебхук, вы закрываете заказ.
- В кабинете клиента эти счета видны под его собственным именем.
При настройке сразу проверяйте валидность ключа: вызовите GET /api/v1/invoices или создайте пробный счёт на ключе песочницы. Если сохранить неверный ключ молча, проблема всплывёт только в момент первой оплаты.
Путь 2: Partner API
Через Partner API платформа работает за клиента: создаёт организацию, помогает подключить кассира, выдаёт API-ключ, читает статистику. Клиент не выходит из вашего интерфейса.
Для этого нужен ключ со scope partner:manage. Подробнее: Partner API.
Когда выбирать: если клиентов много, если они технически неподготовлены или если вы хотите, чтобы «Включить Kaspi» работало одной кнопкой.
Какие методы API нужны
| Что делает | Метод |
|---|---|
| Счёт от имени клиента | POST /api/v1/invoices (ключом этого клиента) |
| Массовое выставление | POST /api/v1/invoices/bulk, 1-100 |
| Запрос статуса | GET /api/v1/invoices/{id} |
| Список, отчётность | GET /api/v1/invoices |
| Возврат | POST /api/v1/invoices/{id}/refund |
| Управление организациями клиентов | Partner API, partner:manage |
| Состояние сервиса | GET /api/v1/status |
Безопасное хранение ключей
Ключ клиента косвенно связан с его деньгами. Правила хранения:
- Шифруйте. В базе ключ не должен лежать открытым текстом. Ключ шифрования держите в отдельном секрет-хранилище.
- Только на сервере. Ключ не должен попадать в браузер, в мобильное приложение (APK/IPA) и во фронтенд-код.
- Не пишите в логи. В журналах ошибок и трассировках запросов ключа быть не должно. В интерфейсе показывайте только последние четыре символа.
- Минимум прав. Не просите у клиента ключ с полным набором прав. Для выставления счетов хватает
invoices:writeиinvoices:read,refunds:writeдобавляйте только если нужны возвраты. - Дайте возможность заменить. Если клиент хочет сменить ключ, в интерфейсе должна быть кнопка. После удаления старого ключа API начнёт отвечать 401.
- Ограничьте круг доступа. Решите, кто из сотрудников вашей платформы вообще может видеть ключи клиентов.
Полный список: Безопасность интеграции: чек-лист.
Отдельный вебхук на каждого клиента
В адресе вебхука должен быть признак, по которому вы отличите клиента. Два подхода:
- Признак в пути:
https://вашаплатформа.kz/hooks/qutpay/<client_id>. Каждый клиент указывает этот адрес в своём кабинете (или это делаете вы через Partner API). - Признак в payload: при создании счёта пишете идентификатор клиента в
metadataи читаете его при получении вебхука.
Надёжнее использовать оба сразу. Важные моменты:
- В боевом режиме адрес должен быть только на
httpsи на реальном домене; IP и адрес туннеля не принимаются. - Адрес вебхука должен открываться без авторизации. Редиректы на другой адрес не отрабатываются.
- Проверяйте подпись:
HMAC-SHA256(secret, timestamp + "." + rawBody), hex, с префиксомsha256=. Проверяйте тело в неизменённом байтовом виде, до разбора в JSON. timestampстарше 5 минут принимать не надо.- При ответе не 2xx доставка повторится 11 раз, поэтому обработка должна быть идемпотентной по паре
(invoice.id, status).
Подробнее: Настройка вебхуков.
Есть ли вариант без кода
Со стороны платформы — нет, это работа уровня интеграции. Но для ваших клиентов он должен быть без кода: им достаточно создать ключ в кабинете и вставить его в ваши настройки. В варианте с Partner API ещё проще — клиент только привязывает своего кассира.
Когда будете писать инструкцию для клиентов, распишите шаги буквально: завести сотрудника в приложении Kaspi Pay, привязать его в кабинете, создать ключ. Чаще всего люди спотыкаются на требованиях к номеру кассира.
Особые замечания
- Не собирайте деньги на себя. Принимать деньги клиентов на свой счёт и потом распределять — это другой вид деятельности, для него нужна отдельная правовая основа. Наша модель: деньги каждого клиента идут ему самому.
- Тариф и лимиты у каждой организации свои. Тарифы клиентов не складываются, каждый выбирает под свой объём. Предусмотрите уведомление клиенту, упёршемуся в лимит.
- Привязка кассира может оборваться. Если с номера кассира клиента кто-то войдёт в Kaspi Pay, привязка оборвётся и счета перестанут создаваться. В платформе должно быть место, где эта ошибка перехватывается и показывается клиенту понятным текстом.
- Сделайте симуляцию клиента в песочнице. На ключе
qp_test_…прогоните весь цикл: ввод ключа, создание счёта, приём вебхука, ошибочные ситуации. - Данные покупателей. Вы обрабатываете номера телефонов покупателей — опишите в своей политике, как вы их храните.
Вопросы и ответы
Деньги придут на счёт моей платформы? Нет. Деньги каждого клиента приходят на его собственный Kaspi-счёт. Ни у нас, ни у вас они не задерживаются.
Как мне брать комиссию? Брать процент с транзакции в этой модели не получится. Берите собственную абонентскую плату платформы отдельно — её тоже можно собирать через Qut Pay.
Можно вместо хранения ключей клиентов использовать один общий ключ? Нет. Общий ключ связан с кассиром одной организации, и деньги уходили бы именно ей.
Кому доступен Partner API? Нужен ключ со scope partner:manage. Условия обсуждаются через поддержку.
Что будет, если клиент удалит свой ключ? Запросы от его имени начнут возвращать 401. Предусмотрите в платформе экран, который перехватывает эту ошибку и просит новый ключ: API отвечает 401.