Kaspi Pay обслуживает 14+ млн пользователей в Казахстане, контролируя 72% рынка онлайн-платежей по данным Нацбанка на апрель 2026.

Интеграция Kaspi Pay позволяет бизнесу принимать платежи от 80% казахстанцев мгновенно. В 2026 году объем транзакций через Kaspi превысил 15 трлн тенге. Руководство содержит полные HTTP-примеры, webhook-обработку и таблицу комиссий для быстрого запуска.

Бизнес-контекст и предпосылки интеграции

Kaspi Pay доминирует на рынке платежных систем Казахстана: 14,2 млн активных пользователей, 72% доли в онлайн-платежах по данным Нацбанка РК на 1 апреля 2026. Компании вроде Kaspi.kz, ChocoFamily и локальных ритейлеров уже интегрировали API, увеличив конверсию платежей на 45%. Для ТОО/ИП в Казахстане это обязательный инструмент: средний чек онлайн-заказов вырос до 25 000 тенге в 2026.

Предпосылки:

  1. Регистрация ТОО/ИП в налоговой (ЭЦП обязательна).

  2. Открытие мерчант-счета в Kaspi Bank (документы: устав, БИН, реквизиты).

  3. Получение тестовых credentials в Kaspi Pay Dashboard (sandbox.kaspipay.kz).

  4. Сервер с HTTPS, публичный домен, Node.js/PHP/Python backend.

  5. Библиотеки: axios/cURL для HTTP, crypto для HMAC-SHA256.

Регистрация мерчанта занимает 3-5 дней. Комиссии: QR 0,5%, карты 1,5-2%. Sandbox бесплатный, production — после верификации. Такие компании как Alashed IT (it.alashed.kz) предлагают полную интеграцию за 500 000 тенге с гарантией 99,9% uptime. В Алматы и Астане 65% e-commerce используют 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);

Token действует 1 час. Ротация автоматическая. Ошибка 401 — неверные credentials. В продакшене храните токены в Redis с TTL 55 мин.

Создание платежного заказа POST /payment/orders

Основной endpoint: POST https://api.kaspipay.kz/payment/orders. Требует Bearer token.

Полный JSON body:


{

"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-поток: Генерируйте QR из qrData поля ответа. Скан через 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 предпочтительнее для мобильного трафика (85% в KZ). Redirect — для десктопа. Оба возвращают callback на webhook.

Обработка webhook с HMAC-SHA256 верификацией

Kaspi отправляет POST на callback_url при изменении статуса.

Пример 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 дней. Проверяйте статус каждые 30 сек в течение 5 мин после создания.

Типичные ошибки и решения

401 Unauthorized — Неверный token. Решение: обновите OAuth2 token, проверьте 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 мин — Отмена. Решение: polling каждые 30 сек, лимит 100 req/мин.

Логируйте все ошибки с request_id из headers. Alashed IT рекомендует Sentry для мониторинга. Тестируйте 100+ транзакций в sandbox.

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

В Казахстане 87% смартфонов имеют Kaspi SuperApp (данные 2026). E-commerce вырос на 42% до 3,2 трлн тенге. Алматы/Астана: 68% ритейла интегрировали Kaspi Pay. Для ТОО комиссия 0,5% выгоднее карточек (1,5%). Средний бизнес экономит 2,8 млн тенге/год на платежах. Astana Hub резиденты получают приоритетную поддержку Kaspi. Локальные разработчики (Alashed IT) интегрируют за 3 дня vs 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 downtime (1%), duplicate orders (0,2%). Решение: HMAC-верификация, уникальные reference. Uptime API 99,97%.

Сколько времени занимает интеграция?

Sandbox: 1 день. Production: 3-5 дней с верификацией. Alashed IT — 72 часа full-cycle.

Лучшие практики для Kaspi Pay в e-commerce?

QR + redirect, polling 30 сек, webhook backup. Конверсия 78% при QR. Тестируйте 500+ транзакций.

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

Источники