xpayment виртуалды кассирі және API v2 кілті қалай жұмыс істейді

Kaspi Pay кассирі xpayment-те қалай кассаға айналады, API v2 кілті касса кілтінен несімен ыңғайлы және сайт, бот, CRM немесе n8n үшін не аласыз.

Бизнесте Kaspi Pay және жеке кассир бұрыннан болса, келесі қадам — сол кассирді өніміңіз үшін қауіпсіз API-арнаға айналдыру. xpayment.kz ішінде бұл Kaspi Pay кассирі, кабинеттегі касса және backend төлемдерді басқаратын xapi_… кілті тізбегі болып көрінеді.

Терминдер туралы. Кабинетте бұл нысан касса деп аталады («Кассы и счета»), API v2-де кассаны device_name бойынша таңдайсыз, ал API v1-де және ішкі атауларда оны құрылғы дейді. Интеграцияны бизнеске түсіндіргенде виртуалды кассир дейміз: пайдаланушы үшін бұл xpayment жағындағы қосылған кассир. Төрт сөздің бәрі бір нәрсені білдіреді.

xpayment — Kaspi-дің ресми өнімі емес. Бұл — тәуелсіз интеграциялық платформа: қазір Kaspi Pay қолдау табады және онлайн төлемдер үшін бір қабат ретінде құрылады, басқа төлем жүйелері кейін қосылады. Бұл мақала сәулетті және қосылудың мәнін түсіндіреді. Экрандармен қадамдық процесс үшін Кассаны қосу және API v2 кілті мақаласын қараңыз.

Қысқа жауап

Логика мынадай:

Kaspi Pay кассирі -> xpayment-тегі касса (виртуалды кассир, device_name) -> API v2 кілті xapi_… -> қосымшаңыз -> төлем күйі туралы вебхук

Қосылғаннан кейін өніміңіз мыналарды істей алады:

Виртуалды кассир дегеніміз не

xpayment-тегі виртуалды кассир — Kaspi Pay-дегі жаңа қызметкер емес. Бұл — Kaspi Pay-де бұрын жасалған кассир өніміңіз үшін қауіпсіз API-арнаға айналатын қосылу моделі.

xpayment-те кассаны қосу = жаңа виртуалды кассир қосу

Нысан Қайда тұрады Не үшін қажет
Кассир Kaspi Pay Төлем қабылдауға арналған шектеулі рөл
Касса / виртуалды кассир xpayment («Кассы и счета») Кассир нөмірін кабинетіңізге байлайды; API атауы (device_name)
API v2 кілті xapi_… xpayment («API-ключи») Backend-тің барлық кассаларыңыздың төлемдеріне қолжетімділігі
Вебхук Сіздің серверіңіз Күйлердің автоматты жаңаруы

Kaspi Pay жағында сіз әдеттегі Кассир рөлімен жұмыс істейсіз. xpayment жағында бұл кассир өніміңізге қауіпсіз қосылатын касса ретінде көрінеді.

API v2 кілті неге ыңғайлы

API v1-де xdev_… кілті бір кассаға байланған: касса қайта қосылса, жаңа кілт керек, ал кодты өзгертуге тура келеді. API v2 басқаша жұмыс істейді:

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

Схема неге сенімді көрінеді

xpayment бизнес иесінің негізгі аккаунтына қолжетімділік сұрамайды. Біз қосылуды Kaspi Pay өзінің ресми материалдарында сипаттайтын шектеулі кассир рөлі төңірегінде құрамыз:

Кассир ақша аудара алмайды және бөтен операцияларды көрмейді, ал сатып алушылардың ақшасы тікелей сіздің Kaspi шотыңызға түседі. Ол үшін банкпен келісімшарт та, VPN де қажет емес: бар Kaspi Pay аккаунтыңызды пайдаланасыз.

Қосар алдында не дайындау керек

  1. Бөлек телефон нөмірі бар Kaspi Pay кассирі (басқа Kaspi Pay аккаунтының иесі емес).
  2. Кассирдің телефоны қасыңызда: оған SMS-код келеді.
  3. xpayment.kz кабинетіне қолжетімділік.
  4. Төлем сценарийі түсінікті: төлем сілтемесі, QR, deeplink немесе телефонға шот.
  5. Күйлер CRM-ге, сайтқа, SaaS-қа немесе n8n-ге түсуі керек болса, вебхуктың ашық HTTPS мекенжайы.

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

xpayment-те қосылу қалай көрінеді

  1. xpayment-ке кіріңіз.
  2. Кассы и счета (Кассалар мен шоттар) → Подключить кассу (Кассаны қосу) бөлімін ашыңыз.
  3. Үш тексеруді белгілеп, касса атауын, «Имя для API» (API атауы) және кассир нөмірін енгізіңіз.
  4. SMS-тегі кодты енгізіңіз.
  5. API-ключи (API кілттері) бөлімінде API v2 кілтін xapi_… жасаңыз.

Экрандармен толық процесс: Кассаны қосу және API v2 кілті.

Кілт шыққаннан кейін не аласыз

xapi_… кілті «бүкіл Kaspi-ге қолжетімділік» бермейді. Ол xpayment арқылы нақты төлем мүмкіндіктерін ашады:

Мүмкіндік Әрі қарай қайда
Клиентке телефон нөмірі бойынша шот жіберу POST /v2/payments арқылы қашықтан төлемдерді қабылдау
Төлем сілтемесін, QR немесе deeplink жасау POST /v2/payments/link арқылы төлем сілтемелері
Төлем растауын автоматты алу xpayment вебхуктары
Қайтарым жасау немесе төлемді тоқтату Төлем күйлері мен қайтарымдар
Нақты ақшасыз тестілеу Sandbox
SaaS пайдаланушыларының тарифтері мен қолжетімділігін басқару Жазылымдар API-і

Виртуалды кассирдің мәні — қолмен «тағы бір түймені басу» емес, сайт, CRM, бот, SaaS немесе no-code сценарий үшін басқарылатын API-ағынды алу.

Мұндай модель қайда ерекше пайдалы

Өнім Виртуалды кассир не береді
Интернет-дүкен Чекаут төлемді автоматты жасап, вебхукты күтеді
Telegram-бот Бот кассирдің қолмен жұмысынсыз сілтеме, QR немесе шот жібереді
CRM Менеджер клиентке телефон нөмірі бойынша шот шығарады
SaaS / биллинг Төлем шот немесе жазылым ағынынан жасалады
n8n HTTP Request түйіні API-ді шақырады, Webhook түйіні CRM немесе ERP-ді жаңартады

Бірден сақтаған жөн ережелер

  1. Тек кассирді қосыңыз, иесінің негізгі аккаунтын емес.
  2. xapi_… кілтін тек серверде немесе құпиялар менеджерінде сақтаңыз.
  3. merchant_order_id-ді ішкі тапсырыс идентификаторы ретінде сақтаңыз.
  4. Сұраныстар қайталануы мүмкін жерде X-Idempotency-Key қолданыңыз.
  5. Тапсырыс күйін сілтеме ашылғанда немесе сұраныс жасалғанда емес, вебхук бойынша өзгертіңіз.
  6. Әр вебхуктың қолтаңбасын тексеріңіз.

Әрі қарай не оқу керек