POST /v2/payments/link арқылы төлем сілтемелері

API v2 арқылы төлем сілтемесін жасап, сатып алушыға кез келген жолмен жіберіңіз: Kaspi даяр төлем экранымен ашылады. QR, deeplink, жарамдылық мерзімі және қайта жасау.

Төлем сілтемесі дегеніміз не

Төлем сілтемесі — нақты соммаға арналған Kaspi QR немесе deeplink. Оны POST /v2/payments/link сұранысымен жасап, сатып алушыға кез келген ыңғайлы жолмен бересіз: сайттағы түйме, экрандағы QR, WhatsApp немесе Telegram хабарламасы, хат. Сатып алушы сілтемені ашады, Kaspi қосымшасы төлем деректері толтырылған күйде іске қосылады, оған тек «Төлеу» түймесін басу қалады.

Басты айырмашылық: сатып алушының телефоны қажет емес

Телефонға шоттан айырмашылығы, мұнда сатып алушының нөмірін білудің қажеті жоқ. Сілтемені тек сомамен және кассамен жасайсыз, ал оны қашан және қай құрылғыдан ашатынын сатып алушы өзі шешеді.

Қашан қолдану керек

Төлем сілтемелері мына жағдайда жарайды:

Телефонға шот жақсырақ, егер:

Әзірлеушіңіз болмаса, дәл осындай сілтемелерді кабинетте кодсыз жасай аласыз: Бағдарламалаусыз төлем қабылдау.

Бұл қалай жұмыс істейді: 30 секундтық жол

Сіздің серверіңіз -> POST /v2/payments/link -> xpayment -> Kaspi QR
     |                                                  |
     | qr_token (сілтеме / QR)                          |
     v                                                  v
 Сатып алушы сілтемені ашады -> Kaspi -> «Төлеу» -> payment.completed вебхугі
  1. Сервер device_name, amount және (жақсырақ) merchant_order_id бар POST /v2/payments/link жібереді.
  2. xpayment Kaspi QR жасайды және qr_token, payment_id және expire_date қайтарады.
  3. Сіз qr_token-ді QR немесе түйме ретінде көрсетесіз.
  4. Сатып алушы Kaspi қосымшасында төлейді.
  5. xpayment payment.completed вебхугін жібереді, сіз тапсырысты орындайсыз.

Бастау үшін не қажет

Не қажет Толығырақ
API атауы бар қосылған касса Кассаны қосу және API v2 кілті
API v2 кілті xapi_… API-ключи (API кілттері) бөлімі → Ключи API v2 (API v2 кілттері)
Вебхук xpayment вебхуктары

Сахна сыртында не болады

API v1: сол ағын касса кілтімен xdev_… POST /v1/payments/link арқылы (device_name-сіз). Ол әлі де қолдау табады.

Сатып алушы не көреді

Сатып алушы мобильді телефоннан төлем сілтемесін басқанда, Kaspi қосымшасы автоматты түрде ашылады және төлем деректері алдын ала толтырылған болады. Ештеңені қолмен енгізудің қажеті жоқ.

Механизм мен оның көрінісін шатастырмаңыз:

Сатып алушының жолы: басудан төлемге дейін

1. Сатып алушы сілтемені алады

Сілтеме кез келген жолмен келуі мүмкін:

2. Сатып алушы сілтемені басады

Телефонда бір рет басу Kaspi-ді ашады. Чекаут ноутбукта ашық болса, сатып алушыға deeplink басқаннан гөрі QR сканерлеу ыңғайлы. Сондықтан төменде екеуі де көрсетілген: мобильді deeplink және компьютердегі QR.

3. Сатып алушы төлемді растайды

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

4. Сіздің серверіңіз төлем туралы біледі

Бірнеше секунд ішінде xpayment COMPLETED күйін байқап, серверіңізге payment.completed вебхугін жібереді. Төлем жазбасында Kaspi берген сатып алушының телефон нөмірі болады.


Сатып алушыда Kaspi қосымшасы болмаса ше?

Сілтемені басқанда, браузер Kaspi қосымшасын ашуға тырысады. Ол орнатылмаған болса, сатып алушы қосымшаны жүктеп алуға немесе веб-нұсқа арқылы кіруге болатын Kaspi бетіне түседі.

Маңызды: сілтеме ұзақ әрекет етпейді. Нақты уақыты жауаптағы expire_date өрісінде, әдетте бірнеше минут. Сатып алушы үлгермесе, жаңа сілтеме жасаңыз.


API: төлем сілтемесін жасау

Сұраныс

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"
  }'
Өріс Түрі Міндетті Сипаттама
device_name string иә Кассаңыздың атауы, мысалы, Kassa1
amount number иә Теңгемен сома
merchant_order_id string жоқ Сіздің тапсырыс идентификаторыңыз. Вебхукта қайтып келеді

200 жауабы

{
  "payment_id": "018f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
  "qr_token": "https://qr.kaspi.kz/553080826307468991696180316421",
  "qr_operation_id": 14893934009,
  "ext_tran_id": "QR14893934009",
  "status": "QrTokenCreated",
  "expire_date": "2026-11-08T16:39:53.000+05:00",
  "environment": "live"
}
Өріс Мәні
payment_id xpayment-тегі төлем ID-і: күйді сұрау, төлемді болдырмау және қайтарым жасау үшін қолданасыз
qr_token Kaspi QR мекенжайы: оны QR ретінде көрсетіңіз немесе deeplink ретінде қолданыңыз
qr_operation_id, ext_tran_id Kaspi-дегі операция идентификаторлары
status Жасалған сәттегі QR-токен күйі
expire_date Сілтеме қашан жұмысын тоқтатады
environment Боевой кілт үшін live, тест кілті үшін sandbox

Сілтемені сатып алушыға қалай көрсету керек

1-нұсқа: сайттағы түйме (ұсынылады)

<a href="https://qr.kaspi.kz/…" class="pay-button">Kaspi арқылы төлеу</a>

Телефонда басқанда Kaspi ашылады. Жауаптағы qr_token-ді серверде қойып, бетті дайын күйде беріңіз.

2-нұсқа: компьютер экранындағы QR

qr_token-ді кез келген кітапханамен QR-код етіп салыңыз (мысалы, JavaScript үшін qrcode немесе Python үшін segno). Сатып алушы оны телефон камерасымен немесе Kaspi қосымшасымен сканерлейді.

3-нұсқа: WhatsApp немесе Telegram хабарламасы

qr_token-ді мәтін ретінде жіберіңіз: №42 тапсырысты төлеңіз: https://qr.kaspi.kz/…. Сілтеме басылады және Kaspi-ді ашады.

TypeScript мысалы

async function startCheckout(orderId: string, amount: number) {
  const res = await fetch("https://api.xpayment.kz/v2/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,
      amount,
      merchant_order_id: orderId,
    }),
  })
  if (!res.ok) throw new Error(`xpayment ${res.status}`)

  const link = await res.json()
  await db.orders.update(orderId, { paymentId: link.payment_id }) // тапсырыс пен төлемді байланыстыру
  return { url: link.qr_token, expiresAt: link.expire_date }
}

Python мысалы

import os
import httpx


def create_link(amount: float, order_id: str) -> dict:
    resp = httpx.post(
        "https://api.xpayment.kz/v2/payments/link",
        headers={"Authorization": f"Bearer {os.environ['XPAYMENT_API_KEY']}"},
        json={
            "device_name": os.environ["XPAYMENT_DEVICE_NAME"],
            "amount": amount,
            "merchant_order_id": order_id,
        },
        timeout=15,
    )
    resp.raise_for_status()
    return resp.json()

Мерзімнің өтуі және қайта жасау

Сілтеме қысқа мерзімді: expire_date қараңыз. Уақыт өтсе, төлем EXPIRED күйін алады және payment.expired вебхугі келеді. Жаңа әрекет үшін жаңа сілтеме жасаңыз.

Бір тапсырысқа бірнеше сілтеме болуы мүмкін: сатып алушы кетіп қалды, QR ескірді, кассир сілтемені қайта жасады. Сондықтан merchant_order_id төлемді емес, тапсырысты анықтайды, ал бір мәнге бірнеше төлем байланысуы мүмкін.

Сол merchant_order_id бар жаңа сілтеме жасағанда, сол тапсырыстың бұрынғы төленбеген сілтемелері тоқтатылады, сонда тек біреуі жұмыс істеп тұрады. Бұл жағдайда бас тарту туралы вебхук жіберілмейді: әйтпесе тапсырыс төленген сілтеме бойынша payment.completed алғаннан кейін тасталған сілтемеден payment.expired ала алар еді.

Жалғыз ерекшелік: Kaspi бұрынғы сілтеменің төленгенін хабарлаған болса, ол сақталады және әдеттегідей payment.completed арқылы аяқталады.

Вебхуктарды merchant_order_id бойынша емес, payment_id бойынша салыстырыңыз.


Күйді қадағалау

Күйлер мен қайтарым ережелері: Төлем күйлері мен қайтарымдар.

Қателер

HTTP Код Себебі
400 VALIDATION_ERROR device_name немесе amount жоқ
401 — Кілт жіберілмеген, жойылған немесе xapi_ емес
404 DEVICE_NOT_FOUND Осындай атаумен белсенді касса жоқ
422 KASPI_ERROR, DEVICE_INACTIVE, DEVICE_TOKEN_REVOKED Сессия немесе касса жарамсыз: кассаны қайта қосыңыз
402, 403, 429 NO_ACTIVE_BILLING, INSUFFICIENT_BALANCE, PAYMENT_BLOCKED, тариф лимиттері Тариф, теңгерім немесе төлем лимитімен мәселе: «Тариф и баланс»