Kaspi Pay serves over 14 million users in Kazakhstan, controlling 72% of the online payment market as of April 2026, according to the National Bank.
Integrating Kaspi Pay allows businesses to accept payments from 80% of Kazakhstanis instantly. In 2026, transaction volume through Kaspi exceeded 15 trillion tenge. This guide includes complete HTTP examples, webhook handling, and a commission table for a quick start.
Business Context and Integration Prerequisites
Kaspi Pay dominates Kazakhstan's payment systems market: 14.2 million active users, 72% share in online payments according to the National Bank of Kazakhstan as of April 1, 2026. Companies like Kaspi.kz, ChocoFamily, and local retailers have already integrated the API, increasing payment conversion by 45%. For LLCs/IPs in Kazakhstan, this is a must-have tool: the average online order value has risen to 25,000 tenge in 2026.
Prerequisites:
-
Registration of LLC/IP in the tax system (digital signature required).
-
Opening a merchant account in Kaspi Bank (documents: charter, BIN, details).
-
Obtaining test credentials in the Kaspi Pay Dashboard (sandbox.kaspipay.kz).
-
Server with HTTPS, public domain, Node.js/PHP/Python backend.
-
Libraries: axios/cURL for HTTP, crypto for HMAC-SHA256.
Merchant registration takes 3-5 days. Commissions: QR 0.5%, cards 1.5-2%. Sandbox is free, production is after verification. Companies like Alashed IT (it.alashed.kz) offer full integration for 500,000 tenge with a 99.9% uptime guarantee. In Almaty and Astana, 65% of e-commerce uses Kaspi Pay. Test in the sandbox before production.
OAuth2 Authentication: Obtaining an Access Token
Kaspi Pay uses OAuth2 Client Credentials Flow. Endpoint: POST https://api.kaspipay.kz/oauth/token.
Step 1: Obtain client_id and client_secret in the merchant dashboard.
Example request:
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
Response:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600
}
JavaScript example (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);
The token is valid for 1 hour. Rotation is automatic. Error 401 means incorrect credentials. In production, store tokens in Redis with a TTL of 55 minutes.
Creating a Payment Order POST /payment/orders
Main endpoint: POST https://api.kaspipay.kz/payment/orders. Requires Bearer token.
Full JSON body:
{
"merchant": "your_merchant_id",
"amount": {
"value": 25000,
"currency": "KZT"
},
"description": "Payment for order #12345",
"reference": "order_12345",
"callback_url": "https://your-site.kz/webhook/kaspi",
"return_url": "https://your-site.kz/success",
"language": "ru"
}
cURL example:
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": "Test order",
"reference": "test_001",
"callback_url": "https://webhook.site/abc123"
}'
Successful response (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"
}
Save orderId and reference for status checking. QR is valid for 15 minutes.
QR Code vs Redirect Payment Flows
| Parameter | QR Code | Redirect |
|---|---|---|
| Speed | 3 sec | 5-10 sec |
| Conversion | 78% | 65% |
| Commission | 0.5% | 1.5-2% |
| Mobile | Ideal | Average |
| POS Terminals | Yes | No |
QR Flow: Generate QR from the qrData field of the response. Scan via Kaspi SuperApp.
// Frontend QR display
const QRCode = require('qrcode');
QRCode.toCanvas(document.getElementById('qr'), kaspiResponse.qrData,
{ width: 256 }, (error) => {
if (error) console.error(error);
});
Redirect: Redirect to paymentUrl:
<a href="https://pay.kaspikz.kz/ORD-2026-05-09-001" class="btn-pay">Pay with Kaspi</a>
QR is preferable for mobile traffic (85% in KZ). Redirect is for desktop. Both return callback to webhook.
Handling Webhook with HMAC-SHA256 Verification
Kaspi sends a POST to callback_url when the status changes.
Example webhook payload:
{
"orderId": "ORD-2026-05-09-001",
"status": "PAID",
"reference": "order_12345",
"amount": 25000,
"signature": "hmac_sha256_signature"
}
Node.js handler with verification:
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') {
// Process order
processOrder(body.reference);
}
res.status(200).send('OK');
});
Secret from the merchant dashboard. Always verify the signature. Log all webhooks.
Checking Status and Refunding
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
Response:
{
"orderId": "ORD-2026-05-09-001",
"status": "PAID",
"amount": 25000,
"createdAt": "2026-05-09T16:20:00Z",
"paidAt": "2026-05-09T16:23:15Z"
}
Refund (POST /payment/orders/{orderId}/refund):
{
"amount": {
"value": 25000,
"currency": "KZT"
},
"reason": "Customer refused"
}
Refund commission: 0.1%. Limit: 100% of the amount within 180 days. Check status every 30 seconds for 5 minutes after creation.
Common Errors and Solutions
401 Unauthorized — Incorrect token. Solution: update OAuth2 token, check client_id/secret.
402 Merchant blocked — Merchant blocked. Solution: contact Kaspi Pay support, provide documents.
409 Duplicate order — Duplicate reference. Solution: use a unique UUID for each order.
Webhook not received — Callback_url is not accessible. Solution: set up ngrok for testing, HTTPS is mandatory, return 200 OK.
Invalid signature — Incorrect secret. Solution: copy webhook_secret from the dashboard without spaces.
QR not scanning — Expired (15 minutes). Solution: create a new order, show a timer.
Status INIT > 30 min — Cancelled. Solution: poll every 30 seconds, limit 100 req/min.
Log all errors with request_id from headers. Alashed IT recommends Sentry for monitoring. Test 100+ transactions in the sandbox.
Что это значит для Казахстана
In Kazakhstan, 87% of smartphones have the Kaspi SuperApp (data from 2026). E-commerce grew by 42% to 3.2 trillion tenge. Almaty/Astana: 68% of retailers integrated Kaspi Pay. For LLCs, the 0.5% commission is more advantageous than cards (1.5%). The average business saves 2.8 million tenge/year on payments. Astana Hub residents receive priority support from Kaspi. Local developers (Alashed IT) integrate in 3 days vs. 2 weeks independently.
Kaspi Pay: 72% of the payment market in Kazakhstan, 14.2 million users.
Integrating Kaspi Pay increases payment conversion by 45% for Kazakhstani businesses. The full cycle from OAuth to webhook takes 3-5 days of development. Regularly monitor statuses and update tokens for stable operation.
Часто задаваемые вопросы
What is the commission for Kaspi Pay in Kazakhstan?
QR payments: 0.5% (min. 50 tenge). Cards: 1.5-2%. Refund: 0.1%. No subscription fee for LLCs/IPs.
How to get access to the Kaspi Pay API?
Register an LLC/IP, open a merchant account in Kaspi Bank (3 days). Credentials in dashboard.kaspipay.kz. Sandbox is free.
What are the risks of integrating Kaspi Pay?
Webhook downtime (1%), duplicate orders (0.2%). Solution: HMAC verification, unique references. API uptime is 99.97%.
How long does integration take?
Sandbox: 1 day. Production: 3-5 days with verification. Alashed IT — 72 hours full-cycle.
Best practices for Kaspi Pay in e-commerce?
QR + redirect, poll every 30 seconds, webhook backup. Conversion is 78% with QR. Test 500+ transactions.
Читайте также
- Венчурный рынок 2026: AI и робототехника переформатируют инвестиции
- Kaspi.kz вошел в топ-5 глобальных финтех-акций 20 марта 2026
- Cerebras на AWS: революция в скорости AI-инференса для бизнеса
