# Маркетплейс и агрегатор

> Если деньги должны приходить на счёт Kaspi каждого продавца: своя организация и свой кассир для каждого, разделение ключей, отдельные вебхуки. Как удерживать комиссию.

## Коротко

При запуске маркетплейса первое, что нужно решить, — **на чей счёт приходят деньги**. Есть две совершенно разные архитектуры. Если всё приходит вам, а потом вы рассчитываетесь с продавцами — достаточно одной организации и простой схемы. Если же деньги каждого продавца должны идти **напрямую на его счёт Kaspi**, то у каждого продавца будет своя организация, свой кассир Kaspi и свой API-ключ. Делается это не руками, а через Platform Partner API.

## Выбор модели

| | Один счёт (ваш) | Свой счёт у каждого продавца |
|---|---|---|
| Куда приходят деньги | На ваш счёт Kaspi | На счёт Kaspi продавца |
| Что нужно продавцу | Ничего | Свой бизнес-аккаунт Kaspi Pay, номер кассира |
| Что нужно вам | Одна организация, один ключ | На каждого продавца организация + кассир + ключ |
| Выплаты продавцу | Переводите сами | Не нужны, деньги сразу его |
| Расчёты | На вашей стороне | Комиссию собираете отдельно |
| Сложность | Низкая | Выше, но автоматизируется |

Первая модель — это обычная схема интернет-магазина: [Приём Kaspi для интернет-магазина](/kb/ru/for-online-store). Дальше речь о второй.

## Что нужно каждому продавцу

Чтобы деньги приходили продавцу на его счёт, нужны три вещи:

1. **Свой бизнес-аккаунт Kaspi Pay.** Без него ничего не сделать.
2. **Отдельный номер кассира.** Реальная SIM, принимающая SMS. На ИИН владельца этого номера не должно быть зарегистрировано ИП или ТОО в Kaspi Pay, иначе Kaspi запросит пароль и видеоверификацию. На номере должна стоять только роль «Кассир». Подробно: [Три условия для номера кассира](/kb/ru/cashier-number-requirements).
3. **Свой API-ключ.** Ваша платформа выставляет счета от имени этого продавца именно этим ключом.

Самое сложное — второй пункт. Часть продавцов не сможет выполнить это условие, поэтому продумайте процесс подключения заранее: дайте продавцу понятную инструкцию, что именно сделать.

## Platform Partner API

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

Ключу нужен scope `partner:manage`.

Полное описание и методы: [Partner API](/kb/ru/partner-api). Похожий, но немного другой сценарий: [SaaS-платформа](/kb/ru/for-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)](/kb/ru/scopes).
- **Привяжите ключ к конкретному кассиру.** Боевые счета привязанного ключа идут только через этого кассира и не видят счетов другого: [Привязка API-ключа к кассиру](/kb/ru/api-key-connection).
- **Если ключ утёк** — сразу удалите и создайте новый.

## Отдельный вебхук на продавца

Адрес вебхука настраивается на уровне организации, поэтому для организации каждого продавца можно указать свой адрес. Два подхода:

**1. Общий адрес.** Все организации шлют на один адрес, а вы определяете продавца по данным внутри события. Проще всего.

**2. Отдельный путь на продавца.** Вида `https://vash-domen.kz/hooks/seller/1487`. Разделять в коде удобнее, да и секреты будут разными.

В обоих случаях проверяйте подпись и делайте обработку идемпотентной — по паре `(invoice.id, status)`. Настройка: [Настройка вебхуков](/kb/ru/webhook-setup).

## Как удерживать комиссию

Скажем прямо: **мы комиссию не удерживаем и платёж не делим.** Деньги целиком уходят на счёт Kaspi продавца, мы их не трогаем. Ни split-payment, ни эскроу у нас нет.

Значит, комиссия платформы — это ваш расчёт с продавцом. Работающие на практике варианты:

| Способ | Как работает | Кому подходит |
|---|---|---|
| Счёт раз в месяц | В конце месяца выставляете продавцу счёт на сумму комиссии | Постоянные продавцы |
| Подписка | Берёте с продавца фиксированный ежемесячный платёж | Абонементная модель |
| Предоплаченный баланс | Продавец вносит вперёд, вы списываете с баланса | Реклама, платные места |
| Смешанные счета | Часть заказов на ваш счёт, часть на счёт продавца | Сложно, не рекомендуем |

Счёт продавцу на комиссию — это обычный счёт, выставленный организацией вашей платформы. Их можно выставлять пачкой: [Массовое создание счетов](/kb/ru/bulk-invoices).

Пропишите размер комиссии и срок оплаты в договоре. Если продавец не платит, отключение его ключа — это одно техническое действие.

## Отчётность и контроль

- Счета каждого продавца лежат в его организации и видны в его кабинете.
- Статистику на уровне платформы вы получаете через Partner API.
- Если продавец хочет разделить учёт по своим точкам: [Раздельная отчётность по точкам](/kb/ru/multi-point-reporting).
- Тариф и лимиты — **у каждой организации свои**. Если у продавца кончился тариф, его счета выставляться не будут. Решите заранее, кто платит за тариф: платформа или сам продавец.

## На что обратить внимание

- **Номер кассира виден покупателю.** В уведомлении о счёте будет номер кассира продавца, а не вашей платформы. Объясните это покупателю.
- **Привязка кассира у продавца может оборваться.** Если он войдёт с этого номера в Kaspi Pay, счета остановятся. Показывайте в платформе признак «привязка неактивна» и уведомляйте продавца.
- **Кто делает возврат.** Возврат идёт через организацию продавца. Продумайте, как вы принимаете претензию покупателя и как заставляете продавца оформить возврат.
- **Поздние оплаты.** Платежи с признаком `late: true` на маркетплейсе особенно опасны: заказ мог быть уже закрыт. Обрабатывайте этот случай отдельно.

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

**Можно разделить один платёж надвое и сразу удержать комиссию?** Нет. Один счёт — один получатель. Split-payment нет.

**У продавца нет аккаунта Kaspi, но он хочет продавать. Что делать?** Тогда идите по первой модели: деньги приходят вам, а с продавцом рассчитываетесь сами. В этом случае продавцом товара становитесь вы — юридическую сторону обсудите со своим юристом.

**Смогу ли я видеть счета продавцов?** Данные уровня платформы доступны через Partner API. Подробно: [Partner API](/kb/ru/partner-api).

**Нужен ли отдельный тариф каждому продавцу?** Да, тариф привязан к организации. Если продавцов много, обсудите партнёрский тариф с поддержкой.

**Что делать, если продавец уходит с платформы?** Удалите его API-ключ. Организация и аккаунт Kaspi остаются у него, он сможет работать и без вас.