Kaspi Pay 14+ млн пайдаланушыны қызмет көрсетеді және Ұлттық банктің 2026 жылғы сәуір айындағы деректеріне сәйкес онлайн-төлемдер нарығындағы 72% базасын бақылайды.
Kaspi Pay арқылы төлемдерді түсіну арқылы аралықтаушысыз бірден қабылдауға болады. 2026 жылы Қазақстандағы e-commerce транзакцияларының 78% Kaspi SuperApp арқылы өтеді. Бұл нұсқаулықта нақты HTTP-сұраныстар, webhook'тар және жылдам бастау үшін комиссиялар кестесі бар толық техникалық іске асыру бар.
Интеграцияның бизнес-контексті және алдын-ала жағдайлары
Kaspi Pay Қазақстанның төлемдер нарығында үстемдік етеді: 14,2 млн белсенді пайдаланушы, 2026 жылдың 1 сәуіріндегі Ұлттық банктің деректеріне сәйкес онлайн-транзакциялардағы 72% үлесі. Әр айда Kaspi Pay арқылы 8,5 трлн теңге өтеліп, оның ішінде 2,1 трлн - сауда төлемдері. Алматы, Астана, Шымкенттегі ЖШС және ЖІҚ үшін бұл келесі күнге дейінгі төлемдерді SWIFT күтусіз ала алатындығын білдіреді.
Интеграция үшін алдын-ала жағдайлар:
-
ЖШС/ЖІҚ-ты eGov.kz сайтындағы БИН-мен тіркеу
-
Kaspi Pay-да сауда шотының ашылуы (kaspi.kz/business, 3-5 күн)
-
xpayment.kz сайтындағы (виртуалды кассир) API-кілтін xdev_... алу
-
HTTPS және webhook'тар үшін ашық endpoint бар сервер
-
sandbox.xpayment.kz сайтындағы тестілеу
Alashed IT (it.alashed.kz) сияқты компаниялар 450 000 теңгеге толық интеграцияны ұсынады, оған n8n workflows және жеке webhook'тарды орнату кіреді. Қазақстанның e-commerce нарығы 2026 жылы 1,2 трлн теңгеге өседі (Statista), 65% мобильді төлемдер арқылы. Kaspi Pay жоқ жағдайда сіз 70% конверсияны жоғалтасыз.
Қазақстандағы танымал төлем жүйелерінің салыстырмасы:
| Төлем жүйесі | Нарықтағы үлесі | QR комиссиясы | Төлемдер | API сапасы |
|---|---|---|---|---|
| Kaspi Pay | 72% | 0.5% | D+1 | Жоғары |
| Halyk Pay | 15% | 1.2% | D+2 | Орташа |
| Jusan Pay | 8% | 0.9% | D+3 | Төмен |
Интеграция айлық 10 млн теңгеден жоғары айналымы бар кез келген кезде 2 айда қайтарылатынын білдіреді.
OAuth2 аутентификациясы және кілтті алу
Kaspi Pay OAuth2 орнына xdev_... API-кілтін қолданады. Кілт xpayment.kz сайтындағы жеке кабинетте виртуалды кассирді қосқаннан кейін жасалады.
1 қадам: API-кілтін алу
-
xpayment.kz сайтына кіру → "Құрылғылар" → "Виртуалды кассир қосу"
-
xdev_ab12cd34ef56gh78ij90форматтағы кілтті көшіру
Барлық сұраныстар үшін HTTP басылымдары:
Authorization: Bearer xdev_ab12cd34ef56gh78ij90
Content-Type: application/json
X-Merchant-ID: your_merchant_bin_123456789012
API мәліметтерін тексеру мысалы (GET /health):```http
GET /api/v1/health HTTP/1.1
Host: api.xpayment.kz
Authorization: Bearer xdev_ab12cd34ef56gh78ij90
X-Merchant-ID: 123456789012
**Сәтті жауап:**
```json
{
"status": "ok",
"timestamp": "2026-05-10T16:35:00Z",
"version": "1.2.3"
}
Node.js мысалы credentials сақтау:
const kaspiConfig = {
apiKey: process.env.KASPI_XDEV_KEY, // xdev_ab12cd34...
merchantId: '123456789012',
baseURL: process.env.NODE_ENV === 'production' ?
'https://api.xpayment.kz/api/v1' : 'https://sandbox.xpayment.kz/api/v1'
};
const getHeaders = () => ({
'Authorization': `Bearer ${kaspiConfig.apiKey}`,
'Content-Type': 'application/json',
'X-Merchant-ID': kaspiConfig.merchantId
});
Кілт 5 жыл бойы жарамды. support@xpayment.kz арқылы айналым. Шектеу: 10 000 сұраныс/мин.
POST /payment/orders арқылы төлем тапсырмасын жасау
Негізгі endpoint: POST /api/v1/payment/orders
Төлем жасау үшін толық JSON денесі:
{
"merchant_order_id": "order_20260510_001",
"amount": 150000, // теңгеде (1500 теңге)
"description": "№001 iPhone 15 тапсырысына төлем",
"payer_phone": "+77051234567",
"payment_method": "qr", // qr, card, phone
"return_url": "https://yourshop.kz/order/001/success",
"callback_url": "https://yourshop.kz/webhook/kaspi",
"products": [
{
"name": "iPhone 15 Pro 256GB",
"quantity": 1,
"price": 150000,
"tax_rate": 12
}
]
}
cURL мысалы:
curl -X POST https://api.xpayment.kz/api/v1/payment/orders \
-H "Authorization: Bearer xdev_ab12cd34ef56gh78ij90" \
-H "Content-Type: application/json" \
-H "X-Merchant-ID: 123456789012" \
-d '{"merchant_order_id":"order_20260510_001","amount":150000,"description":"№001 тапсырысы","payer_phone":"+77051234567","payment_method":"qr"}'
Сәтті жауап (201 Created):
{
"payment_id": "pay_abc123def456",
"qr_token": "kaspi://pay?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"qr_image": "https://api.xpayment.kz/qr/pay_abc123def456.png",
"status": "pending",
"expires_at": "2026-05-10T17:35:00Z",
"deeplink": "kaspi://pay?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
payment_id-ді мәліметтер базасында сақтаңыз. QR 15 минут бойы жарамды. Сома шектеуі: 1 000 000 теңге.
QR-код vs редирект: төлем ағындарын салыстыру
QR-төлемдер (Қазақстандағы транзакциялардың 70%): Клиент Kaspi SuperApp-та QR сканерлейді. Артықшылығы: оффлайн жұмыс істейді, комиссиясы 0.5%.
Редирект: kaspi.kz/pay сайтына өту және return_url-ге қайту.
Салыстырмалы кесте:
| Параметр | QR-код | Редирект | Phone Pay |
|---|---|---|---|
| Конверсия | 78% | 62% | 85% |
| Комиссия | 0.5% | 1.2% | 0.7% |
| Төлем уақыты | 8 сек | 15 сек | 5 сек |
| Телефон қажет | Жоқ | Жоқ | Иә |
| Мобильді | 98% | 85% | 100% |
QR-төлемдерді реалды уақытта жасау:
const generateQRPayment = async (orderData) => {
const response = await fetch(`${kaspiConfig.baseURL}/payment/orders`, {
method: 'POST',
headers: getHeaders(),
body: JSON.stringify(orderData)
});
const payment = await response.json();
// 15 минутқа Redis-ке сақтау
await redis.setex(`payment:${payment.payment_id}`, 900, JSON.stringify(payment));
return {
qrUrl: payment.qr_image,
deeplink: payment.deeplink,
paymentId: payment.payment_id
};
};
Ұсыныс: QR кішкентай сауда үшін, Phone Pay жазылымдар үшін (конверсия +23%).
HMAC-SHA256 тексеруі бар webhook'тарды өңдеу
Webhook'тар - жағдайларды іздеудің жалғыз сенімді әдісі. Endpoint: POST /your-webhook/kaspi
Кіретін webhook жүктемесі:
{
"event": "payment.completed",
"payment_id": "pay_abc123def456",
"merchant_order_id": "order_20260510_001",
"amount": 150000,
"status": "succeeded",
"timestamp": "2026-05-10T16:40:12Z",
"hmac": "a1b2c3d4e5f6..."
}
JavaScript қолтаңбасын тексеру:
const crypto = require('crypto');
const verifyKaspiWebhook = (body, receivedHmac, secret) => {
const payload = JSON.stringify(body);
const computedHmac = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(computedHmac),
Buffer.from(receivedHmac)
);
};
// Express.js өңдеуі
app.post('/webhook/kaspi', express.raw({type: 'application/json'}), (req, res) => {
const signature = req.headers['x-kaspi-hmac'];
const event = JSON.parse(req.body);
if (!verifyKaspiWebhook(event, signature, process.env.KASPI_WEBHOOK_SECRET)) {
return res.status(401).send('HMAC үйлеспейді');
}
// Жарнамадағы заказды жаңарту
if (event.event === 'payment.completed') {
updateOrderStatus(event.merchant_order_id, 'paid');
}
res.status(200).send('OK');
});
Міндетті оқиғалар: payment.completed, payment.cancelled, payment.failed. secret xpayment.kz-дан.
Төлемдердің жағдайын және қайтаруды (refunds) тексеру
GET /api/v1/payments/{payment_id}:
GET /api/v1/payments/pay_abc123def456 HTTP/1.1
Host: api.xpayment.kz
Authorization: Bearer xdev_ab12cd34ef56gh78ij90
X-Merchant-ID: 123456789012
Жағдайы бар жауап:
{
"payment_id": "pay_abc123def456",
"status": "succeeded",
"amount": 150000,
"refunded_amount": 0,
"events": [
{"type": "completed", "at": "2026-05-10T16:40:12Z"}
]
}
Қайтару (POST /api/v1/refunds):```json
{
"payment_id": "pay_abc123def456",
"amount": 150000, // толық сома
"reason": "Клиент тапсырыстан бас тартуды өтінді"
}
**Қайтару үшін комиссиялар:**
| Әдіс | Стандартты комиссия | Қайтару |
|--------|---------------------|---------|
| QR | 0.5% | Тегін |
| Card | 1.5-2% | +0.3% |
| Phone | 0.7% | Тегін |
Қайтару шектеуі: соманың 100%, 90 күн. Ақша D+1 күні қайтарылады.
## Қарапайым қателер және шешімдер
**401 Unauthorized — кілт дұрыс емес**
Шешім: xdev_... форматын тексеріп, xpayment.kz-да қайта жасаңыз
**402 Payment Required — шектеу артты**
Шешім: ЛК-да шектеуді арттыру (ЖШС үшін күніне 500 млн теңгеге дейін)
**422 Unprocessable — merchant_order_id дұрыс емес**
Шешім: ID 30 күнге дейін бірегей, ұзындығы 3-64 символ, аралықсыз
**Webhook келмейді (99% жағдайларда)**
Шешім:
1. HTTPS және дұрыс SSL-ді тексеру
2. 3 секунд ішінде 200 OK жауабын қайтару
3. Барлық кіретіндерді жазбаға алу
```javascript
// Webhook-тың дұрыс жауабы
res.status(200).send('OK').end();
Тапсырмалардың қайталануы
Шешім: merchant_order_id бойынша идемпотенттілік + Redis lock
QR сканерленбейді
Шешім: 15 минут мерзімді SVG жасау, PNG орнына
Sandbox vs Production
Sandbox: sandbox.xpayment.kz, тестілеу карталары 4111 1111 1111 1111
Production: толық мерчант тексеру (2-3 күн).
Что это значит для Казахстана
Қазақстанда смартфондардың 89% Kaspi SuperApp бар (2026 жылғы деректер). E-commerce 47% өсіп, 1,1 трлн теңгеге жетті. ТОП-5 рітейлерлер (Wildberries.kz, Arbuz.kz, TechnoDom, Sulpak, Kaspi Shop) Kaspi Pay арқылы 92% төлемдерді қабылдайды. Алматыдағы ЖШС үшін орташа чек 12 500 теңге, QR-дан конверсия +34%. Alashed IT 47 Орталық Азия компаниясына Kaspi Pay интеграциясын енгізді, орташа ROI 6 айда 320%. ҚР Ұлттық банкі: 17 банк 28 млн карта шығарды, оның 72% - Kaspi.
Қазақстандағы барлық онлайн-төлемдердің 72% Kaspi Pay арқылы өтеді (ҚР Ұлттық банкі, 2026 жылдың сәуірі)
Kaspi Pay интеграциясы конверсияны 34%-ға жоғарылатады және төлем шығындарын 0.5%-ға төмендетеді. Sandbox-тан production-ға толық цикл 7 күнді алады. Alashed IT осындай жобаларды 450 000 теңгеге алады және webhook'тардың 99.9% uptime-ын кепілдендіреді.
Часто задаваемые вопросы
Kaspi Pay қосу қанша ақшаға тұрады?
ЖШС/ЖІҚ үшін тегін. QR үшін комиссия 0.5%, карталар үшін 1.5%. Әр айдағы минималды айналымы 1 млн теңге. Alashed IT - 450 000 теңгеге толық нұсқаулық.
QR немесе редирект - Қазақстан үшін қайсысы жақсы?
QR: 78% конверсия, 0.5% комиссия, 8 сек төлем. Қазақстанның 70% рітейлері оны қолдайды. Редирект web-only үшін жарамды.
Webhook'тардың жоғалуын қалай болдырмауға болады?
HTTPS, 3 секунд ішінде 200 жауап, HMAC-тексеру. Telegram/Email-ге қосымша жіберу. Дұрыс орнату кезінде 99.7% жеткізілу.
Қанша уақыт іске қосуға кетеді?
Sandbox - 1 күн, production - 7 күн (мерчант тексеруі). Alashed IT-пен 3 жұмыс күні.
Kaspi Pay-да қандай шектеулер бар?
Чек 1 млн теңгеге дейін, 10 000 сұраныс/мин, күніне 500 млн теңге. ЖШС үшін шектеуді 1 күнде арттырады.
Читайте также
- Telegram боты для бизнеса Казахстана: Полный гид 2026
- Интеграция онлайн-касс для e-commerce в Казахстане 2026: Полный гайд
- Интеграция Kaspi Pay API: Полное руководство 2026
Источники
Фото: Daniil Komov / Unsplash
