Қысқаша
Егер сіз кәсіпорындарға арналған платформа жасасаңыз (жазылу жүйесі, дүкен құрастырғыш, есеп жүргізу сервисі), клиенттеріңізге Kaspi төлемін қосуға болады. Басты қағида: әр клиенттің ақшасы өз Kaspi шотына түседі, сіздің шотыңыз арқылы өтпейді. Екі жолы бар — клиенттің API кілтін платформада сақтап, оның атынан счёт шығару, немесе Partner API арқылы ұйым ашудан кілт беруге дейінгі бүкіл процесті автоматтандыру.
Сценарий
Сіздің платформаңызда 300 салон, дүкен немесе шеберхана отыр. Әрқайсысы өз клиенттерінен ақша алады. Сіз ол ақшаға тимейсіз — сіздің табысыңыз платформаның өз жазылым ақысы.
Клиентке керегі: баптауларға кіріп, Kaspi төлемін қосу, содан кейін оның тапсырыстарында «Kaspi арқылы төлеу» батырмасы пайда болуы. Ақша сол салонның өз Kaspi шотына түсуі керек, сіздің шотыңызға емес.
Екі жол
| Жол | Не істейді | Кімге жарайды |
|---|---|---|
| Клиенттің кілтін сақтау | Клиент өзі тіркеледі, кілтті платформаға енгізеді, сіз оның атынан счёт шығарасыз | Клиент саны аз немесе орташа, қолмен баптау қолайлы |
| Partner API | Платформа клиент ұйымын ашады, кассирін қосады, кілт береді, статистиканы көреді | Клиент саны көп, тіркелу процесі платформаның ішінде болуы керек |
Екеуінде де ақша ағыны бірдей: тіке клиенттің Kaspi шотына.
Жол 1: клиенттің кілтін сақтау
Клиент жағындағы қадамдар. Клиент qut.kz сайтында тіркеледі, өз Kaspi кассирін қосады (Kaspi Pay қосымшасында қызметкер ашып, кабинетте байланыстырады), кабинеттен API кілт жасайды да, сол кілтті сіздің платформаңыздың баптауына енгізеді.
Платформа жағындағы қадамдар.
- Клиенттің кілтін серверде, шифрланған күйде сақтайсыз.
- Тапсырыс төленуі керек болғанда сол клиенттің кілтімен
POST /api/v1/invoicesшақырасыз. - Жауаптағы
payUrl-ды клиенттің сатып алушысына көрсетесіз. - Төлем түскенде webhook келеді, сіз тапсырысты жабасыз.
- Клиенттің кабинетінде бұл счёттар өз атынан көрінеді.
Баптау кезінде кілттің жарамдылығын бірден тексеріңіз: GET /api/v1/invoices шақырып көріңіз немесе sandbox кілтімен сынақ счётын жасаңыз. Қате кілтті сақтап қойсаңыз, мәселе бірінші төлем сәтінде ғана шығады.
Жол 2: Partner API
Partner API арқылы платформа клиентке орнына жұмыс істейді: ұйым ашады, кассирін қосуға көмектеседі, API кілт береді, статистиканы оқиды. Клиент сіздің интерфейсіңізден шықпайды.
Бұл үшін partner:manage scope-ы бар кілт керек. Толығы: 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 қайтарады.
- Қол жетімді адамдар шеңбері. Платформаңыздың қызметкерлерінің қайсысы клиент кілтін көре алатынын шектеңіз.
Толық тізім: Интеграция қауіпсіздігі: чек-парақ.
Әр клиентке бөлек 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 баптау.
Кодсыз нұсқасы бар ма
Платформа тарапынан — жоқ, бұл интеграция деңгейіндегі жұмыс. Бірақ сіздің клиенттеріңіз үшін кодсыз болуы керек: олар тек кабинетте кілт жасап, сіздің баптауыңызға енгізсе жеткілікті. Partner API нұсқасында одан да қарапайым — клиент тек кассирін байланыстырады.
Клиенттеріңізге көрсететін нұсқаулық дайындағанда қадамдарды нақты жазыңыз: Kaspi Pay қосымшасында қызметкер ашу, кабинетте байланыстыру, кілт жасау. Ең жиі қателесетін жері — кассир нөміріне қойылатын шарттар.
Ерекше ескертулер
- Ақшаны өзіңізге жинамаңыз. Клиенттердің ақшасын өз шотыңызға алып, кейін бөлу — бұл басқа қызмет түрі, ол үшін бөлек заңды негіз керек. Біздің модель — әр клиенттің ақшасы өзіне.
- Тариф пен лимит әр ұйымға жеке. Клиенттердің тарифтері қосылмайды, әрқайсысы өз көлеміне қарай таңдайды. Лимитке тірелген клиентке хабарлау механизмі болсын.
- Кассир байланысы үзілуі мүмкін. Клиенттің кассир нөмірімен біреу Kaspi Pay-ге кірсе, байланыс үзіледі де счёт жасау тоқтайды. Платформада бұл қатені ұстап, клиентке түсінікті хабар көрсететін жер болсын.
- Sandbox-та клиент симуляциясын жасаңыз.
qp_test_…кілтімен бүкіл циклді өткізіңіз: кілт енгізу, счёт жасау, webhook қабылдау, қате жағдайлар. - Клиенттің деректері. Сатып алушылардың телефон нөмірлерін өңдейсіз — оны қалай сақтайтыныңызды өз саясатыңызда жазыңыз.
Жиі қойылатын сұрақтар
Ақша менің платформамның шотына түсе ме? Жоқ. Әр клиенттің ақшасы өз Kaspi шотына түседі. Ақша ешқашан бізде де, сізде де ұсталмайды.
Комиссияны қалай алам? Транзакциядан пайыз алу бұл модельде жұмыс істемейді. Платформаңыздың өз жазылым ақысын бөлек алыңыз — оны да Qut Pay арқылы жинауға болады.
Клиенттің кілтін сақтаудың орнына ортақ кілт қолдансам бола ма? Жоқ. Ортақ кілт бір ғана ұйымның кассирімен байланысты, сондықтан ақша сол ұйымға түсер еді.
Partner API-ге кім қол жеткізе алады? partner:manage scope-ы бар кілт керек. Шарттарын талқылау үшін қолдауға жазыңыз.
Клиент кілтін жойып жіберсе не болады? Оның атынан жіберілген сұраулар 401 қайтарады. Платформада бұл қатені ұстап, клиенттен жаңа кілт сұрайтын экран болсын: API 401 қайтарады.