API v2 арқылы сатып алушының телефонына шотты қалай шығаруға болады: сұраныс, идемпотенттілік, қателер, код мысалдары және сатып алушы Kaspi-де не көреді.
Телефонға шот (қашықтан төлем) — сатып алушының телефон нөмірі бойынша тікелей Kaspi қосымшасына жіберілетін төлем сұранысы. Сіз POST /v2/payments шақырасыз, xpayment шот шығарады, сатып алушы push-хабарлама алады, оны ашады және не төлейді, не бас тартады. Нәтижені вебхуктан білесіз.
Төлем сілтемесінен басты айырмашылығы: мұнда сатып алушының телефон нөмірі алдын ала қажет.
Клиенттің нөмірі бұрыннан болса жарайды:
Нөмір болмаса немесе сатып алушы тапсырысты сайтта өзі рәсімдесе, төлем сілтемесін қолданыңыз. Сенімді емессіз бе? Нұсқаларды QR, deeplink немесе телефон нөмірі бойынша қашықтан төлем мақаласында салыстырыңыз.
Kassa1: Кассаны қосу және API v2 кілті.xapi_….Сіздің серверіңіз -> POST /v2/payments -> xpayment -> Kaspi-дегі шот
|
сатып алушыға push, төлем
|
Сіздің серверіңіз <- payment.completed вебхугі <- xpayment <- жаңа күй
device_name, телефон және сомасымен POST /v2/payments жібереді.PENDING күйімен қайтарады.payment.completed алады, GET /v2/payments/{payment_id} арқылы төлемді сұрайды және тапсырысты орындайды.Касса кілтімен
xdev_…API v1 әлі де қолдау табады: мекенжайы —POST /v1/payments, кассаны кілттің өзі анықтайды,device_nameөрісі жіберілмейді.
POST /v2/payments арқылы шот шығарғанда, сатып алушы жағында мынадай жағдай болады.
Сатып алушы Kaspi қосымшасында push-хабарлама алады:
Kaspi.kz
ShopMebel дүкені сізге 50 000 ₸ шот шығарды
Хабарлама телефон құлыптаулы болса да, дерлік лезде келеді. Басқанда Kaspi қосымшасы ашылады.
Kaspi шот экранын көрсетеді:
comment өрісі;«Төлеу» түймесін басады. Kaspi соманы таңдалған төлем тәсілінен есептен шығарады, сатып алушы растауды көреді. xpayment жаңа COMPLETED күйін бірнеше секунд ішінде байқайды, ал вебхугіңіз payment.completed алады.
Шоттан бас тартады немесе жауап бермейді. Төлем төленбейді. Kaspi мұны қалай хабарлағанына байланысты, ол CANCELLED, EXPIRED немесе уақытша FAILED күйіне өтеді, ал сіз сәйкес вебхук аласыз. Түйме атауына қарап болжамаңыз: GET /v2/payments/{payment_id} төлем күйіне сүйеніңіз. Сатып алушы ештеңе істемесе, төленбеген шот ең кеші 24 сағат ішінде мерзімі өтеді. Толығырақ: Төлем күйлері мен қайтарымдар.
+77001234567, 87001234567 және 7001234567 пішімдерінде қабылдайды, ал Kaspi бұл нөмірді білуі керек. Мұндай нөмірлі клиент табылмаса, 422 KASPI_CLIENT_NOT_FOUND қатесін аласыз.POST /v2/payments/{payment_id}/cancel.Төмендегі макет сатып алушының телефонында не көретінін көрсетеді:
API v2 кілтімен және касса атауымен POST /v2/payments жіберіңіз:
curl -X POST https://api.xpayment.kz/v2/payments \
-H "Authorization: Bearer xapi_СІЗДІҢ_КІЛТІҢІЗ" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: order-42-attempt-1" \
-d '{
"device_name": "Kassa1",
"payer_phone": "+77001234567",
"amount": 1500,
"comment": "№42 тапсырыс",
"merchant_order_id": "order-42",
"metadata": {"product_id": "sku-999"}
}'
| Өріс | Түрі | Міндетті | Сипаттама |
|---|---|---|---|
device_name |
string | иә | Касса атауы: латын әріптері мен сандар, 32 символға дейін, регистр маңызды емес |
payer_phone |
string | иә | Сатып алушының нөмірі, мысалы, +77001234567 |
amount |
number | иә | Теңгемен сома, нөлден үлкен |
comment |
string | жоқ | Сатып алушы Kaspi-де көретін хабарлама |
merchant_order_id |
string | жоқ | Сіздің тапсырыс идентификаторыңыз. Вебхукта қайтып келеді |
metadata |
object | жоқ | «Кілт-мән» пішіміндегі кез келген деректеріңіз, төлеммен бірге сақталады |
X-Idempotency-Key тақырыбы міндетті емес, бірақ оны әрдайым жіберуді ұсынамыз: сол кілтпен қайталанған сұраныс бұрын жасалған төлемді қайтарады және екінші шот шығармайды. Кілтті басқа төлем ұстап тұрса, API 409 IDEMPOTENCY_CONFLICT жауап береді.
201 жауабы{
"payment_id": "018f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
"device_name": "Kassa1",
"payer_phone": "+77001234567",
"amount": 1500.00,
"currency": "KZT",
"comment": "№42 тапсырыс",
"merchant_order_id": "order-42",
"status": "PENDING",
"metadata": {"product_id": "sku-999"},
"cancel_reason": null,
"cancelled_at": null,
"completed_at": null,
"created_at": "2026-11-08T10:00:00Z",
"updated_at": "2026-11-08T10:00:00Z"
}
payment_id сақтаңыз: күйді сұрау, төлемді болдырмау және қайтарым жасау үшін оны қолданасыз.
async function createInvoice({ phone, amount, orderId }) {
const res = await fetch("https://api.xpayment.kz/v2/payments", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.XPAYMENT_API_KEY}`,
"Content-Type": "application/json",
"X-Idempotency-Key": `invoice-${orderId}`,
},
body: JSON.stringify({
device_name: process.env.XPAYMENT_DEVICE_NAME,
payer_phone: phone,
amount,
merchant_order_id: orderId,
}),
})
if (res.status !== 201) throw new Error(`xpayment ${res.status}: ${await res.text()}`)
return res.json()
}
import os
import httpx
def create_invoice(phone: str, amount: float, order_id: str) -> dict:
resp = httpx.post(
"https://api.xpayment.kz/v2/payments",
headers={
"Authorization": f"Bearer {os.environ['XPAYMENT_API_KEY']}",
"X-Idempotency-Key": f"invoice-{order_id}",
},
json={
"device_name": os.environ["XPAYMENT_DEVICE_NAME"],
"payer_phone": phone,
"amount": amount,
"merchant_order_id": order_id,
},
timeout=15,
)
resp.raise_for_status()
return resp.json()
<?php
function createInvoice(string $phone, float $amount, string $orderId): array
{
$ch = curl_init('https://api.xpayment.kz/v2/payments');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('XPAYMENT_API_KEY'),
'Content-Type: application/json',
'X-Idempotency-Key: invoice-' . $orderId,
],
CURLOPT_POSTFIELDS => json_encode([
'device_name' => getenv('XPAYMENT_DEVICE_NAME'),
'payer_phone' => $phone,
'amount' => $amount,
'merchant_order_id' => $orderId,
]),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 201) {
throw new RuntimeException("xpayment $status: $body");
}
return json_decode($body, true);
}
| HTTP | Код | Себебі |
|---|---|---|
| 400 | VALIDATION_ERROR |
device_name, payer_phone немесе amount жоқ, нөмір пішімі қате немесе сома нөлден үлкен емес |
| 401 | — | Кілт жіберілмеген, жойылған немесе API-дің басқа нұсқасына жатады |
| 404 | DEVICE_NOT_FOUND |
Осындай device_name бар белсенді касса жоқ |
| 409 | IDEMPOTENCY_CONFLICT |
Идемпотенттілік кілтін басқа төлем пайдаланған |
| 422 | KASPI_CLIENT_NOT_FOUND |
Kaspi мұндай сатып алушыны білмейді |
| 422 | KASPI_ERROR, DEVICE_INACTIVE, DEVICE_TOKEN_REVOKED |
Сессия немесе касса жарамсыз: кассаны қайта қосыңыз |
| 402 | NO_ACTIVE_BILLING, INSUFFICIENT_BALANCE |
Тариф белсенді емес немесе теңгерімде қаражат жеткіліксіз («Тариф и баланс») |
| 403 | PAYMENT_BLOCKED |
Ұйымыңыз үшін төлем қабылдау бұғатталған. «Тариф и баланс» бөлімін тексеріңіз немесе қолдау қызметіне жазыңыз |
| 429 | DAILY_TX_LIMIT_REACHED, MONTHLY_PAYMENT_LIMIT_REACHED |
Тарифтің күндік немесе айлық төлем лимиті таусылды |
| 500 | INTERNAL_ERROR |
Күтпеген қате. Сол X-Idempotency-Key кілтімен қайталаңыз |
Төлем алдымен PENDING, содан кейін WAITING_FOR_PAYER (сатып алушы шотты көрді) күйінде болады және нәтижелердің біріне келеді:
| Күй | Нені білдіреді | Болдырмауға бола ма? |
|---|---|---|
PENDING, WAITING_FOR_PAYER |
Шот жасалды, сатып алушыны күтуде | Иә |
COMPLETED |
Сатып алушы төледі | Жоқ, қайтарым жасаңыз |
CANCELLED |
Төлем тоқтатылды | Жоқ |
EXPIRED |
Уақыт өтті немесе сатып алушы растамады | Жоқ |
FAILED |
Kaspi төлемді қабылдамады немесе түсініксіз жауап берді | Иә, төлем әлі аяқталуы мүмкін |
FAILEDтүпкілікті емес.FAILEDкүйіндегі төлем кейінCOMPLETEDбола алады: xpayment оның өмір сүру мерзімі аяқталғанша тексеруді жалғастырады. Мұндай тапсырысты бірден есептен шығармаңыз. Күйлер, бас тарту және қайтарымдар туралы толық талдау: Төлем күйлері мен қайтарымдар.
curl -X POST https://api.xpayment.kz/v2/payments/PAYMENT_ID/cancel \
-H "Authorization: Bearer xapi_СІЗДІҢ_КІЛТІҢІЗ" \
-H "Content-Type: application/json" \
-d '{"reason": "Клиент ойын өзгертті"}'
Төлем аяқталған болса, жауап — 409 PAYMENT_NOT_CANCELABLE.
payment.completed алыңыз, қолтаңбаны тексеріңіз және төлемді сұраңыз: Вебхуктар, Қолтаңбаны тексеру.GET /v2/payments/{payment_id} әр 3–5 секунд сайын.GET /v2/payments?merchant_order_id=order-42.Төлемді скриншоттармен немесе шот жіберілгенінің өзімен тексермеңіз.