Толық нұсқаулық: Kaspi-ден бірінші төлемге дейін

Қадамдық нұсқаулық: Kaspi Pay кассирін жасаңыз, кассаны қосыңыз, API v2 кілтін алыңыз, вебхукты баптаңыз және бәрін sandbox-та тексеріңіз. Сайт, бот, CRM немесе кодсыз.

xpayment-ке қош келдіңіз

Бұл — xpayment-ті Kaspi Pay-ге қосудың шолу маршруты: бос аккаунттан бірінші төлемге дейін. Ол қадамдардың реттілігін түсініп, адаспауға көмектеседі. Егжей-тегжейлі нұсқаулықтар жеке мақалаларда, әр қадамда сілтеме берілген.

Қазір Kaspi Pay қолдау табады, басқа төлем жүйелері кейінірек қосылады. Сатып алушылардың ақшасы тікелей сіздің Kaspi шотыңызға түседі: xpayment оны сақтамайды.

Төлем қабылдаудың екі жолы

Кассаны қосқаннан кейін (төмендегі 1–2 қадам) төлемді қалай қабылдайтыныңызды таңдайсыз:

Жол Кімге арналған Не қажет
Кодсыз Әзірлеушісі жоқ дүкен, студия, репетитор, қызмет Кабинетте төлем сілтемесін немесе онлайн жазылуды жасап, сілтемені клиентке жіберіңіз. Толығырақ: Бағдарламалаусыз төлем қабылдау
API v2 арқылы Сайт, Telegram-бот, CRM, қосымша, SaaS xapi_… кілті, POST /v2/payments/link немесе POST /v2/payments сұранысы және вебхук

Кассаны қосу екі жағдайда да қажет, ал кілт пен вебхук тек API арқылы жұмыс істегенде керек.

Қосылу қалай өтеді

  1. Kaspi Pay-ді дайындап, кассир қосыңыз
  2. xpayment-те кассаны қосыңыз
  3. API v2 кілтін жасап, бірінші сұранысты жіберіңіз
  4. Вебхукты баптаңыз (API үшін): xpayment вебхуктары
  5. Бәрін sandbox-та тексеріңіз нақты ақшасыз: Sandbox
  6. Төлем сценарийін таңдаңыз: алдымен салыстыру — QR, deeplink немесе телефон нөмірі бойынша қашықтан төлем, содан кейін іске асыру — POST /v2/payments немесе POST /v2/payments/link

Сізге не қажет болады

Не қажет Не үшін
ЖК (ИП) немесе ЖШС (ТОО) және Kaspi Pay аккаунты Касса ақшаны жеке картаға емес, бизнес шотына қабылдайды
Kaspi Pay қосымшасы бар смартфон Иесі мен кассир үшін
Бөлек телефон нөмірі Шектеулі кассир рөлі үшін. Ол басқа Kaspi Pay аккаунтының иесі болмауы керек
xpayment-ке кіру Google арқылы немесе құпиясөзбен
Вебхуктың ашық HTTPS мекенжайы Тек API үшін: жүйеңіз төлем күйлерін алуы үшін

Соңында не аласыз

  1. Иесінің негізгі аккаунтына қолжетімділіктің орнына Kaspi Pay-дегі шектеулі кассир. Кассир төлем қабылдап, тек өз операцияларын көре алады. Ақша аудара да, компания теңгерімін көре де алмайды.
  2. xpayment-тегі касса түсінікті API атауымен, мысалы, Kassa1.
  3. API v2 кілті xapi_…. Бір кілт барлық кассаларыңызбен жұмыс істейді және касса қайта қосылса да жұмысын жалғастырады.
  4. Қолтаңбасы бар вебхуктар: төлем туралы автоматты хабарламалар.
  5. Сайт, бот, CRM, SaaS немесе n8n үшін төлем қабылдау тәсілі.

Бағасы қанша

Алдымен сынақ қолжетімділігінің 3 тегін күні: API, QR, deeplink және телефонға шотты тексеруге жеткілікті. Содан кейін төлем көлемі бойынша тіркелген тарифті таңдайсыз: «Старт» — 10 000 ₸/ай (айына 250 төлемге дейін), «Рост» — 25 000 ₸/ай (2 000 төлемге дейін) немесе «Масштаб» — 60 000 ₸/ай (төлем саны шектеусіз). Тіркелген тариф сәйкес келмесе, 1–4% пайыздық модельді таңдауға болады. Комиссияны калькуляторда есептеуге болады.

1-қадам. Kaspi Pay-ді дайындау

Алдымен Kaspi Pay жағын дайындаңыз: бизнес-аккаунттың белсенді екеніне көз жеткізіп, құқықтары шектеулі жеке кассир жасаңыз. Экраннан экранға толық нұсқаулықты мұнда қайталамаймыз, ол жеке мақалада: Kaspi Pay кассирін онлайн төлемдер үшін қалай қосуға болады.

Kaspi Pay-де нені тексеру керек

xpayment-ке өтпес бұрын мыналарды тексеріңіз:

  1. Сізде ЖК (ИП) немесе ЖШС (ТОО) және белсенді Kaspi Pay бизнес-аккаунты бар, сіз оның иесісіз.
  2. Kaspi Pay-де сауда нүктесі жасалған.
  3. Кассир үшін бөлек телефон нөмірі бар. Ол басқа Kaspi Pay аккаунтының иесі болмауы керек.
  4. Кассир Kaspi Pay қосымшасына SMS-сілтеме арқылы кіре алады.

Неге дәл кассир

xpayment бизнес иесінің негізгі аккаунтымен жұмыс істемейді. Үшінші тарап сервисіне қолжетімділік беру қорқынышты екенін түсінеміз, сондықтан қауіпсіз модель «Кассир» рөлі төңірегінде құрылған: ол шектеулі және тек төлем қабылдауға арналған.

Кассир жасай алады Кассир жасай алмайды
Төлем қабылдау Ақша аудару
Өз операциялар тарихын көру Бизнес-аккаунттың бәріне қол жеткізу
Басқа кассирлердің операцияларын көру

Кассирдің деректері бөтен адамның қолына түссе де, бұл рөлмен бизнеске зиян келтіру мүмкін емес. Бұл — төлем қабылдауға жеткілікті ең аз қолжетімділік.

Kaspi-дің ресми материалдары:

Қазір не істеу керек

  1. Kaspi Pay әлі қосылмаса, Kaspi Pay қосымшасында бизнес-аккаунтты белсендіріңіз.
  2. Кассир қосыңыз: Сервисы -> Профиль компании -> Сотрудники -> Добавить, «Кассир» рөлі.
  3. Кассирді қажетті сауда нүктесіне байлаңыз.
  4. Кассирдің нөмірін сақтаңыз: келесі қадамда қажет болады.

Бұл кезеңді толық білгіңіз келсе, кассир туралы жеке мақаланы ашып, толық өтіңіз де, 2-қадамға оралыңыз.

2-қадам. xpayment-те кассаны қосу

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

Кіру

  1. xpayment.kz сайтын ашып, Войти через Google (Google арқылы кіру) түймесін басыңыз. Құпиясөзбен де кіруге болады.
  2. Кабинет сұраса, шарттарды қабылдаңыз.

«Касса қосу» шебері

Кассы и счета (Кассалар мен шоттар) бөлімін ашып, Подключить кассу (Кассаны қосу) түймесін басыңыз. Шебер үш қадамнан тұрады:

  1. Бәрі дайын екенін тексеріңіз. Үш тармақты белгілеңіз: сізде ЖК (ИП) немесе ЖШС (ТОО) бар, сіз Kaspi Pay аккаунтының иесісіз, бөлек нөмірді кассир ретінде қостыңыз.
  2. Кассирдің нөмірі. Үш өрісті толтырыңыз:
    • Название кассы (Касса атауы): кез келген түсінікті атау, мысалы, «Қабылдау бөлмесіндегі касса»;
    • Имя для API (API атауы): латын әріптері мен сандар, 32 символға дейін, мысалы, Kassa1. API v2 сұраныстарында кассаны осы атау бойынша таңдайсыз;
    • Kaspi Pay-де кассир ретінде қосылған нөмір: оған кодпен SMS келеді. Kaspi Pay иесінің нөмірі жарамайды.
  3. SMS-код. Кодты енгізіп, растаңыз. Касса қосылды.

Растау кезінде кассирдің телефоны қасыңызда болуы керек.

Кассаны қайта қосу қажет болса

Кейде Kaspi кассаның сессиясын қабылдауды тоқтатады, кабинет оны жұмыс істемейтін ретінде белгілейді. Кассаны қайта қосып, сол API атауын көрсетіңіз. Кодыңызды да, xapi_… кілтіңізді де өзгертудің қажеті жоқ.

Шебер, қателер және тексеру туралы толығырақ: Кассаны қосу және API v2 кілті. Нені және не үшін жасайтыныңыз: xpayment виртуалды кассирі қалай жұмыс істейді.

3-қадам. API v2 кілті және бірінші сұраныс

Касса қосылды, бірақ кілт автоматты түрде берілмейді: оны өзіңіз жасайсыз. Кілт арқылы сервер сұраныстардың сізден келгенін растайды.

Кілт жасау

  1. API-ключи (API кілттері) бөлімін ашып, Ключи API v2 (API v2 кілттері) блогын табыңыз. Бұл — ұсынылатын кілттер: олар xapi_ деп басталады және кассаны қайта қосқанда да жұмыс істей береді.
  2. Кілт жасап, оған ат беріңіз, мысалы, «Сайт» немесе «CRM».
  3. Кілтті бірден көшіріңіз: ол бір рет көрсетіледі, кейін xpayment тек оның SHA-256 хэшін сақтайды және мәнін қалпына келтіре алмайды.

Кілтпен жұмыс ережелері:

Касса кілттері xdev_… («Ключи касс (v1)» блогы) API v1-ге жатады. Ол әлі де қолдау табады, бірақ жаңа интеграциялар үшін API v2-ні пайдаланыңыз.

Бірінші сұраныс

Kassa1 кассасы арқылы 1 500 ₸ төлем сілтемесін жасаңыз:

curl -X POST https://api.xpayment.kz/v2/payments/link \
  -H "Authorization: Bearer xapi_СІЗДІҢ_КІЛТІҢІЗ" \
  -H "Content-Type: application/json" \
  -d '{"device_name": "Kassa1", "amount": 1500, "merchant_order_id": "order-42"}'

Жауапта payment_id, qr_token (QR немесе deeplink үшін мекенжай), qr_operation_id және expire_date болады. qr_token-ді QR-код немесе сілтеме ретінде көрсетіңіз, сатып алушы Kaspi қосымшасында төлейді.

Алдымен нақты ақшасыз байқағыңыз келе ме? Сол сұраныстар sandbox-та xapi_test_… тест кілтімен жұмыс істейді.

4-қадам. Вебхук

Вебхук — төлем күйін өзгерткенде xpayment сіздің серверіңізге жіберетін сұраныс. Соның арқасында клиенттің төлегенін API-ден үнемі сұрап отырудың қажеті жоқ: тапсырыс автоматты түрде расталады.

Қалай жасау керек

  1. Вебхуки (Вебхуктар) бөлімін ашып, + Новый вебхук (Жаңа вебхук) түймесін басыңыз.
  2. Өңдеушіңіздің HTTPS мекенжайын көрсетіңіз, мысалы, https://example.com/webhook.
  3. Оқиғаларды таңдаңыз. Көп жобаларға payment.completed, payment.cancelled, payment.expired және payment.failed жеткілікті. Қайтарым жасасаңыз, payment.refunded және payment.refund_failed қосыңыз.
  4. Secret орнатыңыз: ұзын кездейсоқ жол (openssl rand -hex 32). Әр сұраныс оның көмегімен қол қойылады, сондықтан өрісті бос қалдырмаңыз.
  5. Сақтап, байланысты тексеру үшін Тест түймесін басыңыз.

Бірден нені білу керек

Оқиғалар, қайталаулар және идемпотентті өңдеу туралы толық талдау: xpayment вебхуктары.

5-қадам. Платформаңызға қосу

Кілт бар, касса жұмыс істейді. Әрі қарай не істеу төлемді қалай қабылдағыңыз келетініне байланысты.


А нұсқасы — кодсыз

Әзірлеушіңіз болмаса, сізге кілт те, вебхук та қажет емес. Кабинетте төлем сілтемесін, онлайн жазылуды немесе тұрақты төлемдерді жасап, сілтемені клиентке WhatsApp, Instagram немесе Telegram арқылы жіберіңіз. Клиент Kaspi-де төлейді, ал төлемдер тізімін кабинетте көресіз. Толығырақ: Бағдарламалаусыз төлем қабылдау.


Б нұсқасы — серіктес платформалар (мысалы, tec.delivery)

xpayment серіктес платформасында жұмыс істесеңіз (мысалы, tec.delivery), бәрі қарапайым:

  1. Платформадағы аккаунтыңызға кіріңіз.
  2. Компания баптауларына өтіңіз.
  3. Төлемге немесе xPayment-ке қатысты бөлімді табыңыз.
  4. API-ключи (API кілттері) бөліміндегі API кілтін өріске қойыңыз. Қандай кілт қажет екенін платформаның өзі өрістің жанында көрсетеді.
  5. Баптауларды сақтаңыз.

Осыдан кейін Kaspi Pay арқылы онлайн төлемдер сіздің мекемеңізде өздігінен жұмыс істейді. Серіктес платформалар тізімі кеңейе береді.


В нұсқасы — REST API v2

Сіз әзірлеуші болсаңыз немесе сервисіңіз API арқылы тікелей қосылуды қолдаса, xpayment-пен тікелей жұмыс істеңіз.

  1. Сценарийді таңдаңыз: QR, deeplink немесе телефон нөмірі бойынша қашықтан төлем.
  2. Оны іске асырыңыз:
  3. Төлемді сұрау арқылы емес, вебхуктармен растаңыз.
  4. Төлем күйлері мен қайтарымдарды оқыңыз: xpayment-те FAILED түпкілікті күй емес.
  5. Тарифтері бар SaaS-ыңыз болса, жазылымдар API-ін қараңыз.

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

  1. xpayment.kz/docs бетін ашып, «API v2» бөлімін таңдаңыз.
  2. xapi_… кілтін Bearer токен өрісіне қойыңыз.
  3. Эндпоинтті таңдаңыз, мысалы, POST /payments/link, «Try it» түймесін басып, device_name мен amount толтырыңыз да, сұранысты жіберіңіз.

Касса кілтімен xdev_… API v1 әлі де қолдау табады, бірақ жаңа интеграциялар үшін v2-ні ұсынамыз.


Дайын

Нөлден жұмыс істейтін интеграцияға дейін өттіңіз:

Енді эквайринг өтінімдерінсіз және апталап келісусіз Kaspi Pay төлемдерін қабылдай аласыз. Алғашқы 3 күн тегін; кейін тіркелген тарифті немесе пайыздық модельді таңдайсыз: кабинеттегі «Тариф и баланс» (Тариф және теңгерім) бөлімі мен калькулятор.

Бірдеңе дұрыс болмаса, осы бөлімдегі басқа мақалаларды қараңыз немесе қолдау қызметіне жазыңыз.