# SaaS платформасына: клиенттер атынан төлем қабылдау

> Платформаңыздың клиенттері Kaspi төлемін өз шоттарына жинай алады. Кілттерді сақтау, клиент атынан счёт шығару, Partner API арқылы толық автоматтандыру және әр клиентке бөлек webhook.

## Қысқаша

Егер сіз кәсіпорындарға арналған платформа жасасаңыз (жазылу жүйесі, дүкен құрастырғыш, есеп жүргізу сервисі), клиенттеріңізге Kaspi төлемін қосуға болады. Басты қағида: **әр клиенттің ақшасы өз Kaspi шотына түседі**, сіздің шотыңыз арқылы өтпейді. Екі жолы бар — клиенттің API кілтін платформада сақтап, оның атынан счёт шығару, немесе Partner API арқылы ұйым ашудан кілт беруге дейінгі бүкіл процесті автоматтандыру.

## Сценарий

Сіздің платформаңызда 300 салон, дүкен немесе шеберхана отыр. Әрқайсысы өз клиенттерінен ақша алады. Сіз ол ақшаға тимейсіз — сіздің табысыңыз платформаның өз жазылым ақысы.

Клиентке керегі: баптауларға кіріп, Kaspi төлемін қосу, содан кейін оның тапсырыстарында «Kaspi арқылы төлеу» батырмасы пайда болуы. Ақша сол салонның өз Kaspi шотына түсуі керек, сіздің шотыңызға емес.

## Екі жол

| Жол | Не істейді | Кімге жарайды |
|---|---|---|
| Клиенттің кілтін сақтау | Клиент өзі тіркеледі, кілтті платформаға енгізеді, сіз оның атынан счёт шығарасыз | Клиент саны аз немесе орташа, қолмен баптау қолайлы |
| Partner API | Платформа клиент ұйымын ашады, кассирін қосады, кілт береді, статистиканы көреді | Клиент саны көп, тіркелу процесі платформаның ішінде болуы керек |

Екеуінде де ақша ағыны бірдей: тіке клиенттің Kaspi шотына.

## Жол 1: клиенттің кілтін сақтау

**Клиент жағындағы қадамдар.** Клиент [qut.kz](https://qut.kz) сайтында тіркеледі, өз Kaspi кассирін қосады (Kaspi Pay қосымшасында қызметкер ашып, кабинетте байланыстырады), кабинеттен API кілт жасайды да, сол кілтті сіздің платформаңыздың баптауына енгізеді.

**Платформа жағындағы қадамдар.**

1. Клиенттің кілтін серверде, шифрланған күйде сақтайсыз.
2. Тапсырыс төленуі керек болғанда сол клиенттің кілтімен `POST /api/v1/invoices` шақырасыз.
3. Жауаптағы `payUrl`-ды клиенттің сатып алушысына көрсетесіз.
4. Төлем түскенде webhook келеді, сіз тапсырысты жабасыз.
5. Клиенттің кабинетінде бұл счёттар өз атынан көрінеді.

Баптау кезінде кілттің жарамдылығын бірден тексеріңіз: `GET /api/v1/invoices` шақырып көріңіз немесе sandbox кілтімен сынақ счётын жасаңыз. Қате кілтті сақтап қойсаңыз, мәселе бірінші төлем сәтінде ғана шығады.

## Жол 2: Partner API

Partner API арқылы платформа клиентке орнына жұмыс істейді: ұйым ашады, кассирін қосуға көмектеседі, API кілт береді, статистиканы оқиды. Клиент сіздің интерфейсіңізден шықпайды.

Бұл үшін `partner:manage` scope-ы бар кілт керек. Толығы: [Partner API](/kb/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 қайтарады.
- **Қол жетімді адамдар шеңбері.** Платформаңыздың қызметкерлерінің қайсысы клиент кілтін көре алатынын шектеңіз.

Толық тізім: [Интеграция қауіпсіздігі: чек-парақ](/kb/security-checklist).

## Әр клиентке бөлек webhook

Webhook адресіне клиентті ажырататын белгі болғаны дұрыс. Екі тәсіл:

- **Жолда белгі:** `https://sizdin-platforma.kz/hooks/qutpay/<client_id>`. Әр клиент өз кабинетінде осы адресті қояды (немесе Partner API арқылы сіз қоясыз).
- **Payload ішіндегі белгі:** счёт жасағанда `metadata` өрісіне клиенттің идентификаторын жазасыз, webhook келгенде соны оқисыз.

Екеуін қатар қолданған сенімдірек. Маңызды нүктелер:

- Продакшенде адрес тек `https` және нақты домен болуы керек, IP немесе туннель адресі қабылданбайды.
- Webhook адресі авторизациясыз ашық болуы керек. Басқа жерге апаратын қайта бағыттау ұсталмайды.
- Қолтаңбаны тексеріңіз: `HMAC-SHA256(secret, timestamp + "." + rawBody)`, hex, `sha256=` префиксімен. **Денені өзгертілмеген байт күйінде** тексеріңіз, JSON-ға айналдырғанға дейін.
- 5 минуттан ескі `timestamp` қабылданбасын.
- 2xx емес жауап берсеңіз 11 рет қайталанады, сондықтан өңдеуіңіз `(invoice.id, status)` жұбы бойынша идемпотентті болсын.

Толығы: [Webhook баптау](/kb/webhook-setup).

## Кодсыз нұсқасы бар ма

Платформа тарапынан — жоқ, бұл интеграция деңгейіндегі жұмыс. Бірақ **сіздің клиенттеріңіз үшін** кодсыз болуы керек: олар тек кабинетте кілт жасап, сіздің баптауыңызға енгізсе жеткілікті. Partner API нұсқасында одан да қарапайым — клиент тек кассирін байланыстырады.

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

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

- **Ақшаны өзіңізге жинамаңыз.** Клиенттердің ақшасын өз шотыңызға алып, кейін бөлу — бұл басқа қызмет түрі, ол үшін бөлек заңды негіз керек. Біздің модель — әр клиенттің ақшасы өзіне.
- **Тариф пен лимит әр ұйымға жеке.** Клиенттердің тарифтері қосылмайды, әрқайсысы өз көлеміне қарай таңдайды. Лимитке тірелген клиентке хабарлау механизмі болсын.
- **Кассир байланысы үзілуі мүмкін.** Клиенттің кассир нөмірімен біреу Kaspi Pay-ге кірсе, байланыс үзіледі де счёт жасау тоқтайды. Платформада бұл қатені ұстап, клиентке түсінікті хабар көрсететін жер болсын.
- **Sandbox-та клиент симуляциясын жасаңыз.** `qp_test_…` кілтімен бүкіл циклді өткізіңіз: кілт енгізу, счёт жасау, webhook қабылдау, қате жағдайлар.
- **Клиенттің деректері.** Сатып алушылардың телефон нөмірлерін өңдейсіз — оны қалай сақтайтыныңызды өз саясатыңызда жазыңыз.

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

**Ақша менің платформамның шотына түсе ме?** Жоқ. Әр клиенттің ақшасы өз Kaspi шотына түседі. Ақша ешқашан бізде де, сізде де ұсталмайды.

**Комиссияны қалай алам?** Транзакциядан пайыз алу бұл модельде жұмыс істемейді. Платформаңыздың өз жазылым ақысын бөлек алыңыз — оны да Qut Pay арқылы жинауға болады.

**Клиенттің кілтін сақтаудың орнына ортақ кілт қолдансам бола ма?** Жоқ. Ортақ кілт бір ғана ұйымның кассирімен байланысты, сондықтан ақша сол ұйымға түсер еді.

**Partner API-ге кім қол жеткізе алады?** `partner:manage` scope-ы бар кілт керек. Шарттарын талқылау үшін қолдауға жазыңыз.

**Клиент кілтін жойып жіберсе не болады?** Оның атынан жіберілген сұраулар 401 қайтарады. Платформада бұл қатені ұстап, клиенттен жаңа кілт сұрайтын экран болсын: [API 401 қайтарады](/kb/api-401).