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

> Әр сатушының ақшасы өз Kaspi шотына түсуі керек болса: әрқайсысына өз ұйымы мен кассирі, кілттерді бөлу, бөлек webhook. Комиссияны қалай ұстау мәселесі.

## Қысқаша

Маркетплейс құрғанда бірінші шешетін нәрсе — **ақша кімнің шотына түседі**. Екі мүлдем бөлек архитектура бар. Егер бәрі сіздің шотыңызға түсіп, сосын сатушыларға таратылса — сізге бір ғана ұйым және қарапайым схема керек. Ал әр сатушының ақшасы **тікелей оның өз Kaspi шотына** түсуі керек болса, әр сатушының өз ұйымы, өз Kaspi кассирі және өз API кілті болады. Мұны қолмен емес, Platform Partner API арқылы автоматтандырасыз.

## Екі модельді таңдау

| | Бір шот (сіздікі) | Әр сатушының өз шоты |
|---|---|---|
| Ақша қайда түседі | Сіздің Kaspi шотыңызға | Сатушының Kaspi шотына |
| Сатушыға не керек | Ештеңе | Өз Kaspi Pay бизнес-аккаунты, кассир нөмірі |
| Сізге не керек | Бір ұйым, бір кілт | Әр сатушыға ұйым + кассир + кілт |
| Сатушыға төлеу | Өзіңіз аударасыз | Керек емес, ақша бірден оған тиесілі |
| Есеп айырысу | Сізде | Комиссияны бөлек өндіресіз |
| Күрделілігі | Төмен | Жоғары, бірақ автоматтандырылады |

Бірінші модель — бұл жай ғана интернет-дүкен схемасы: [Интернет-дүкенге Kaspi төлемін қосу](/kb/for-online-store). Бұдан әрі екінші модель туралы.

## Әр сатушыға не керек

Сатушының ақшасы өз шотына түсуі үшін үш нәрсе болуы керек:

1. **Өз Kaspi Pay бизнес-аккаунты.** Онсыз ештеңе жасай алмайсыз.
2. **Бөлек кассир нөмірі.** Нақты SIM, SMS қабылдайтын. Ол нөмір иесінің ЖСН-іне Kaspi Pay-де ЖК немесе ЖШС тіркелмеген болуы керек, әйтпесе Kaspi пароль мен видеоверификация сұрайды. Нөмірде тек «Кассир» рөлі тұрсын. Толығы: [Кассир нөміріне қойылатын үш шарт](/kb/cashier-number-requirements).
3. **Өз API кілті.** Сіздің платформаңыз сол кілтпен сол сатушының атынан счёт жасайды.

Ең қиын жері — екінші тармақ. Сатушылардың бір бөлігі бұл шартты орындай алмайды, сондықтан қосылу процесін алдын ала ойластырыңыз: сатушыға нақты не істеу керегін көрсететін нұсқаулық беріңіз.

## Platform Partner API

Жүз сатушыны қолмен қосу мүмкін емес. Partner API дәл осы үшін жасалған: клиент ұйымын ашу, оған кассир қосу, API кілт беру, статистиканы алу — бәрі бағдарламалық түрде.

Кілтке `partner:manage` scope-ы керек.

Толық сипаттамасы мен әдістері: [Partner API](/kb/partner-api). Ұқсас, бірақ сәл басқа сценарий: [SaaS платформасына](/kb/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 | Webhook жібереді |
| 6 | Сіздің сервер | Тапсырысты «төленді» етеді, сатушыға хабарлайды |

## Кілттерді бөлу және сақтау

- **Әр сатушыға бөлек кілт.** Ортақ кілт жасамаңыз: бір сатушының счёттарын екіншісі көріп қалуы мүмкін.
- **Кілт тек сіздің серверде тұрсын.** Сатушының браузеріне, мобильді қосымшаға берілмесін.
- **Шифрлап сақтаңыз.** Базада ашық мәтінмен жатпасын.
- **Ең аз құқық беріңіз.** Счёт жасау үшін `invoices:write` жетеді, `refunds:write` қажет болғанда ғана. Толығы: [Құқықтар (scopes)](/kb/scopes).
- **Кілтті нақты кассирге байлаңыз.** Байланған кілттің live счёттары тек сол кассир арқылы жүреді, басқа кассирдің счёттарын көрмейді: [API кілтті кассирге байлау](/kb/api-key-connection).
- **Кілт сыртқа шықса** дереу жойып, жаңасын жасаңыз.

## Әр сатушыға бөлек webhook

Webhook адресі ұйым деңгейінде бапталады, сондықтан әр сатушының ұйымына өз адресіңізді қоюға болады. Екі тәсіл:

**1. Ортақ адрес.** Барлық ұйым бір адреске жіберсін, ал сіз оқиғаның ішіндегі деректер бойынша қай сатушы екенін анықтаңыз. Қарапайымы.

**2. Сатушы бойынша бөлек жол.** `https://sizdin-domen.kz/hooks/seller/1487` сияқты. Кодта ажырату оңайырақ, бірақ құпиялар да бөлек болады.

Екі жағдайда да қолтаңбаны тексеріңіз және өңдеу идемпотентті болсын — `(invoice.id, status)` жұбы бойынша. Баптау: [Webhook баптау](/kb/webhook-setup).

## Комиссияны қалай ұстау мәселесі

Мұны ашық айтамыз: **біз комиссияны ұстамаймыз және бөлмейміз.** Ақша толығымен сатушының Kaspi шотына түседі, біз оған жанаспаймыз. Бізде split-payment немесе escrow деген нәрсе жоқ.

Демек платформаның комиссиясы — сіздің сатушымен арадағы есеп айырысуыңыз. Іс жүзінде қолданылатын жолдар:

| Тәсіл | Қалай жұмыс істейді | Кімге жарайды |
|---|---|---|
| Ай сайынғы шот | Ай соңында сатушыға комиссия сомасына счёт шығарасыз | Тұрақты сатушылар |
| Жазылым | Сатушыдан ай сайынғы тұрақты төлем аласыз | Абонемент моделі |
| Алдын ала баланс | Сатушы алдын ала салады, сіз одан ұстайсыз | Жарнама, жарнамалық орын |
| Аралас шот | Кейбір тапсырыс сіздің шотқа, кейбірі сатушыға | Күрделі, ұсынбаймыз |

Сатушыға комиссия счётын шығару — бұл сіздің платформаңыздың өз ұйымы арқылы жасалатын әдеттегі счёт. Топтап жасауға болады: [Топтап счёт жасау](/kb/bulk-invoices).

Шартта комиссияның мөлшері мен төлеу мерзімін жазып қойыңыз. Сатушы төлемей қойса, оның кілтін өшіру — техникалық жағынан бір әрекет.

## Есеп және бақылау

- Әр сатушының счёттары өз ұйымында тұрады, өз кабинетінен көрінеді.
- Сізге платформа деңгейіндегі статистика Partner API арқылы келеді.
- Сатушы ішінде нүктелерге бөлгісі келсе: [Нүктелер бойынша бөлек есеп](/kb/multi-point-reporting).
- Тариф пен лимит **әр ұйымға бөлек**. Сатушының тарифі бітсе, оның счёттары шықпайды. Мұны алдын ала ойластырыңыз: тарифті платформа төлей ме, әлде сатушының өзі ме.

## Ерекше ескертулер

- **Кассир нөмірі сатып алушыға көрінеді.** Счёт туралы хабарламада сатушының кассир нөмірі тұрады, сіздің платформаңыздың емес. Сатып алушыға мұны түсіндіріңіз.
- **Сатушының кассир байланысы үзілуі мүмкін.** Ол нөмірмен Kaspi Pay-ге кірсе, счёттар тоқтайды. Платформада «байланыс белсенді емес» деген белгі болсын, сатушыға хабарлаңыз.
- **Қайтаруды кім жасайды.** Қайтару сатушының ұйымы арқылы жүреді. Сатып алушының шағымын сіз қабылдап, сатушыны қайтару жасауға мәжбүрлеу механизмін ойластырыңыз.
- **Кеш келген төлем.** `late: true` белгісімен келетін төлемдер маркетплейсте әсіресе қауіпті: тапсырыс жабылып қалған болуы мүмкін. Оны бөлек өңдеңіз.

## Жиі қойылатын сұрақтар

**Бір төлемді екіге бөліп, комиссияны бірден ұстауға бола ма?** Жоқ. Бір счёт — бір алушы. Split-payment жоқ.

**Сатушының Kaspi аккаунты жоқ, бірақ сатқысы келеді. Не істеймін?** Онда бірінші модельмен жүріңіз: ақша сіздің шотыңызға түседі, сатушымен өзіңіз есеп айырысасыз. Бұл жағдайда сіз тауардың сатушысы болып шығасыз — заңды жағын заңгеріңізбен қараңыз.

**Сатушының счёттарын мен көре аламын ба?** Partner API арқылы платформа деңгейіндегі мәліметтерді аласыз. Толығы: [Partner API](/kb/partner-api).

**Әр сатушыға бөлек тариф керек пе?** Иә, тариф ұйым деңгейінде. Сатушы саны көп болса, Серіктес тарифі туралы қолдаумен сөйлесіңіз.

**Сатушыны платформадан шығарсам не істеймін?** Оның API кілтін жойыңыз. Ұйымы мен Kaspi аккаунты өзінде қалады, ол сізсіз де жұмыс істей береді.