Кассаны қосу және API v2 кілті

«Подключить кассу» шебері қадам-қадам: API атауы (device_name), SMS-кодты енгізу, xapi_… кілтін жасау және GET /v2/devices арқылы қосылымды тексеру.

Касса дегеніміз не

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

Бұл не үшін қажет

Талаптар

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

Бұл қалай жұмыс істейді

Кассир нөмірі -> Kaspi-ден SMS-код -> xpayment-тегі касса -> API v2 кілті (xapi_…) -> сіздің сұраныстарыңыз
  1. Шеберде кассирдің нөмірін енгізесіз.
  2. Kaspi сол нөмірге SMS-код жібереді.
  3. Кодты енгізесіз, ал xpayment Kaspi Pay аккаунтыңызбен қорғалған сессия орнатады. Ол үшін xpayment касса үшін өзінің криптографиялық кілттер жұбын (ECDSA P-256) жасайды.
  4. Касса кабинетте пайда болады. Әрі қарай xapi_… кілтін жасап, кассаға оның атауымен жүгінесіз.

Жалпы көрініс пен API v2 артықшылықтары үшін xpayment виртуалды кассирі қалай жұмыс істейді мақаласын қараңыз.

Кассаны қосу: қадамдық нұсқаулық

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


1-қадам. Бәрі дайын екенін тексеріңіз

Шебер үш тармақты белгілеуді сұрайды. Қосылу көбіне солардың бірінен сәтсіз болады:

Тармақ Түсініктеме
Менде ЖК (ИП) немесе ЖШС (ТОО) бар Касса ақшаны жеке картаға емес, бизнес шотына қабылдайды
Мен Kaspi Pay аккаунтының иесімін Kaspi Pay қосымшасы немесе pay.kaspi.kz арқылы кіру
Бөлек нөмірді кассир ретінде қостым Кассир нөмірі басқа Kaspi Pay аккаунтының иесі бола алмайды

Мұнда Kaspi нұсқаулығына сілтеме де бар: «Кассирді қалай қосуға болады». Барлық тармақ белгіленгенде, Продолжить (Жалғастыру) түймесін басыңыз.


2-қадам. Кассирдің нөмірі

Үш өрісті толтырыңыз:

Өріс Сипаттама Мысал
Название кассы (Касса атауы) Өзіңізге түсінікті атау, кабинетте көрсетіледі Қабылдау бөлмесіндегі касса
Имя для API (API атауы) API v2-де кассаны таңдайтын атау. Латын әріптері мен сандар, 1-ден 32 символға дейін Kassa1
Kaspi Pay-де кассир ретінде қосылған нөмір Оған кодпен SMS келеді +7 700 123 45 67

«API атауы» ережелері:

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

Сахна сыртында:


3-қадам. SMS-код

SMS-тегі кодты енгізіп (қазір Kaspi 4 таңбалы код жібереді), растаңыз.

Сахна сыртында:

Код қате немесе мерзімі өтсе (CHALLENGE_EXPIRED қатесі), 2-қадамға оралып, жаңа код сұраңыз. Пайдаланылған код CHALLENGE_ALREADY_USED қайтарады.

Бұл кезде кілт берілмейді. Касса дайын, бірақ API кілтін өзіңіз жасайсыз, бұл — келесі қадам.


4-қадам. API v2 кілтін жасаңыз

  1. API-ключи (API кілттері) → Ключи API v2 (API v2 кілттері) бөлімін ашыңыз.
  2. Кілт жасап, оған ат беріңіз (мысалы, «Сайт»).
  3. xapi_… түріндегі мәнді көшіріңіз.
xapi_a1b2c3d4e5f6…  (xapi_ + 64 таңба)

Кілтті бірден көшіріңіз. Ол бір рет қана көрсетіледі. xpayment тек SHA-256 хэшін сақтайды және кілтті қалпына келтіре алмайды. Жоғалтсаңыз, кілтті жойып (отозвать), жаңасын жасаңыз.

Кілтпен не істеу керек:

  1. Оны backend орта айнымалыларында (.env) немесе құпиялар менеджерінде сақтаңыз.
  2. Репозиторийге коммит жасамаңыз және frontend-ке салмаңыз.
  3. Әртүрлі жүйелер (сайт, CRM, бот) үшін бөлек кілттер қолданыңыз: оларды бөлек жою оңай. Ең көбі — пайдаланушыға 10 белсенді кілт.

Қосылымды тексеріңіз

Кассаларыңыздың тізімін сұраңыз:

curl https://api.xpayment.kz/v2/devices \
  -H "Authorization: Bearer xapi_СІЗДІҢ_КІЛТІҢІЗ"

Жауапта әр белсенді касса үшін device_name, name және session_problem_since бар: Kaspi кассаның сессиясын қабылдауды тоқтатқан уақыт. Ол null болса, касса жұмыс істейді.

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

Касса тізімінде немесе касса бетінде Подключить заново (Қайта қосу) әрекетін қолданыңыз:

Негізгісі: жаңа кассаны сол «API атауымен» қосыңыз, сонда device_name: "Kassa1" бар сұраныстар кодты да, xapi_… кілтін де өзгертпей жұмысын жалғастырады. Атауды әлі басқа белсенді касса ұстап тұрса, DEVICE_NAME_TAKEN қатесін аласыз.

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

Кілтті қосымшада қолдану

Касса қосылды, xapi_… кілті қолыңызда. Енді оны backend-ке қосыңыз.

Жылдам бастама: бірінші сұраныс

API v2-ге барлық сұраныстар https://api.xpayment.kz/v2 мекенжайына Authorization: Bearer xapi_… тақырыбымен барады. Кассаны сұраныс денесінде device_name бойынша көрсетесіз:

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"}'

200 жауабы:

{
  "payment_id": "018f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
  "qr_token": "https://qr.kaspi.kz/553080826307468991696...",
  "qr_operation_id": 14893934009,
  "ext_tran_id": "QR14893934009",
  "status": "QrTokenCreated",
  "expire_date": "2026-11-08T16:39:53.000+05:00",
  "environment": "live"
}

qr_token-ді QR-код немесе түйме ретінде көрсетіп, нәтижені вебхуктан күтіңіз.

Интеграция мысалдары

Кілтті орта айнымалысында сақтаңыз және оны ешқашан браузерге жібермеңіз.

Node.js

const API = "https://api.xpayment.kz/v2"

async function createPaymentLink({ amount, orderId }) {
  const res = await fetch(`${API}/payments/link`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.XPAYMENT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      device_name: process.env.XPAYMENT_DEVICE_NAME, // мысалы, Kassa1
      amount,
      merchant_order_id: orderId,
    }),
  })
  if (!res.ok) throw new Error(`xpayment ${res.status}: ${await res.text()}`)
  return res.json() // { payment_id, qr_token, expire_date, ... }
}

Python

import os
import httpx

API = "https://api.xpayment.kz/v2"
HEADERS = {"Authorization": f"Bearer {os.environ['XPAYMENT_API_KEY']}"}


def create_payment_link(amount: float, order_id: str) -> dict:
    resp = httpx.post(
        f"{API}/payments/link",
        headers=HEADERS,
        json={
            "device_name": os.environ["XPAYMENT_DEVICE_NAME"],
            "amount": amount,
            "merchant_order_id": order_id,
        },
        timeout=15,
    )
    resp.raise_for_status()
    return resp.json()

PHP

<?php

function createPaymentLink(float $amount, string $orderId): array
{
    $ch = curl_init('https://api.xpayment.kz/v2/payments/link');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('XPAYMENT_API_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS     => json_encode([
            'device_name'       => getenv('XPAYMENT_DEVICE_NAME'),
            'amount'            => $amount,
            'merchant_order_id' => $orderId,
        ]),
    ]);
    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status !== 200) {
        throw new RuntimeException("xpayment $status: $body");
    }
    return json_decode($body, true);
}

Негізгі тұстар

  1. Кілт тек серверде тұрады. Ол браузерге, репозиторийге немесе логқа түсіп кетсе, API-ключи (API кілттері) бөлімінде оны жойып, жаңасын жасаңыз.
  2. Касса атауы — конфигте. device_name-ді кодта емес, баптауларда сақтаңыз: сонда боевой және тест кассасының арасында ауысу оңай.
  3. Идемпотенттілік. POST /v2/payments үшін X-Idempotency-Key жіберіңіз, сонда қайталанған сұраныс дубль жасамайды.
  4. Вебхукпен растау. Сілтеме жасалған бойда тапсырысты төленді деп белгілемеңіз: payment.completed күтіңіз.
  5. Sandbox-та тестілеңіз xapi_test_… кілтімен және test кассасымен: Sandbox.

Мүмкін қателер

HTTP Код Не істеу керек
400 VALIDATION_ERROR device_name (латын әріптері мен сандар), amount (> 0) және payer_phone тексеріңіз
401 — Кілт жоқ, жойылған немесе басқа түрде. xapi_ тек /v2-де, xdev_ тек /v1-де жұмыс істейді
404 DEVICE_NOT_FOUND Сізде осындай device_name бар белсенді касса жоқ
422 KASPI_ERROR, DEVICE_INACTIVE, DEVICE_TOKEN_REVOKED Кассаның сессиясы жарамсыз: оны сол атаумен қайта қосыңыз
409 DEVICE_NAME_TAKEN Атауды басқа белсенді касса ұстап тұр (қосу кезінде)

API v1. xdev_… касса кілті және /v1/... мекенжайлары әлі де қолдау табады. Онда кассаны кілттің өзі анықтайды, сондықтан денеде device_name қажет емес, бірақ кассаны қайта қосуға жаңа кілт керек. Жаңа интеграциялар үшін v2-ні қолданыңыз.

Әрі қарай не