Kaspi Pay қабылдау REST арқылы — мерчант аккаунтының үстінен.

QR мен нөмірге шот қою, мәртебені ұстау және оқиғалар журналын оқу үшін бір REST-API. Kaspi-ге қосылымды платформа сіз үшін ұстап тұрады; сіз HTTP-сұраныс жасайсыз.

Базалық мекенжай

https://api.aitole.kz

Келісімдер

• Ақша — бүтін теңге (integer). Бөлшек сомалар → 422 amount_not_whole.
• Жасау кезіндегі провайдер ақаулығы — 5xx емес: операция мына мәртебеде қайтады: failed себеп коды және HTTP 200. Мына өрісті тексеріңіз: status, тек HTTP-кодын ғана емес.
• Әр жауап мына тақырыпты алып жүреді: X-Request-Id — қолдауға жүгінгенде оны көрсетіңіз.
• Барлық дене — JSON, жауаптағы өрістер — snake_case.

Екі контур: төлемге кілт, кабинетке токен.

Төлем қабылдау мынау арқылы жүреді: API-кілт. Қосылымдар мен кілттерді басқару — мынау арқылы: кабинеттен алынған JWT. Кілт қосылымдарды басқармайды — бұл ол ағып кеткен жағдайға арналған қорғаныс.

X-API-Key: sk_live_hLR0vCVY_…

curl -X POST https://api.aitole.kz/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"…"}'

← 200  { "token": "eyJhbGciOiJIUzI1NiJ9…" }

Бірыңғай қате конверті.

Кез келген қате — сол бір JSON. Мынау бойынша тармақтаңыз: error.code, мәтін бойынша емес. Кодтардың толық тізімі — төменде.

{
  "error": {
    "code": "amount_over_key_cap",
    "message": "Операция сомасы кілт шегінен асады",
    "category": "validation",
    "request_id": "req_79b6…"
  }
}

Kaspi онбордингі — кабинеттен, SMS арқылы.

Мерчант аккаунтын қосу — JWT астындағы үш auth-қадам (owner/admin). Сессия құпиясын платформа шифрланған күйде сақтайды және сыртқа бермейді. Барлық әдіс — Authorization: Bearer.

Қосылым жобасын жасайды. Дене: { "driver": "http" } нақты Kaspi үшін немесе { "driver": "mock" } сынақ ортасы үшін. Жауап — сессия құпиясы жоқ қауіпсіз түрде.

{ "id": "7a3069ab-…", "driver": "http",
  "status": "onboarding", "is_default": false, "created_at": "2026-09-08T…" }

Содан кейін — мынау бойынша үш авторизация қадамы: :id

Kaspi сессиясы және ол неге өледі.

Қосылым кассир нөміріне байланған тірі Kaspi сессиясына сүйенеді. Kaspi-де бір нөмірге бір белсенді сессия — бұл сирек шеткі жағдай емес, тоқтап қалудың басты себебі.

Сессияны не өлтіреді

• Сол нөмірмен Kaspi Pay қосымшасына кіру. Сіздің сессияңыз дереу ығысады — Kaspi мұны бөлек кодпен хабарлайды. Сондықтан платформаға берілген кассир нөмірі бөлек болуы керек: онымен қолмен кірмейді.
• Kaspi жағында сессияның табиғи аяқталуы.

Платформа не істейді

Провайдер сессияны танымайтынын хабарлаған бойда, қосылым мынадан ауыстырылады: active → session_expired, ал журналға оқиға жазылады: connection.session_expired. Мұндай қосылым бойынша мәртебе сұрау тоқтайды — платформа Kaspi-ді өлі сессиямен әлектендірмейді.

Бұл сіздің жағыңыздан қалай көрінеді

• Жаңа төлемдер мынамен қабылданбайды: 409 no_active_connection.
• Мынада: /v2/events пайда болады connection.session_expired.
• GET /me/connections қосылым мәртебесін көрсетеді.

Бірнеше Kaspi аккаунты

Платформаның бір аккаунтында бірнеше нақты қосылым болуы мүмкін — мысалы, әр заңды тұлғаға немесе нүктеге бір-бірден. Төлемге касса мына ретпен таңдалады:

1. connection_id сұраныс денесінде — анық таңдау.
2. Қосылым, оған кілт байланған. Байланыс кілт кабинетте шығарылғанда белгіленеді.
3. «Негізгі» деп белгіленген қосылым.
4. Өз контурындағы жалғыз белсенді қосылым.

Егер контурдың белсенді қосылымы бірнешеу болса, ешқайсысы негізгі деп белгіленбесе және таңдау кілтпен де, сұраныспен де жасалмаса, төлем мынамен қабылданбайды: 409 connection_ambiguous. Ақшаны қай кассаға жіберу керегін платформа болжамайды.

Төлем кассасын қалай білуге болады

Әр төлем оқиғасы мынаны алып жүреді: connection_id — әрі журналда (GET /v2/events), әрі вебхук денесінде. Қосылым оқиғалары да соны алып жүреді. Жазылым мен тариф туралы оқиғаларда касса жоқ: олар тұтас аккаунт туралы.

Вебхукті нақты кассаға жазуға болады: эндпоинт жасағанда мынаны жіберіңіз: connection_id. Мұндай эндпоинт тек соның төлемдерін алады және аккаунт деңгейіндегі оқиғаларды алмайды. Мынасыз эндпоинт: connection_id бұрынғыдай бәрін алады.

Тірі эндпоинттің кассасы мынау арқылы ауыстырылады: PATCH /me/webhooks/:id мына өріспен: connection_id (немесе null, қайтадан бәрін алу үшін). Бұл үшін эндпоинтті қайта жасаудың қажеті жоқ әрі зиянды: жаңасының қолтаңба құпиясы басқа болады.

QR жасау.

QR-төлем қояды. Мына құралды талап етеді: create_qr кілттің scopes ішінде және міндетті тақырып Idempotency-Key.

Дене параметрлері

curl -X POST https://api.aitole.kz/v2/qr \
  -H "X-API-Key: sk_live_…" \
  -H "Idempotency-Key: order-42" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "comment": "Тапсырыс №42"}'

{
  "id": "op_d7834b…",
  "type": "qr",
  "status": "pending",
  "amount": 5000,
  "qr_token": "https://pay.kaspi.kz/…",
  "expires_at": "2026-09-08T00:37:24Z",
  "comment": "Тапсырыс №42",
  "created_at": "2026-09-08T00:32:24Z"
}

qr_token — мынадай сілтеме: pay.kaspi.kz/…; оны QR-код етіп салыңыз немесе клиентке сілтеме ретінде беріңіз. Төлем автоматты түрде ұсталады — мәртебе мынаған ауысады: paid, қараңыз: оқиғалар журналы.

Телефон нөміріне шот.

Клиентке нөмір бойынша Kaspi-де шот жібереді. Мына құралды талап етеді: create_invoice.

curl -X POST https://api.aitole.kz/v2/invoices \
  -H "X-API-Key: sk_live_…" -H "Idempotency-Key: inv-42" \
  -d '{"phone":"+77011234567","amount":12000}'

← 200  { "id":"op_…", "type":"invoice", "status":"pending", "amount":12000 }

Идемпотенттік.

Әр мутация (/v2/qr, /v2/invoices, бас тарту) мына тақырыпты талап етеді: Idempotency-Key — сұраныс мағынасына сәйкес кез келген бірегей жол (мысалы, тапсырыс нөмірі).

• Тақырып жоқ → 422 idempotency_key_required.
• Сол кілт және сол дене → қайтады сол жауап, екінші операция жасалмайды.
• Сол кілт және басқа дене → 409 idempotency_key_conflict.
• Біріншісі әлі орындалып жатқанда қайталау → 429 payment_in_progress.

Сынақ ортасы: төлемнің бүкіл жолы ақшасыз.

Сынақ ортасы — бұл мынадай қосылым: driver: "mock". Нағыз Kaspi қатыспайды, ақша қозғалмайды, qr_token әдейі жалған қайтарылады (mock_qr_…, оны төлеу мүмкін емес).

Төлемді төленгенге дейін жеткізу

Басқару әдістері күйді өзгертеді провайдер жағында, ал операцияңыздың мәртебесін нақты режимдегі сол поллер қозғалтады — сол бірнеше секундтық кідіріспен. Осылайша сіз тірі ақшамен жұмыс істейтін дәл сол кодты тексересіз, оқиғаны өңдеуді қоса.

Операцияны төленді деп белгілейді. Бірнеше секундтан кейін ол мынадай болады: paid, журналда пайда болады: payment.paid.

Операцияны мерзімі өтті деп белгілейді → expired және payment.expired.

Қосылым сессиясын «ығыстырады» — осылайша мынаған өз реакцияңызды тексеруге болады: сессияның өлімі, нақты қосылымды бұзбай. Қосылым мынаған кетеді: session_expired мына оқиғамен: connection.session_expired.

# сынақ ортасында шот қойдық
curl -X POST https://api.aitole.kz/v2/qr \
  -H "X-API-Key: sk_test_…" -H "Idempotency-Key: demo-1" \
  -d '{"amount": 5000}'

# оны «төледік»
curl -X POST https://api.aitole.kz/v2/sandbox/operations/op_…/pay \
  -H "X-API-Key: sk_test_…"

# бірер секундтан кейін мәртебе өзі ауысты
curl https://api.aitole.kz/v2/operations/op_… -H "X-API-Key: sk_test_…"
← { "status": "paid", "paid_at": "…" }

id бойынша операция.

Операцияның жолдарымен қоса ағымдағы күйі. Бөгде операция немесе белгісіз id → 404 operation_not_found.

{ "id":"op_…", "type":"qr", "status":"paid", "amount":5000,
  "provider_id":"qr:…", "paid_at":"2026-09-08T00:33:10Z",
  "comment":"Тапсырыс №42", "items":[], "created_at":"…" }

Мүмкін мәртебелер

created → pending → терминалдық paid, expired, cancelled, failed. Ауысуды платформа поллері автоматты түрде жасайды.

Операциялар тізімі.

Курсорлы таспа, жаңалары алдымен. Жауап: { data, next_cursor, has_more }. Келесі бет үшін мынаны жіберіңіз: next_cursor → cursor.

curl "https://api.aitole.kz/v2/operations?limit=2&status=paid" \
  -H "X-API-Key: sk_live_…"

← 200  { "data":[ … ], "next_cursor":"eyJ0Ijoi…", "has_more":true }

Операциядан бас тарту.

Әлі төленбеген операциядан бас тартады. Жарамсыз ауысу (мысалы, қазірдің өзінде paid) → 409 invalid_state_transition. Белсенді қосылымды талап етеді.

curl -X POST https://api.aitole.kz/v2/operations/op_…/cancel \
  -H "X-API-Key: sk_live_…" -H "Idempotency-Key: cancel-42"

← 200  { "id":"op_…", "status":"cancelled" }

Қайтарым — толық және ішінара.

Операция мына мәртебеде қалады: paid. «Қайтарылды» деген бөлек мәртебе әдейі жоқ: ақша алынды, сосын қайтарылды — бұл екі факт, біреуінің екіншісін алмастыруы емес, және бухгалтерия екеуін де көруі тиіс.

{ "operation_id":"op_…",
  "amount":2500,          // өріссіз — ҚАЛДЫҚ қайтады
  "reason":"клиент тауарды қайтарды" }

{ "id":"…", "operation_id":"op_…",
  "amount":2500, "status":"done",
  "operation":{ "status":"paid", "amount":10000,
                "refunded_amount":2500 } }

Алдын ала нені білу керек

• Бөлек құрал керек: refund кілттің скоупында. Кассаға шот қоюға берілген кілт ақша қайтармауы тиіс — бұл ақшаның кері бағыттағы қозғалысы.
• Қайтарым тек мыналар үшін мүмкін: paid. Төленбеген QR қайтарылмайды: одан бас тартады немесе ол өзі ескіреді.
• Қайтарым терезесі — 90 күн төлем сәтінен бастап, одан әрі refund_window_expired. Бұл — біздің шектеуіміз; Kaspi-дің өз мерзімдері болуы мүмкін, оның бас тартуы мынада келеді: failure_message.
• Idempotency-Key барлық өзгертетін сұраныстардағыдай міндетті. Сол кілтпен қайталау екінші қайтарымды емес, сол нәтижені қайтарады.

Оқиғалар журналы.

Аккаунт оқиғаларының курсорлы таспасы — payment.created, payment.paid, payment.expired, payment.cancelled, payment.refunded және connection.session_expired. Операциялардағы сол query (limit, cursor, type, date_from/to).

{ "data": [
    { "id":"evt_…", "type":"payment.paid",
      "operation_id":"op_…",
      "payload":{ "id":"op_…", "status":"paid", "amount":5000 },
      "created_at":"2026-09-08T00:33:10Z" }
  ], "next_cursor":null, "has_more":false }

Вебхуктер: оқиғалар өзі келеді.

Жазылым жасалады тек кабинеттен, иесінің токенімен. API-кілт мұнда мүлдем жіберілмейді: әйтпесе ағып кеткен интеграция кілті оқиғаларыңызды бөгде мекенжайға әкетуге мүмкіндік берер еді.

Қолжетімді оқиғалар: payment.created, payment.paid, payment.expired, payment.cancelled, payment.refunded, connection.session_expired, connection.restored, webhook.test. Не "*" — бәрі, кейін қосылған оқиғаларды қоса. Аттағы қате бірден қабылданбайды (unknown_event), үнсіз эндпоинтке айналмайды.

{ "id":"…", "url":"https://shop.kz/aitole",
  "events":["payment.paid"], "enabled":true,
  "secret":"whsec_…" }

Не келеді

Конверт-денесі және мына тақырыптары бар POST: X-Webhook-Id, X-Webhook-Event, X-Webhook-Timestamp, X-Webhook-Signature.

{ "id":"evt_…", "type":"payment.paid",
  "created_at":"2026-09-09T10:00:00.000Z",
  "data":{ "id":"op_…", "status":"paid", "amount":5000 } }

Қолтаңбаны тексеру

Тақырып X-Webhook-Signature мынадай түрде sha256=<hex>; қолтаңба — мына жолдан алынған HMAC-SHA256: "{timestamp}.{шикі дене}". Оны есептеңіз сұраныстың шикі байттары бойынша: алдымен JSON-ды талдап, кері жинасаңыз, кілттер реті өзгереді де, қолтаңба сәйкес келмейді.

const raw = await readRawBody(req);           // дәл байттар, JSON.parse емес
const ts  = req.headers['x-webhook-timestamp'];
const got = req.headers['x-webhook-signature'];  // "sha256=abc…" түрінде

// sha256= префиксі қолтаңбаға кіреді — жолды тұтас есептейміз
const mine = 'sha256=' + crypto.createHmac('sha256', secret)
  .update(`${ts}.${raw}`).digest('hex');

// тұрақты уақытпен салыстыру — === емес
const a = Buffer.from(mine), b = Buffer.from(got);
const ok = a.length === b.length && crypto.timingSafeEqual(a, b);

// әрі міндетті түрде жаңалығы: әйтпесе ұсталған сұранысты қайталауға болады
if (!ok || Math.abs(Date.now()/1000 - ts) > 300) return res.status(400).end();
res.status(200).end();                          // жылдам жауап беріңіз

Қайталаулар және өшіру

Сәттілік — кез келген жауап 2xx. Қалғанының бәрі (10 секундтық таймаутты қоса) — сәтсіздік, біз қайталаймыз: мына аралықпен: 1 мин, 5 мин, 30 мин, 2 сағ, 6 сағ, 24 сағ. Әр әрекет кабинетте көрінеді: жауап коды, ұзақтығы, қате мәтіні.

Егер эндпоинт бас тартса үздіксіз екі тәулік, біз оны өшіріп, жіберуді тоқтатамыз — әйтпесе кезек өлі мекенжаймен бітеледі. Кабинетте қайта қосуға болады; тоқтап тұрған кездегі оқиғалар мынау арқылы қолжетімді: /v2/events.

Мекенжайға қойылатын талаптар

Тек https әрі тек ашық мекенжай. localhost, 127.0.0.1, ішкі диапазондар мен бұлттық метадеректер мекенжайы жасалу кезінде қабылданбайды — әрі жеткізу сәтінде қайта тексеріледі, сондықтан ішкі желіге шешілетін домен көмектеспейді. Жергілікті әзірлеу үшін туннель қолданыңыз.

Кабинеттегі «Тексеру» батырмасы мынаны жібереді: webhook.test — нағыз қолтаңбасы бар нағыз жеткізуді, дәл сол эндпоинтке, төлемді күтпей.

Жиілік шектеулері.

Нақты кілттер — минутына 200 сұраныс. Сынақ кілттері (sk_test_…) — шектеусіз. Асып кетсе — 429 rate_limit_exceeded мына тақырыппен: Retry-After.

Тариф шектеулері.

Шектеу екеу: күнтізбелік айда қанша төлем қабылдауға болады және бір мезгілде қанша операция төленбей тұра алады.

Нақты не саналады

• Айлық квота — тек ТӨЛЕНГЕН төлемдер. 50 шот қойдыңыз, 12-сі төленді — 12 жұмсалды. Тасталған және мерзімі өткен шоттар квотаны жұмсамайды.
• Ай күнтізбелік, Астана уақыты бойынша (UTC+5). Квота 1-ші күні жаңарады.
• Сынақ ортасы шектеулерді жұмсамайды: сынақ кілттері бөлек саналады және айлық шектеуі жоқ (бір мезгілде белсендісі — 10).
• Бұрыннан тұрған төленбеген шоттар квотадан тыс төленуі мүмкін — жолда келе жатқан ақшадан платформа бас тартпайды.
• Бір мезгілде төленбеген шоттар шегі де бар — бұл тариф опциясы емес, адал пайдалануды қорғау: тұрған әр шотты платформа Kaspi-ден сұрайды, олардың тым көп болуы сіздің өз сессияңызға зиян. Шек жомарт, қалыпты жұмыста оны байқамайсыз; ағымдағы мәні кабинетте көрінеді.

Бас тартулар

Ағымдағы тариф пен жұмсалу мынада көрінеді: кабинетте және жауапта GET /me.

Қате кодтары.

Health.

Қолжетімділікті тексеру — кілтсіз. Аптайм-мониторингке жарайды.

{ "status":"ok", "checks":{ "database":"ok", "redis":"ok" } }

Интеграция бойынша сұрақ — мынаны қоса беріңіз: X-Request-Id жауаптан.