API v2 арқылы төлем сілтемесін жасап, сатып алушыға кез келген жолмен жіберіңіз: Kaspi даяр төлем экранымен ашылады. QR, deeplink, жарамдылық мерзімі және қайта жасау.
Төлем сілтемесі — нақты соммаға арналған Kaspi QR немесе deeplink. Оны POST /v2/payments/link сұранысымен жасап, сатып алушыға кез келген ыңғайлы жолмен бересіз: сайттағы түйме, экрандағы QR, WhatsApp немесе Telegram хабарламасы, хат. Сатып алушы сілтемені ашады, Kaspi қосымшасы төлем деректері толтырылған күйде іске қосылады, оған тек «Төлеу» түймесін басу қалады.
Телефонға шоттан айырмашылығы, мұнда сатып алушының нөмірін білудің қажеті жоқ. Сілтемені тек сомамен және кассамен жасайсыз, ал оны қашан және қай құрылғыдан ашатынын сатып алушы өзі шешеді.
Әзірлеушіңіз болмаса, дәл осындай сілтемелерді кабинетте кодсыз жасай аласыз: Бағдарламалаусыз төлем қабылдау.
Сіздің серверіңіз -> POST /v2/payments/link -> xpayment -> Kaspi QR
| |
| qr_token (сілтеме / QR) |
v v
Сатып алушы сілтемені ашады -> Kaspi -> «Төлеу» -> payment.completed вебхугі
device_name, amount және (жақсырақ) merchant_order_id бар POST /v2/payments/link жібереді.qr_token, payment_id және expire_date қайтарады.qr_token-ді QR немесе түйме ретінде көрсетесіз.payment.completed вебхугін жібереді, сіз тапсырысты орындайсыз.| Не қажет | Толығырақ |
|---|---|
| API атауы бар қосылған касса | Кассаны қосу және API v2 кілті |
API v2 кілті xapi_… |
API-ключи (API кілттері) бөлімі → Ключи API v2 (API v2 кілттері) |
| Вебхук | xpayment вебхуктары |
PENDING күйімен сақтайды.payment.completed, payment.expired және т.б.) xpayment вебхук жібереді.API v1: сол ағын касса кілтімен
xdev_…POST /v1/payments/linkарқылы (device_name-сіз). Ол әлі де қолдау табады.
Сатып алушы мобильді телефоннан төлем сілтемесін басқанда, Kaspi қосымшасы автоматты түрде ашылады және төлем деректері алдын ала толтырылған болады. Ештеңені қолмен енгізудің қажеті жоқ.
Механизм мен оның көрінісін шатастырмаңыз:
POST /v2/payments/link ағыны, тек сатып алушы үшін кіру жолы басқа.Сілтеме кез келген жолмен келуі мүмкін:
Телефонда бір рет басу Kaspi-ді ашады. Чекаут ноутбукта ашық болса, сатып алушыға deeplink басқаннан гөрі QR сканерлеу ыңғайлы. Сондықтан төменде екеуі де көрсетілген: мобильді deeplink және компьютердегі QR.
Төлеу түймесін басу транзакцияны іске қосады: Kaspi соманы есептен шығарады, сатып алушы растауды көреді және электронды чек алады.
Бірнеше секунд ішінде xpayment COMPLETED күйін байқап, серверіңізге payment.completed вебхугін жібереді. Төлем жазбасында Kaspi берген сатып алушының телефон нөмірі болады.
Сілтемені басқанда, браузер Kaspi қосымшасын ашуға тырысады. Ол орнатылмаған болса, сатып алушы қосымшаны жүктеп алуға немесе веб-нұсқа арқылы кіруге болатын Kaspi бетіне түседі.
Маңызды: сілтеме ұзақ әрекет етпейді. Нақты уақыты жауаптағы
expire_dateөрісінде, әдетте бірнеше минут. Сатып алушы үлгермесе, жаңа сілтеме жасаңыз.
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 |
<a href="https://qr.kaspi.kz/…" class="pay-button">Kaspi арқылы төлеу</a>
Телефонда басқанда Kaspi ашылады. Жауаптағы qr_token-ді серверде қойып, бетті дайын күйде беріңіз.
qr_token-ді кез келген кітапханамен QR-код етіп салыңыз (мысалы, JavaScript үшін qrcode немесе Python үшін segno). Сатып алушы оны телефон камерасымен немесе Kaspi қосымшасымен сканерлейді.
qr_token-ді мәтін ретінде жіберіңіз: №42 тапсырысты төлеңіз: https://qr.kaspi.kz/…. Сілтеме басылады және Kaspi-ді ашады.
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 }
}
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бойынша салыстырыңыз.
payment.completed, payment.expired, payment.cancelled, payment.failed. Қолтаңбаны тексеріп, содан кейін төлемді payment_id бойынша сұраңыз: Вебхуктар, Қолтаңбаны тексеру.GET /v2/payments/{payment_id} әр 3–5 секунд сайын.GET /v2/payments?merchant_order_id=order-42&status=COMPLETED.Күйлер мен қайтарым ережелері: Төлем күйлері мен қайтарымдар.
| 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, тариф лимиттері |
Тариф, теңгерім немесе төлем лимитімен мәселе: «Тариф и баланс» |