«Подключить кассу» шебері қадам-қадам: 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_…) -> сіздің сұраныстарыңыз
xapi_… кілтін жасап, кассаға оның атауымен жүгінесіз.Жалпы көрініс пен API v2 артықшылықтары үшін xpayment виртуалды кассирі қалай жұмыс істейді мақаласын қараңыз.
Кассаны үш қадамнан тұратын шебер қосады. Кассы и счета (Кассалар мен шоттар) бөлімін ашып, Подключить кассу (Кассаны қосу) түймесін басыңыз.
Шебер үш тармақты белгілеуді сұрайды. Қосылу көбіне солардың бірінен сәтсіз болады:
| Тармақ | Түсініктеме |
|---|---|
| Менде ЖК (ИП) немесе ЖШС (ТОО) бар | Касса ақшаны жеке картаға емес, бизнес шотына қабылдайды |
| Мен Kaspi Pay аккаунтының иесімін | Kaspi Pay қосымшасы немесе pay.kaspi.kz арқылы кіру |
| Бөлек нөмірді кассир ретінде қостым | Кассир нөмірі басқа Kaspi Pay аккаунтының иесі бола алмайды |
Мұнда Kaspi нұсқаулығына сілтеме де бар: «Кассирді қалай қосуға болады». Барлық тармақ белгіленгенде, Продолжить (Жалғастыру) түймесін басыңыз.
Үш өрісті толтырыңыз:
| Өріс | Сипаттама | Мысал |
|---|---|---|
| Название кассы (Касса атауы) | Өзіңізге түсінікті атау, кабинетте көрсетіледі | Қабылдау бөлмесіндегі касса |
| Имя для API (API атауы) | API v2-де кассаны таңдайтын атау. Латын әріптері мен сандар, 1-ден 32 символға дейін | Kassa1 |
| Kaspi Pay-де кассир ретінде қосылған нөмір | Оған кодпен SMS келеді | +7 700 123 45 67 |
«API атауы» ережелері:
^[A-Za-z0-9]{1,32}$);Kassa1 және kassa1 — бір нәрсе); сәйкес келсе, DEVICE_NAME_TAKEN қатесін аласыз;PUT /v1/devices/{deviceID}), бірақ ескі атауды қолданатын сұраныстарды да жаңартыңыз.Кодты сұраңыз. Код келмесе, нөмірдің шынымен Kaspi Pay-де кассир ретінде қосылғанын және иесіне тиесілі емес екенін тексеріңіз.
Сахна сыртында:
SMS-тегі кодты енгізіп (қазір Kaspi 4 таңбалы код жібереді), растаңыз.
Сахна сыртында:
Код қате немесе мерзімі өтсе (CHALLENGE_EXPIRED қатесі), 2-қадамға оралып, жаңа код сұраңыз. Пайдаланылған код CHALLENGE_ALREADY_USED қайтарады.
Бұл кезде кілт берілмейді. Касса дайын, бірақ API кілтін өзіңіз жасайсыз, бұл — келесі қадам.
xapi_… түріндегі мәнді көшіріңіз.xapi_a1b2c3d4e5f6… (xapi_ + 64 таңба)
Кілтті бірден көшіріңіз. Ол бір рет қана көрсетіледі. xpayment тек SHA-256 хэшін сақтайды және кілтті қалпына келтіре алмайды. Жоғалтсаңыз, кілтті жойып (отозвать), жаңасын жасаңыз.
Кілтпен не істеу керек:
.env) немесе құпиялар менеджерінде сақтаңыз.Кассаларыңыздың тізімін сұраңыз:
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-код немесе түйме ретінде көрсетіп, нәтижені вебхуктан күтіңіз.
Кілтті орта айнымалысында сақтаңыз және оны ешқашан браузерге жібермеңіз.
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, ... }
}
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
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);
}
device_name-ді кодта емес, баптауларда сақтаңыз: сонда боевой және тест кассасының арасында ауысу оңай.POST /v2/payments үшін X-Idempotency-Key жіберіңіз, сонда қайталанған сұраныс дубль жасамайды.payment.completed күтіңіз.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-ні қолданыңыз.