Коротко
При запуске маркетплейса первое, что нужно решить, — на чей счёт приходят деньги. Есть две совершенно разные архитектуры. Если всё приходит вам, а потом вы рассчитываетесь с продавцами — достаточно одной организации и простой схемы. Если же деньги каждого продавца должны идти напрямую на его счёт Kaspi, то у каждого продавца будет своя организация, свой кассир Kaspi и свой API-ключ. Делается это не руками, а через Platform Partner API.
Выбор модели
| Один счёт (ваш) | Свой счёт у каждого продавца | |
|---|---|---|
| Куда приходят деньги | На ваш счёт Kaspi | На счёт Kaspi продавца |
| Что нужно продавцу | Ничего | Свой бизнес-аккаунт Kaspi Pay, номер кассира |
| Что нужно вам | Одна организация, один ключ | На каждого продавца организация + кассир + ключ |
| Выплаты продавцу | Переводите сами | Не нужны, деньги сразу его |
| Расчёты | На вашей стороне | Комиссию собираете отдельно |
| Сложность | Низкая | Выше, но автоматизируется |
Первая модель — это обычная схема интернет-магазина: Приём Kaspi для интернет-магазина. Дальше речь о второй.
Что нужно каждому продавцу
Чтобы деньги приходили продавцу на его счёт, нужны три вещи:
- Свой бизнес-аккаунт Kaspi Pay. Без него ничего не сделать.
- Отдельный номер кассира. Реальная SIM, принимающая SMS. На ИИН владельца этого номера не должно быть зарегистрировано ИП или ТОО в Kaspi Pay, иначе Kaspi запросит пароль и видеоверификацию. На номере должна стоять только роль «Кассир». Подробно: Три условия для номера кассира.
- Свой API-ключ. Ваша платформа выставляет счета от имени этого продавца именно этим ключом.
Самое сложное — второй пункт. Часть продавцов не сможет выполнить это условие, поэтому продумайте процесс подключения заранее: дайте продавцу понятную инструкцию, что именно сделать.
Platform Partner API
Подключить сотню продавцов вручную невозможно. Partner API сделан ровно для этого: создать организацию клиента, подключить к ней кассира, выдать API-ключ, получить статистику — всё программно.
Ключу нужен scope partner:manage.
Полное описание и методы: Partner API. Похожий, но немного другой сценарий: SaaS-платформа.
Схема работы по шагам
Подключение продавца:
| Шаг | Кто | Что происходит |
|---|---|---|
| 1 | Продавец | Регистрируется на вашей платформе |
| 2 | Ваш сервер | Через Partner API создаёт ему организацию |
| 3 | Продавец | В приложении Kaspi Pay заводит сотрудника с ролью «Кассир» |
| 4 | Продавец | Вводит номер кассира и подтверждает код из SMS |
| 5 | Ваш сервер | Создаёт для этой организации API-ключ и надёжно его хранит |
| 6 | Ваш сервер | Выставляет счета по заказам этого продавца его ключом |
Во время заказа:
| Шаг | Кто | Что происходит |
|---|---|---|
| 1 | Покупатель | Выбирает товар продавца и переходит к оплате |
| 2 | Ваш сервер | POST /api/v1/invoices ключом продавца |
| 3 | Покупатель | Сканирует QR и подтверждает в Kaspi |
| 4 | Kaspi | Деньги идут на счёт продавца |
| 5 | Qut Pay | Отправляет вебхук |
| 6 | Ваш сервер | Переводит заказ в «оплачен», уведомляет продавца |
Разделение и хранение ключей
- Отдельный ключ на каждого продавца. Не делайте общий: один продавец сможет увидеть счета другого.
- Ключ живёт только на вашем сервере. Не отдавайте его в браузер продавца и в мобильное приложение.
- Храните в зашифрованном виде. В базе не должно быть открытого текста.
- Выдавайте минимум прав. Для выставления счетов хватает
invoices:write,refunds:write— только если действительно нужен. Подробно: Права доступа (scopes). - Привяжите ключ к конкретному кассиру. Боевые счета привязанного ключа идут только через этого кассира и не видят счетов другого: Привязка API-ключа к кассиру.
- Если ключ утёк — сразу удалите и создайте новый.
Отдельный вебхук на продавца
Адрес вебхука настраивается на уровне организации, поэтому для организации каждого продавца можно указать свой адрес. Два подхода:
1. Общий адрес. Все организации шлют на один адрес, а вы определяете продавца по данным внутри события. Проще всего.
2. Отдельный путь на продавца. Вида https://vash-domen.kz/hooks/seller/1487. Разделять в коде удобнее, да и секреты будут разными.
В обоих случаях проверяйте подпись и делайте обработку идемпотентной — по паре (invoice.id, status). Настройка: Настройка вебхуков.
Как удерживать комиссию
Скажем прямо: мы комиссию не удерживаем и платёж не делим. Деньги целиком уходят на счёт Kaspi продавца, мы их не трогаем. Ни split-payment, ни эскроу у нас нет.
Значит, комиссия платформы — это ваш расчёт с продавцом. Работающие на практике варианты:
| Способ | Как работает | Кому подходит |
|---|---|---|
| Счёт раз в месяц | В конце месяца выставляете продавцу счёт на сумму комиссии | Постоянные продавцы |
| Подписка | Берёте с продавца фиксированный ежемесячный платёж | Абонементная модель |
| Предоплаченный баланс | Продавец вносит вперёд, вы списываете с баланса | Реклама, платные места |
| Смешанные счета | Часть заказов на ваш счёт, часть на счёт продавца | Сложно, не рекомендуем |
Счёт продавцу на комиссию — это обычный счёт, выставленный организацией вашей платформы. Их можно выставлять пачкой: Массовое создание счетов.
Пропишите размер комиссии и срок оплаты в договоре. Если продавец не платит, отключение его ключа — это одно техническое действие.
Отчётность и контроль
- Счета каждого продавца лежат в его организации и видны в его кабинете.
- Статистику на уровне платформы вы получаете через Partner API.
- Если продавец хочет разделить учёт по своим точкам: Раздельная отчётность по точкам.
- Тариф и лимиты — у каждой организации свои. Если у продавца кончился тариф, его счета выставляться не будут. Решите заранее, кто платит за тариф: платформа или сам продавец.
На что обратить внимание
- Номер кассира виден покупателю. В уведомлении о счёте будет номер кассира продавца, а не вашей платформы. Объясните это покупателю.
- Привязка кассира у продавца может оборваться. Если он войдёт с этого номера в Kaspi Pay, счета остановятся. Показывайте в платформе признак «привязка неактивна» и уведомляйте продавца.
- Кто делает возврат. Возврат идёт через организацию продавца. Продумайте, как вы принимаете претензию покупателя и как заставляете продавца оформить возврат.
- Поздние оплаты. Платежи с признаком
late: trueна маркетплейсе особенно опасны: заказ мог быть уже закрыт. Обрабатывайте этот случай отдельно.
Вопросы и ответы
Можно разделить один платёж надвое и сразу удержать комиссию? Нет. Один счёт — один получатель. Split-payment нет.
У продавца нет аккаунта Kaspi, но он хочет продавать. Что делать? Тогда идите по первой модели: деньги приходят вам, а с продавцом рассчитываетесь сами. В этом случае продавцом товара становитесь вы — юридическую сторону обсудите со своим юристом.
Смогу ли я видеть счета продавцов? Данные уровня платформы доступны через Partner API. Подробно: Partner API.
Нужен ли отдельный тариф каждому продавцу? Да, тариф привязан к организации. Если продавцов много, обсудите партнёрский тариф с поддержкой.
Что делать, если продавец уходит с платформы? Удалите его API-ключ. Организация и аккаунт Kaspi остаются у него, он сможет работать и без вас.