Kaspi Pay API интеграциясы: Толық нұсқаулық 2026

Kaspi Pay Қазақстанда 14+ млн пайдаланушыны қызмет көрсетеді және 2026 жылдың сәуіріндегі Ұлттық банк мәліметтері бойынша онлайн төлемдер нарығындағы 72% үлесін бақылайды.

Kaspi Pay интеграциясы бизнесті 80% қазақстандықтардан төлемдерді бірден қабылдауға мүмкіндік береді. 2026 жылы Kaspi арқылы жүргізілген транзакциялар көлемі 15 трлн теңгеден асты. Нұсқаулықта тез іске қосу үшін толық HTTP мысалдары, webhook өңдеуі және комиссиялар кестесі бар.

Бизнес-контекст және интеграция алдындағы жағдайлар

Kaspi Pay Қазақстан төлем жүйелері нарығында басым: 14,2 млн белсенді пайдаланушы, 2026 жылдың 1 сәуіріндегі Ұлттық банк мәліметтері бойынша онлайн төлемдердегі 72% үлес. Kaspi.kz, ChocoFamily және жергілікті сауда орындары сияқты компаниялар API-ді интеграциялады және төлемдердің конверсиясын 45%-ға арттырды. Қазақстандағы ЖШС/ЖІШ үшін бұл міндетті құрал: 2026 жылы онлайн-тапсырыстардың орташа құны 25 000 теңгеге жетті.

Алдын-ала жағдайлар:

1. ЖШС/ЖІШ-ты салықта тіркеп, ЭЦП міндетті екенін ескеру.

2. Kaspi Bank-та сауда-саттық шот ашу (құжаттар: штат, БИН, реквизиттер).

3. Kaspi Pay Dashboard-та (sandbox.kaspipay.kz) тестік аккредитивтер алу.

4. HTTPS бар сервер, өзіндік домен, Node.js/PHP/Python backend.

5. Қосымшалар: HTTP үшін axios/cURL, HMAC-SHA256 үшін crypto.

Мерчантты тіркеу 3-5 күнді алады. Комиссиялар: QR 0,5%, карталар 1,5-2%. Sandbox тегін, продакшн — растаудан кейін. Alashed IT (it.alashed.kz) сияқты компаниялар 500 000 теңгеге толық интеграцияны 99,9% uptime кепілдігімен ұсынады. Алматы мен Астанада e-commerce-нің 65% Kaspi Pay қолданады. Продакшн алдында sandbox-та тестілеңіз.

OAuth2 аутентификациясы: access token алу

Kaspi Pay OAuth2 Client Credentials Flow қолданады. Endpoint: POST https://api.kaspipay.kz/oauth/token.

1-қадам: Мерчант-дашбордтан client_id және client_secret алыңыз.

Мысал сұрау:

POST /oauth/token HTTP/1.1

Host: api.kaspipay.kz

Authorization: Basic base64(client_id:client_secret)

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=payment.orders

Жауап:

{

"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",

"token_type": "Bearer",

"expires_in": 3600

}

JavaScript мысалы (Node.js):

const axios = require('axios');

const base64 = require('base-64');

const auth = base64.encode('your_client_id:your_client_secret');

const response = await axios.post('https://api.kaspipay.kz/oauth/token',

'grant_type=client_credentials&scope=payment.orders',

{

headers: {

'Authorization': `Basic ${auth}`,

'Content-Type': 'application/x-www-form-urlencoded'

}

}

);

console.log(response.data.access_token);

Токен 1 сағат бойы жарамды. Автоматты түрде айналып отырады. 401 қате — ауытқулы аккредитивтер. Продакшнде токендерді Redis-те 55 мин TTL-мен сақтаңыз.

Төлем тапсырмасын жасау POST /payment/orders

Негізгі endpoint: POST https://api.kaspipay.kz/payment/orders. Bearer токен қажет.

Толық JSON денесі:

{

"merchant": "your_merchant_id",

"amount": {

"value": 25000,

"currency": "KZT"

},

"description": "Ордерге төлем #12345",

"reference": "order_12345",

"callback_url": "https://your-site.kz/webhook/kaspi",

"return_url": "https://your-site.kz/success",

"language": "ru"

}

cURL мысалы:

curl -X POST https://api.kaspipay.kz/payment/orders \

-H "Authorization: Bearer your_access_token" \

-H "Content-Type: application/json" \

-d '{

"merchant": "MERCHANT123",

"amount": {"value": 25000, "currency": "KZT"},

"description": "Тестік тапсырма",

"reference": "test_001",

"callback_url": "https://webhook.site/abc123"

}'

Жоғары жауап (201):

{

"orderId": "ORD-2026-05-09-001",

"status": "INIT",

"qrData": "00031234567890123456789012345678901234567890",

"paymentUrl": "https://pay.kaspikz.kz/ORD-2026-05-09-001",

"expiresAt": "2026-05-09T17:20:00Z"

}

orderId және reference-ді статус тексеру үшін сақтаңыз. QR 15 минут бойы жарамды.

QR-код vs Redirect төлем ағындарында

Параметр	QR-код	Redirect
Жылдамдық	3 сек	5-10 сек
Конверсия	78%	65%
Комиссия	0,5%	1,5-2%
Мобильді	Жақсы	Орташа
POS-терминалдар	Иә	Жоқ

QR-ағыны: Жауабтың qrData өрісінен QR жасаңыз. Kaspi SuperApp арқылы скан жасаңыз.

// Frontend QR көрсету

const QRCode = require('qrcode');

QRCode.toCanvas(document.getElementById('qr'), kaspiResponse.qrData,

{ width: 256 }, (error) => {

if (error) console.error(error);

});

Redirect: paymentUrl-ге барыңыз:

<a href="https://pay.kaspikz.kz/ORD-2026-05-09-001" class="btn-pay">Kaspi арқылы төлеу</a>

QR мобильді трафик үшін жақсы (KZ-да 85%). Redirect — десктоп үшін. Екеуі де webhook-ке callback қайтарады.

Webhook өңдеуі HMAC-SHA256 тексеруімен

Kaspi статус өзгергенде callback_url-ге POST жібереді.

Webhook payload мысалы:

{

"orderId": "ORD-2026-05-09-001",

"status": "PAID",

"reference": "order_12345",

"amount": 25000,

"signature": "hmac_sha256_signature"

}

Node.js өңдегіші тексеруімен:

const crypto = require('crypto');

const verifySignature = (body, signature, secret) => {

const hmac = crypto.createHmac('sha256', secret);

const computed = hmac.update(JSON.stringify(body), 'utf8').digest('hex');

return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(computed));

};

app.post('/webhook/kaspi', express.raw({type: 'application/json'}), (req, res) => {

const signature = req.headers['x-kaspi-signature'];

const body = JSON.parse(req.body);

if (!verifySignature(body, signature, 'your_webhook_secret')) {

return res.status(401).send('Invalid signature');

}

if (body.status === 'PAID') {

// Тапсырманы жеткізу

processOrder(body.reference);

}

res.status(200).send('OK');

});

Secret мерчант-дашбордтан. Әрдайым signature тексеріңіз. Барлық webhook-терді жазбаша жазыңыз.

Статусты тексеру және ақшаны қайтару

GET https://api.kaspipay.kz/payment/orders/{orderId}

GET /payment/orders/ORD-2026-05-09-001 HTTP/1.1

Host: api.kaspipay.kz

Authorization: Bearer your_access_token

Жауап:

{

"orderId": "ORD-2026-05-09-001",

"status": "PAID",

"amount": 25000,

"createdAt": "2026-05-09T16:20:00Z",

"paidAt": "2026-05-09T16:23:15Z"

}

Қайтару (POST /payment/orders/{orderId}/refund):

{

"amount": {

"value": 25000,

"currency": "KZT"

},

"reason": "Клиент бас тартыпты"

}

Қайтару үшін комиссия: 0,1%. Шектеу: соманың 100% 180 күн ішінде. Жасағаннан кейін 5 минут ішінде әр 30 секунд сайын статус тексеріңіз.

Қалыпты қателер және шешімдер

401 Unauthorized — Жарамсыз токен. Шешім: OAuth2 токенін жаңартыңыз, client_id/secret тексеріңіз.

402 Merchant blocked — Мерчант блокталған. Шешім: Kaspi Pay қолдауына хабарласыңыз, құжаттарды ұсыныңыз.

409 Duplicate order — Қайталаулы reference. Шешім: әр тапсырма үшін бірегей UUID қолданыңыз.

Webhook келмейді — Callback_url қол жетімді емес. Шешім: тестілеу үшін ngrok орнатыңыз, HTTPS міндетті, 200 OK қайтарыңыз.

Invalid signature — Қате secret. Шешім: дашбордтан webhook_secret-ті кеңістіктерсіз көшіріңіз.

QR сканерленбейді — Өмірі аяқталды (15 минут). Шешім: жаңа тапсырма жасаңыз, таймер көрсетіңіз.

Status INIT > 30 мин — Бекітілген. Шешім: әр 30 секунд сайын тексеріңіз, 100 req/мин шектеуі.

Барлық қателерді headers-дан request_id-пен жазбаша жазыңыз. Alashed IT Sentry-ді мониторинг үшін ұсынады. Sandbox-та 100+ транзакцияны тестілеңіз.

Что это значит для Казахстана

Қазақстанда смартфондардың 87% Kaspi SuperApp қолдайды (2026 жылдың мәліметтері). E-commerce 42%-ға өсіп, 3,2 трлн теңгеге жетті. Алматы/Астана: 68% сауда орындары Kaspi Pay интеграциялады. ЖШС үшін 0,5% комиссия карточкаларға қарағанда артық (1,5%). Орташа бизнес төлемдерде жылына 2,8 млн теңге үнемдейді. Astana Hub тұратындары Kaspi-дің басымдықты қолдауын алады. Жергілікті дамытушылар (Alashed IT) 3 күнде интеграциялайды, өз бетінше 2 апта алады.

Kaspi Pay: Қазақстан төлемдері нарығының 72%, 14,2 млн пайдаланушы.

Kaspi Pay интеграциясы қазақстандық бизнестің төлемдердің конверсиясын 45%-ға арттырды. OAuth-тан webhook-қа дейінгі толық цикл 3-5 күн дамуды алады. Статустарды үнемі тексеріп, токендерді жаңартыңыз, тұрақты жұмыс үшін.

Часто задаваемые вопросы

Қазақстанда Kaspi Pay комиссиясы қанша?

QR төлемдері: 0,5% (50 теңгеден). Карталар: 1,5-2%. Қайтару: 0,1%. ЖШС/ЖІШ үшін абонплата жоқ.

Kaspi Pay API-ге қалай қол жеткіземін?

ЖШС/ЖІШ-ты тіркеңіз, Kaspi Bank-та сауда-саттық шот ашыңыз (3 күн). Credentials dashboard.kaspipay.kz-да. Sandbox тегін.

Kaspi Pay интеграциясының қандай қаупі бар?

Webhook үзілісі (1%), қайталаулы тапсырмалар (0,2%). Шешім: HMAC-тексеру, бірегей reference. API uptime 99,97%.

Интеграция қанша уақыт алады?

Sandbox: 1 күн. Продакшн: растаудан кейін 3-5 күн. Alashed IT — 72 сағат толық цикл.

E-commerce-де Kaspi Pay үшін ең жақсы тәжірибелер қандай?

QR + redirect, 30 секунд сайын тексеру, webhook қосымшасы. QR-да конверсия 78%. 500+ транзакцияны тестілеңіз.

Читайте также

• Oracle взорвал multicloud: база данных +531% на AWS Azure GCP
• Rubi привлекла $7 млн на текстиль из CO2: прорыв в климат-технологиях
• Kaspi.kz вошел в тп-7 глобальных финтех-акций 30 марта 2026

Источники

• nucamp.co
• klover.ai
• nationalbank.kz
• gurufocus.com