Интеграция Kaspi Pay API в 2026 году: полный теничес...

Kaspi Pay сегодня охватывает более 14 миллионов активных пользователей в Казахстане и проводит миллионы операций ежедневно. У многих офлайн и онлайн‑бизнесов доля платежей через Kaspi превышает 60–70 % оборота. Ошибки в интеграции этой платежной системы напрямую превращаются в потерянную выручку и жалобы клиентов.

Этот материал — подробный технический гид по интеграции Kaspi Pay API для backend‑разработчиков, CTO и собственников бизнеса в Казахстане. Разберем путь от регистрации ТОО/ИП и получения мерчант‑аккаунта до production‑запуска с обработкой вебхуков и возвратов. Покажем реальные примеры HTTP‑запросов, JSON‑структур, OAuth2‑аутентификации, HMAC‑проверки подписи и разницу между QR‑ и redirect‑флоу. Гид основан на практическом опыте команд, которые ежедневно внедряют платежные нтеграции для e‑commerce, HoReCa, доставки и SaaS, включая такие компании как Alashed IT (it.alashed.kz).

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

Kaspi Pay за последние годы стал де‑факто стандартом приема платежей для малого и среднего бизнеса в Казахстане. По публичным данным Kaspi.kz, база активных пользователей превышает 14 миллионов человек, а мобильное приложение стабильно входит в топ‑1 по количеству ежедневных сессий в стране. Для многих магазинов, служб доставки и онлайн‑сервисов доля транзакций через Kaspi QR и Kaspi Red достигает 60–80 % всех безналичных платежей. На практике это означает, что отсутствие корректной и удобной интеграции Kaspi Pay может приводить к потере до половины потенциальной выручки.

С точки зрения бизнеса, типичные сценарии использования Kaspi Pay API в 2026 году:

• интернет‑магазины и маркетплейсы (создание платежных заказов из корзины);

• доставочные сервисы еды и товаров (QR‑оплата курьеру, онлайн‑предоплата);

• SaaS‑платформы и b2b‑сервисы (выставление счетов клиентам);

• офлайн‑ритейл и услуги (динамический QR на кассе, интегрированный с учетной системой).

Для юридической интеграции требуются:

1. Регистрация ТОО или ИП в Казахстане (БИН/ИИН, банковский расчетный счет в тенге). На практике многие компании открывают отдельный расчетный счет для платежей Kaspi, чтобы упростить бухгалтерию.

2. Заключение договора мерчанта с Kaspi Pay через личный кабинет бизнеса. Обычно это занимает от 1 до 3 рабочих дней после подачи онлайн‑заявки.

3. Получение доступа к Kaspi Pay API: выдаются client_id, client_secret, merchantId и данные для подключения к sandbox‑среде (если она доступна для вашего тарифного плана).

С технической стороны prerequisites для команды разработки:

• backend на любом языке (Node.js, Java, .NET, Go, PHP), способный выполнять исходящие HTTPS‑запросы и принимать входящие вебхуки;

• возможность хранить секреты (client_secret, webhook_secret) в защищенном виде: environment variables, Vault, KMS;

• поддержка TLS 1.2+ и современных шифров (обычно это уже есть в стандартных HTTP‑клиентах);

• доступный домен с HTTPS для приема вебхуков, например api.myshop.kz или pay.mycompany.kz.

Такие интеграции обычно ведутся в связке: бизнес собирает требования, а техническая реализация ложится на команду разработчиков или внешнего партнера. В Казахстане часто привлекают интеграторов вроде Alashed IT (it.alashed.kz), которые знают нюансы процессинга, фискализации и интеграции с 1С/ERP.

Дальше в гайде мы пройдем полный цикл: аутентификация по OAuth2, создание платежного заказа через POST /payment/orders, сравнение QR и redirect сценариев, обработка вебхуков с HMAC‑подписью, проверки статуса и возвраты, а также чек‑лист запуска в прод и типичные ошибки, которые стоит предотвратить еще на этапе разработки.

OAuth2 аутентификация в Kaspi Pay API: получение access token

Большинство современных платежных API, включая Kaspi Pay, используют OAuth2 Client Credentials Flow для машинной аутентификации. Backend‑сервис мерчанта сначала получает короткоживущий access token, а затем использует его в заголовке Authorization для всех запросов к платежному API.

Чаще всего точка входа выглядит как POST /oauth2/token или /oauth/token. Ниже пример запроса к условному OAuth2 endpoint Kaspi Pay (адрес и поля могут отличаться в вашей документации, но структура типична):

POST https://pay.kaspi.kz/oauth2/token HTTP/1.1

Host: pay.kaspi.kz

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

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=payments

Пример успешного ответа с access token в формате JSON:

{

"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",

"token_type": "Bearer",

"expires_in": 3600,

"scope": "payments",

"merchantId": "MERCHANT_123456"

}

В typical Node.js backend проще всего сделать вспомогательную функцию для получения токена. Пример на JavaScript (Node.js, axios):

const axios = require('axios');

async function getKaspiAccessToken() {

const params = new URLSearchParams();

params.append('grant_type', 'client_credentials');

params.append('client_id', process.env.KASPI_CLIENT_ID);

params.append('client_secret', process.env.KASPI_CLIENT_SECRET);

params.append('scope', 'payments');

const response = await axios.post('https://pay.kaspi.kz/oauth2/token', params.toString(), {

headers: {

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

},

timeout: 5000

});

return {

token: response.data.access_token,

expiresIn: response.data.expires_in

};

}

Важно:

• Никогда не логируйте client_secret и полный access_token в продакшене, максимум первые и последние 4 символа для диагностики.

• Обновляйте токен заранее, за 1–2 минуты до истечения срока действия, либо на каждый запрос, если нагрузка невысокая.

• При ответах 401 Unauthorized со стороны Kaspi Pay сначала пробуйте обновить токен, а затем ретраить запрос.

Пример использования токена в последующем запросе:

GET https://pay.kaspi.kz/api/v1/payment/orders/123456 HTTP/1.1

Host: pay.kaspi.kz

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Accept: application/json

Если у вас микросервисная архитектура, имеет смысл вынести получение токена в отдельный сервис или библиотеку, которой будут пользоваться другие сервисы. Такие компании как Alashed IT часто поставляют заказчикам готовые SDK или internal packages для .NET/Java/Node.js, чтобы унифицировать работу с Kaspi Pay и уменьшить количество ошибок с аутентификацией.

Создание платежного заказа в Kaspi Pay API и сравнение QR vs redirect флоу

Основная операция в Kaspi Pay API для интернет‑платежей — создание платежного заказа. Обычно используется endpoint вида POST /api/v1/payment/orders. В теле запроса вы передаете сумму, валюту, идентификатор вашего заказа, описание и настройки сценария оплаты (QR, redirect, оплата в приложении Kaspi и т.д.).

Пример запроса на создание зказа с QR‑оплатой:

POST https://pay.kaspi.kz/api/v1/payment/orders HTTP/1.1

Host: pay.kaspi.kz

Authorization: Bearer ACCESS_TOKEN

Content-Type: application/json

{

"merchantId": "MERCHANT_123456",

"orderId": "ORDER-100045",

"amount": 15000,

"currency": "KZT",

"description": "Оплата заказа #100045 в интернет-магазине MyShop.kz",

"paymentMethod": "QR",

"successUrl": "https://myshop.kz/payment/success?orderId=ORDER-100045",

"failUrl": "https://myshop.kz/payment/fail?orderId=ORDER-100045",

"callbackUrl": "https://api.myshop.kz/kaspi/webhook",

"customer": {

"phone": "+77011234567",

"email": "client@example.com"

},

"extra": {

"source": "web",

"locale": "ru"

}

}

Пример успешного ответа Kaspi Pay:

{

"orderId": "ORDER-100045",

"kaspiOrderId": "KASPI-7788990011",

"status": "PENDING",

"amount": 15000,

"currency": "KZT",

"paymentMethod": "QR",

"qr": {

"imageUrl": "https://pay.kaspi.kz/qr/7788990011.png",

"payload": "KASPIQR|2|KZ123456789|15000|ORDER-100045"

},

"redirectUrl": null,

"createdAt": "2026-05-10T08:25:30Z"

}

Если вы хотите использовать redirect flow (перенаправление клиента на платежную страницу Kaspi), меняется параметр paymentMethod и добавляется redirectUrl в ответе:

POST https://pay.kaspi.kz/api/v1/payment/orders HTTP/1.1

Authorization: Bearer ACCESS_TOKEN

Content-Type: application/json

{

"merchantId": "MERCHANT_123456",

"orderId": "ORDER-100046",

"amount": 23990,

"currency": "KZT",

"description": "Оплата подписки SaaS на 1 месяц",

"paymentMethod": "REDIRECT",

"successUrl": "https://saas.kz/pay/success",

"failUrl": "https://saas.kz/pay/fail",

"callbackUrl": "https://api.saas.kz/kaspi/webhook"

}

Пример ответа с redirectUrl:

{

"orderId": "ORDER-100046",

"kaspiOrderId": "KASPI-8899001122",

"status": "PENDING",

"amount": 23990,

"currency": "KZT",

"paymentMethod": "REDIRECT",

"qr": null,

"redirectUrl": "https://pay.kaspi.kz/pay/KASPI-8899001122",

"createdAt": "2026-05-10T08:30:02Z"

}

Ключевые отличия QR‑ и redirect‑флоу для бизнеса и разработки:

Параметр	QR-флоу на экране/чеке	Redirect-флоу через Kaspi Pay страницу
UX	Клиент сканирует QR в приложении	Клиент переходит по ссылке и платит в браузере
Основной канал	Офлайн, курьеры, кассы, web-оплата	Онлайн‑магазины, мобильные приложения
Скорость оплаты	Обычно быстрее, клиент привык	Зависит от качества интернета
Требования к фронтенду	Отрисовка PNG/SVG QR	Редирект http 302 или window.location
Риск закрытия вкладки	изкий	Средний, особенно на мобильных
Интеграция с кассой	Удобно для фискализации	Требует связи orderId с чеком

На практике многие компании в Казахстане используют гибридный подход: для web‑checkout — redirect, для выдачи QR курьерам или в офлайн‑точках — QR‑флоу. Интегратор вроде Alashed IT помогает выстроить правильный сценарий в зависимости от процента онлайн‑канала, среднего чека и доминирующей аудитории (мобильный vs десктоп).

Платежный флоу, вебхуки Kaspi Pay и HMAC-SHA256 подпись на JavaScript

Чтобы ваш backend знал, когда платеж успешно оплачен или отклонен, Kaspi Pay отправляет уведомления (webhooks) на callbackUrl, указанный при создании заказа. Это критический элемент интеграции: именно вебхук должен менять статус заказа в вашей системе и запускать выдачу товара, активацию подписки или печать чека.

Типичный сценарий:

1. Вы создаете заказ через POST /payment/orders с callbackUrl.

2. Клиент оплачивает в приложении Kaspi или на странице Kaspi Pay.

3. Kaspi Pay отправляет POST на ваш webhook URL с JSON телом и заголовком подписи.

4. Ваш сервер проверяет HMAC‑SHA256 подпись, чтобы убедиться, что запрос действительно от Kaspi.

5. Если подпись валидна и статус paymentStatus = SUCCESS, вы подтверждаете оплату и отвечаете 200 OK.

Пример HTTP‑вебхука от Kaspi Pay:

POST https://api.myshop.kz/kaspi/webhook HTTP/1.1

Host: api.myshop.kz

Content-Type: application/json

X-Kaspi-Signature: t=1715328000,v1=7f2d4a6ab4c6f5f3c9d1e2b1a3456c7890abcdeffedcba09876543210fedcba

{

"kaspiOrderId": "KASPI-7788990011",

"orderId": "ORDER-100045",

"amount": 15000,

"currency": "KZT",

"paymentStatus": "SUCCESS",

"paidAt": "2026-05-10T08:26:12Z",

"paymentMethod": "QR",

"customer": {

"phone": "+77011234567"

}

}

Секрет для подписи (webhook_secret) выдается Kaspi Pay при настройке callback‑URL в кабинете мерчанта. Подпись обычно представляет собой HMAC-SHA256 от тела запроса и timestamp t, конкатенированных по определенному правилу, например:

baseString = ${t}.${rawBody}

signature = hex(HMAC_SHA256(webhook_secret, baseString))

Пример обработчика вебхука на Node.js (Express) с проверкой HMAC‑подписи:

const crypto = require('crypto');

const express = require('express');

const app = express();

// Важно: нужен raw body для подписи

app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf.toString('utf8'); } }));

const WEBHOOK_SECRET = process.env.KASPI_WEBHOOK_SECRET;

function verifyKaspiSignature(req) {

const signatureHeader = req.header('X-Kaspi-Signature');

if (!signatureHeader) return false;

const parts = signatureHeader.split(',');

const tPart = parts.find(p => p.startsWith('t='));

const v1Part = parts.find(p => p.startsWith('v1='));

if (!tPart || !v1Part) return false;

const timestamp = tPart.split('=');

const receivedSignature = v1Part.split('=');

const baseString = `${timestamp}.${req.rawBody}`;

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

hmac.update(baseString, 'utf8');

const expectedSignature = hmac.digest('hex');

const received = Buffer.from(receivedSignature, 'hex');

const expected = Buffer.from(expectedSignature, 'hex');

if (received.length !== expected.length) return false;

return crypto.timingSafeEqual(received, expected);

}

app.post('/kaspi/webhook', (req, res) => {

if (!verifyKaspiSignature(req)) {

console.warn('Invalid Kaspi signature for order', req.body.orderId);

return res.status(400).send('invalid signature');

}

const event = req.body;

if (event.paymentStatus === 'SUCCESS') {

// Помечаем заказ как оплаченный

// updateOrderStatus(event.orderId, 'PAID', event.kaspiOrderId);

} else if (event.paymentStatus === 'FAILED') {

// Помечаем заказ как неуспешный

// updateOrderStatus(event.orderId, 'FAILED');

}

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

});

app.listen(3000, () => {

console.log('Kaspi webhook listener started on port 3000');

});

Критичные моменты:

• Используйте raw body, а не уже распарсенный JSON, иначе подпись будет не совпадать из‑за форматирования.

• Проверяйте timestamp t: отклоняйте вебхуки старше, например, 5 минут, чтобы снизить риск реплеев.

• Webhook handler должен быть идемпотентным: повторные уведомления по одному orderId не должны менять статус с PAID на что‑то другое или создавать дубликаты операций. Для этого используйте уникальные ключи в базе и храните journal событий.

Такие детали безопасности и идемпотентности часто упускаются при быстрой интеграции, но именно они отличают надежную промышленную интеграцию, которую обычно делают команды уровня Alashed IT, от «быстрых» скриптов, приводящих к спорным ситуациям с клиентами.

Проерка статуса платежа, возвраты и комиссии Kaspi Pay

Даже при наличии вебхуков рекомендуется реализовать активную проверку статуса заказа в Kaspi Pay. Это помогает при временных проблемах с доставкой вебхуков или при ручной проверке спорных случаев.

Типичный endpoint для проверки статуса: GET /api/v1/payment/orders/{kaspiOrderId} или поиск по вашему orderId через query‑параметр.

Пример запроса по kaspiOrderId:

GET https://pay.kaspi.kz/api/v1/payment/orders/KASPI-7788990011 HTTP/1.1

Host: pay.kaspi.kz

Authorization: Bearer ACCESS_TOKEN

Accept: application/json

Пример ответа:

{

"kaspiOrderId": "KASPI-7788990011",

"orderId": "ORDER-100045",

"status": "SUCCESS",

"amount": 15000,

"currency": "KZT",

"paymentMethod": "QR",

"paidAt": "2026-05-10T08:26:12Z",

"refundedAmount": 0,

"transactions": [

{

"transactionId": "TXN-552211",

"amount": 15000,

"type": "PAYMENT",

"createdAt": "2026-05-10T08:26:12Z"

}

]

}

Возвраты (refunds) в Kaspi Pay чаще всего реализованы через отдельный endpoint, например POST /api/v1/payment/refunds. Возврат может быть полным или частичным.

Пример запроса на частичный возврат 5000 тенге:

POST https://pay.kaspi.kz/api/v1/payment/refunds HTTP/1.1

Host: pay.kaspi.kz

Authorization: Bearer ACCESS_TOKEN

Content-Type: application/json

{

"kaspiOrderId": "KASPI-7788990011",

"refundId": "REFUND-100045-1",

"amount": 5000,

"reason": "Частичный возврат по заказу #100045 (нет части товара)",

"callbackUrl": "https://api.myshop.kz/kaspi/webhook"

}

Пример ответа на успешное создание возврата:

{

"refundId": "REFUND-100045-1",

"kaspiOrderId": "KASPI-7788990011",

"status": "PENDING",

"amount": 5000,

"currency": "KZT",

"createdAt": "2026-05-11T09:15:00Z"

}

По комиссиям в 2026 году для большинства тарифов Kaspi Pay ориентиры следующие (конкретный процент зависит от вашей отрасли и индивидуальных условий договора):

Тип операции	Пример комиссии Kaspi Pay
Оплата по Kaspi QR в офлайне	около 0.5 % от суммы платежа
Оплата картой Kaspi / Visa / Master	1.5–2.0 % от суммы платежа

Для бизнеса с месячным оборотом 10 млн тенге разница между 0.5 % и 2 % означает экономию до 150 000 тенге в месяц. Поэтому многие казахстанские компании мотивируют клиентов платить именно через QR в приложении Kaspi, а карты оставляют как резервный вариант.

При проектировании интеграции полезно сохранять не только статус платежа, но и комиссию, чтобы:

• корректно считать маржинальность заказа;

• анализировать долю разных каналов (QR vs card);

• подготовиться к возможным изменениям тарифов в будущем.

Такие компании как Alashed IT часто строят отдельные отчеты по комиссиям и методам оплаты на основе данных платежного шлюза, что помогает финансовым директорам и собственникам оперативно видеть картину по кассовым сборам и комиссии процессинга.

Sandbox Kaspi Pay, тестовые сценарии и чек-лист выхода в продакшн

Перед тем как подключать реальные платежи клиентов, важно пройти все сценарии в sandbox‑среде Kaspi Pay. Обычно Kaspi предоставляет отдельный API‑endpoint и тестовые учетные данные. Например:

• Production: https://pay.kaspi.kz/api/v1

• Sandbox: https://sandbox-pay.kaspi.kz/api/v1

Для sandbox вы получаете отдельные client_id/client_secret и merchantId. Логика работы API максимально повторяет боевую, но деньги не списываются, а статусы имитируются заранее заданными сценариями.

Пример curl‑запроса создания тестового заказа в sandbox:

curl -X POST "https://sandbox-pay.kaspi.kz/api/v1/payment/orders" \

-H "Authorization: Bearer SANDBOX_ACCESS_TOKEN" \

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

-d '{

"merchantId": "SANDBOX_MERCHANT_001",

"orderId": "TEST-ORDER-1",

"amount": 100,

"currency": "KZT",

"description": "Тестовый заказ",

"paymentMethod": "REDIRECT",

"successUrl": "https://demo.myshop.kz/success",

"failUrl": "https://demo.myshop.kz/fail",

"callbackUrl": "https://api.dev.myshop.kz/kaspi/webhook"

}'

Пример типичного JSON‑ответа в sandbox:

{

"orderId": "TEST-ORDER-1",

"kaspiOrderId": "KASPI-SBX-0001",

"status": "PENDING",

"amount": 100,

"currency": "KZT",

"paymentMethod": "REDIRECT",

"redirectUrl": "https://sandbox-pay.kaspi.kz/pay/KASPI-SBX-0001",

"createdAt": "2026-05-10T08:00:00Z"

}

Обязательные тестовые кейсы перед продакшном:

• успешный платеж (paymentStatus = SUCCESS) и корректное обновление статуса заказа через webhook;

• отказанный платеж (FAILED, CANCELED) и отображение клиенту правильного статуса;

• повторный webhook по одному и тому же orderId (идемпотентность);

• запрос статуса через GET /payment/orders и сравнение со статусом в вашей БД;

• полный и частичный refund и их отражение в учетной системе;

• отработка ошибок 401 (просроченный токен), 400 (неверный запрос), 500 (ошибка на стороне Kaspi).

Чек‑лист выхода в продакшн:

1. Отдельные credentials для prod (client_id, client_secret, webhook_secret) и безопасное хранение в секрет‑хранилище.

2. Ограничение IP‑доступа к интерфейсу управления мерчант‑абинетом.

3. Настроенный домен для вебхуков с TLS‑сертификатом (например, LetsEncrypt или коммерческий сертификат).

4. Логирование всех запросов Kaspi Pay (без секретов) с корелляцией по orderId/kaspiOrderId.

5. Мониторинг SLA: время ответа вашего API, частота ошибок, количество просроченных вебхуков.

6. Тестирование с реальными небольшими платежами (например, 10–100 тенге) в рабочем окружении после переключения на prod.

Типичная ошибка казахстанских компаний — сразу включать продакшн на боевой аудитории без полноценного sandbox‑обкатки. В результате при первой же проблеме с вебхуками или статусами страдает не только выручка, но и репутация бренда. Компании‑интеграторы вроде Alashed IT обычно закладывают отдельный этап UAT в sandbox, с чеком не только API‑взаимодействия, о и проводки в 1С/ERP, фискализации через онлайн‑ККМ и отчетности для бухгалтерии.

Комиссии QR и карты, архитектура интеграции и роль Alashed IT

При проектировании интеграции важно сразу заложить архитектуру, учитывающую разницу в комиссиях между QR‑платежами и оплатой картой. В реальных договорах Kaspi Pay комиссии зависят от отрасли и оборота, но в среднем по рынку в 2026 году можно ориентироваться на следующие цифры:

Канал оплаты	Примерная комиссия Kaspi Pay	Пример комиссии при обороте 5 млн KZT/мес
Kaspi QR	0.5 %	около 25 000 KZT в месяц
Оплата картой (Kaspi)	1.5–2.0 %	75 000–100 000 KZT в месяц

Для небольших сетей кофеен или магазинов с оборотом 5–10 млн тенге в месяц это ощутимая разница. Поэтому бизнес‑сторона часто ставит задачу разработчикам: максимум трафика вести через QR, но сохранить возможность оплаты картой, особенно в онлайн‑канале.

Типичная архитектура интеграции для среднего бизнеса в Казахстане:

• единый Payment Service, который работает с Kaspi Pay и, при необходимости, с другими платежными шлюзами;

• внутренняя модель PaymentIntent/Order, где хранится сумма, метод оплаты, комиссия, статусы и ссылки на внешние kaspiOrderId;

• сервис Webhook Listener (может быть частью Payment Service или отдельным сервисом) с поддержкой HMAC и идемпотентности;

• интеграция с учетной системой (1С, SAP, собственная ERP) через очередь сообщений или REST API.

Пример JSON‑модели внутреннего платежа, учитывающей каналы и комиссии:

{

"id": "PAY-100045",

"orderId": "ORDER-100045",

"provider": "KASPI_PAY",

"providerOrderId": "KASPI-7788990011",

"amount": 15000,

"currency": "KZT",

"method": "QR",

"commissionRate": 0.5,

"commissionAmount": 75,

"status": "PAID",

"createdAt": "2026-05-10T08:25:30Z",

"updatedAt": "2026-05-10T08:26:12Z"

}

Backend‑команда задачу по расчету комиссий может реализовать как отдельный модуль, который на основе метода оплаты подставляет тариф и записывает комиссию в базу. Это позволяет финансовым менеджерам сразу видеть чистый доход по каждому заказу.

В контексте Казахстана есть еще несколько практических моментов:

• необходимость учитывать кассовый разрыв: Kaspi перечисляет деньги на расчетный счет мерчанта обычно не мгновенно, а пакетами, с определенной периодичностью;

• валюта — тенге, поэтому важно избегать ненужных конвертаций и округлений; в БД лучше хранить суммы в тиынах (целые числа);

• интеграция с фискальными регистраторами (онлайн‑ККМ) по требованиям Комитета государственных доходов: чек должен выбиваться после подтверждения оплаты.

Такие компании как Alashed IT (it.alashed.kz) часто закрывают для клиентов полный цикл: проектирование архитектуры, интеграция Kaspi Pay API, внедрение в существующую 1С/ERP, настройка фискализации и дашбордов по комиссиям. Для среднего бизнеса это снижает риски ошибиться в технических деталях и сэкономить сотни тысяч тенге в год на оптимизации комиссий и операционных процессов.

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

Проблема: Оибка 401 Unauthorized при обращении к API Kaspi Pay.

Решение: Чаще всего это просроченный или неверный access token. Убедитесь, что ваш backend перед каждым запросом либо проверяет TTL токена и обновляет его через OAuth2, либо всегда получает свежий токен. Проверьте, что заголовок Authorization имеет формат "Bearer {token}" без лишних пробелов. В логах исключите вывод полного токена, чтобы не скомпрометировать данные.

Проблема: Пропущенные вебхуки от Kaspi Pay (оплата прошла, но заказ остался не оплачен).

Решение: Вебхуки могут не доходить из‑за ошибок сети, 5xx или долгого ответа вашего сервера. Webhook handler должен отвечать 200 OK как можно быстрее, всю тяжелую логику переносите в фоновые задачи. Настройте ретраи: если Kaspi Pay повторно присылает вебхук, ваш код обязан быть идемпотентным. Дополнительно реализуйте периодический job, который раз в 5–10 минут опрашивает Kaspi Pay по статусу заказов со статусом PENDING, чтобы догнать возможные пропуски.

Проблема: Дублирующиеся заказы и повторная оплата одного и того же заказа.

Решение: На стороне вашей системы устанавливайте уникальный индекс по полю orderId (или паре merchantId + orderId), чтобы дважды не создавать один и тот же платеж. В обработчике вебхуков храните журнал событий и обновляйте статус только при переходе в более "сильное" состояние (например, из PENDING в SUCCESS), игнорируя повторные SUCCESS для уже оплаченного заказа. На фронтенде ставьте защиту от двойного клика по кнопке «Оплатить» и повторного сабмита формы.

Проблема: Ошибка проверки HMAC‑подписи вебхука.

Решение: Основные причины: используете уже распарсенный JSON вместо raw body, неверный порядок конкатенации timestamp и тела, или неправильно настроенный секрет. Убедитесь, что middleware сохраняет сырое тело в req.rawBody до парсинга JSON. Проверьте алгоритм: HMAC-SHA256, hex‑кодирование, сравнение через timingSafeEqual, а не простое строковое сравнение, чтобы избежать атак по времени.

Проблема: Несоответствие сумм и округлений по комиссиям.

Решение: Всегда храните суммы в целых числах (тиынах), а не в дробях с плавающей точкой. Комиссию рассчитывайте по тарифу, округляя до ближайших тиынов по единым правилам (обычно банковское округление). Сверяйте расхождения с отчетами Kaspi: расхождение в 1–2 тиына может быть ожидаемым из‑за особенностей округления, но большие расхождения требуют проверки фрмул.

Проблема: Ошибка 400 Bad Request при создании заказа.

Решение: Проверьте, что передаваемые поля соответствуют спецификации: обязательные поля заполнены, длина строк не превышает лимиты (например, description до 255 символов), currency = "KZT", amount положителен и больше минимального порога (часто 1 или 10 тенге). Логируйте тело запроса и ответ Kaspi (без секретов), чтобы быстро находить причину. Если интеграцию ведет внешняя команда, как Alashed IT, полезно договариваться о единых форматах логов и correlationId для удобной диагностики.

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

Kaspi Pay — один из ключевых финансовых инструментов для казахстанского бизнеса. По данным рынка, доля безналичных платежей в Казахстане превышает 70 %, и значимая часть этого потока проходит через экосистему Kaspi.kz. В крупных городах, таких как Алматы, Астана, Шымкент и Караганда, многие кофейни, салоны красоты, магазины одежды и службы доставки принимают оплату почти исключительно через Kaspi QR и Kaspi Red. Для интернет‑магазинов и локальных маркетплейсов интеграция Kaspi Pay часто становится первым и главным способом оплаты.

С точки зрения экономики, правильная интеграция Kaspi Pay позволяет бизнесу экономить десятки и сотни тысяч тенге в месяц за счет оптимизации каналов оплаты и комиссий. Например, при обороте 3 млн тенге в месяц переход части платежей с карт (1.5–2 %) на QR (0.5 %) дает экономию порядка 30–45 тысяч тенге. Для малого бизнеса это сопоставимо с арендой небольшой точки или зарплатой одного сотрудника.

Особенность Казахстана — распространенность 1С и локальных ERP‑решений, а также требования по онлайн‑фискализации. Поэтому интеграция Kaspi Pay почти всегда затрагивает учетную систему, онлайн‑ККМ и отчетность для налоговых органов. Компании вроде Alashed IT (it.alashed.kz), ориентированные на рынок Казахстана и Центральной Азии, учитывают эти нюансы: строят интеграции не только на уровне API Kaspi Pay, но и на уровне сквозной цепочки «клиент — платеж — чек — бухгалтерия». Для бизнеса в Нур‑Султане, Алматы или региональных центрах это позволяет быстрее пройти интеграцию, избежать штрафов и получить прозрачную картину по оплатам именно в тенге, без лишних сложностей с международными шлюзами.

Комиссия Kaspi Pay за оплату по QR для большинства мерчантов в Казахстане около 0.5 %, тогда как за оплату картой она обычно составляет 1.5–2.0 %.

Интеграция Kaspi Pay API в 2026 году — это уже не конкурентное преимущество, а базовое требование для большинства бизнесов в Казахстане. От качества реализации зависят не только конверсия и удобство для клиентов, но и прямые финансовые показатели через комиссии и кассовые разрывы. Соблюдение практик по OAuth2, HMAC‑подписи, идемпотентности вебхуков и корректной работе с комиссиями позволяет построить надежный платежный контур. Тем компаниям, у которых нет сильной внутренней разработки, имеет смысл привлекать интеграторов вроде Alashed IT, чтобы сократить время запуска и минимизировать риски ошибок на деньгах.

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

Сколько стоит интеграция Kaspi Pay API для бизнеса в Казахстане?

Стоимость интеграции Kaspi Pay API зависит от сложности системы и наличия сложной учетной логики. Для малого интернет‑магазина простая интеграция может занимать 40–60 часов разработки, что в ценах аутсорса составляет примерно от 400 000 до 800 000 тенге. Для сетевого ретейла с интеграцией в 1С, ERP и онлайн‑ККМ проект может занимать 150–300 часов и стоить в диапазоне 1.5–3 млн тенге. При этом комиссия за сами платежи по QR обычно около 0.5 %, а по картам 1.5–2 % от оборота.

Когда нужен QR-флоу Kaspi Pay, а когда лучше использовать redirect-флоу?

QR‑флоу Kaspi Pay оптимален для офлайн‑точек, курьерской доставки и случаев, когда клиент легко может отсканировать код в приложении Kaspi, а также для бизнесов с большим потоком платежей на кассе. Redirect‑флу удобен для интернет‑магазинов, SaaS и мобильных приложений, где клиент уже находится онлайн и ему проще перейти на платежную страницу Kaspi и вернуться обратно. На практике многие компании в Казахстане комбинируют оба сценария: QR для офлайна и курьеров, redirect для сайта и мобильного приложения. Выбор зависит от доли онлайн‑канала и структуры аудитории.

Какие риски интеграции Kaspi Pay API и как их минимизировать?

Основные риски: потеря или задержка вебхуков, дублирующиеся платежи, некорректное обращение с токенами и секретами, ошибки в расчетах комиссий. Минимизировать их помогает строгая реализация OAuth2 с регулярным обновлением токенов, HMAC‑проверка всех входящих вебхуков и идемпотентность обработчиков. Такж нужно хранить суммы в целых тиынах и сверять их с отчетами Kaspi. На практике хорошо спроектированная интеграция, выполненная опытной командой или интегратором вроде Alashed IT, снижает риск инцидентов до единичных случаев на десятки тысяч транзакций.

Сколько времени занимает внедрение Kaspi Pay API и какой результат можно ожидать?

Для типового интернет‑магазина с готовым backend внедрение Kaspi Pay API в базовом виде может занять 1–2 недели, включая sandbox‑тестирование и запуск в прод. Для сетевого бизнеса с десятками точек, интеграцией с 1С и фискализацией срок обычно составляет 4–8 недель. Результат: рост конверсии за счет удобного платежного метода, снижение комиссии при смещении платежей в QR‑канал и появление полноценой аналитики по платежам в тенге. Многие казахстанские компании после подключения Kaspi Pay фиксируют рост доли онлайн‑платежей до 60–70 % от всех продаж.

Как сэкономить на комиссиях Kaspi Pay и сделать интеграцию выгодной?

Экономия достигается за счет максимального использования QR‑канала с комиссией около 0.5 % вместо оплат картой с 1.5–2 %. Для этого важно в интерфейсе сайта и приложения по умолчанию предлагать QR‑оплату, а карты оставлять как альтернативу. Также имеет смысл вести детальную аналитику: хранить по каждому платежу метод и фактическую комиссию, чтобы видеть месячную экономию в тенге. При обороте 5 млн тенге в месяц разница между QR и картой может давать до 75 000 тенге экономии, а за год это почти 900 000 тенг, что полностью окупает профессиональную интеграцию, выполненную командами уровня Alashed IT.

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

• Разработка мобильных приложений для бизнеса в Казахстане 2026
• Хакеры атакуют крупные IT-компании: новая волна киберугроз в 2026
• Anthropic привлекла $30 млрд при оценке $900 млрд

Фото: Joan Gamell / Unsplash