Как подключить Kaspi Pay API к сайту — пошаговое руководство 2026

Если у вас есть сайт, интернет-магазин, бот или сервис в Казахстане, скорее всего вы уже думали про автоматизацию приёма платежей через Kaspi. Эта статья — практическое руководство: от регистрации до первого подтверждённого webhook'а.

Зачем нужен Kaspi Pay API

Kaspi Pay — основной способ безналичных расчётов в Казахстане: более 12 млн активных пользователей и десятки миллионов QR-платежей в день. Но в стандартном Kaspi Business счета приходится выставлять вручную: открыть приложение, ввести сумму, сгенерировать QR, отправить клиенту, дождаться оплаты, отметить в CRM.

API заменяет всю эту рутину на один POST-запрос. Преимущества для бизнеса:

Скорость. Платёж создаётся за 200 мс, без участия оператора.
Масштаб. Сотни параллельных платежей в час — без лишних сотрудников.
Точность. Сумма приходит из вашей CRM/корзины, человеческая ошибка исключена.
Аналитика. Все события — в единой ленте, экспорт в CSV, метрики конверсии.

Что нужно для подключения

Базовые требования простые:

Аккаунт Kaspi Business. Открывается бесплатно прямо в приложении Kaspi для ИП, ТОО или самозанятых.
Отдельный номер телефона для роли «Кассир». Это критично: подключать API на свой личный номер нельзя — иначе при логине Pay Bot вас выкинет из приложения Kaspi.
Сайт или бэкенд, который сможет принимать webhook-уведомления (или просто опрашивать статус по таймеру).

Программист не обязателен. Если вы пользователь — заполните заявку на /zayavka, менеджер настроит всё за вас. Если разработчик — поехали дальше.

Шаг 1. Регистрация и личный кабинет

Откройте paybot.kz и войдите через Google или Telegram. Email и пароль не нужны — это упрощает процесс и снимает один потенциальный вектор атаки.

После входа вы попадёте в кабинет. В разделе API-ключи будет два ключа:

kp_test_... — для Sandbox
kp_live_... — для прод (доступен после подключения Kaspi)

Тестовый ключ работает сразу — можно начинать кодить.

Шаг 2. Подключение Kaspi Business

В разделе Подключение Kaspi запускается SMS-онбординг:

Вводите номер кассира.
Получаете SMS с кодом от Kaspi.
Вводите код, и сессия Kaspi привязывается к вашему аккаунту Pay Bot.

Весь процесс — около минуты. Никаких эмуляторов, никаких прокси, никаких QR-кодов из стороннего софта. Сессия живёт долго, и Pay Bot сам её поддерживает (keepalive каждые 10 минут).

Шаг 3. Первый платёж через API

Создание QR-кода — один POST-запрос:

import requests
import uuid

response = requests.post(
    "https://api.paybot.kz/v1/qr/create",
    headers={
        "X-API-Key": "kp_live_your_key",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"amount": 5000},
    timeout=10,
)
response.raise_for_status()
data = response.json()

print("QR URL:", data["qr_url"])
print("Operation ID:", data["operation_id"])

Idempotency-Key — обязательное поле. Если запрос потерялся и вы его повторите с тем же ключом, второй платёж не создастся. Это критично при ненадёжной сети.

Ответ выглядит так:

{
  "operation_id": "op_8f3a2c...",
  "qr_url": "https://qr.kaspi.kz/...",
  "deep_link": "kaspi.kz://payment?...",
  "expires_at": "2026-04-01T14:35:00Z"
}

qr_url показываете клиенту как картинку, deep_link — для мобильной кнопки «Открыть Kaspi». Оба работают с одной и той же операцией.

Шаг 4. Получение статуса оплаты

Есть два способа узнать, заплатил ли клиент.

Способ 1: опрос статуса

Самый простой, подходит, если у вас нет публичного бэкенда:

status = requests.get(
    f"https://api.paybot.kz/v1/qr/status/{operation_id}",
    headers={"X-API-Key": "kp_live_your_key"},
).json()

# status["status"] = "pending" | "paid" | "expired" | "failed"

Рекомендуемая частота — раз в 3–5 секунд, не чаще. Все эндпоинты подчиняются rate-limit-ам.

Способ 2: webhook-уведомления

Способ для продакшна. Pay Bot сам пришлёт POST на ваш сервер, как только клиент оплатит:

{
  "event": "payment.completed",
  "operation_id": "op_8f3a2c...",
  "amount": 5000,
  "status": "paid",
  "paid_at": "2026-04-01T14:32:18Z"
}

Каждое сообщение подписано HMAC-SHA256 — проверяйте подпись, не доверяйте Content-Type. Подробно — в статье про webhook-интеграцию.

Шаг 5. Возвраты

Полный или частичный возврат — один вызов:

refund = requests.post(
    f"https://api.paybot.kz/me/payments/{operation_id}/refund",
    headers={"Authorization": f"Bearer {jwt_token}"},
    json={"amount": 5000, "reason": "Возврат товара"},
).json()

Деньги вернутся клиенту в Kaspi в течение нескольких минут. Возвраты доступны 90 дней с момента платежа (ограничение самого Kaspi).

Шаг 6. Идемпотентность и retry

Сеть рвётся, серверы падают — это норма. Pay Bot спроектирован так, чтобы повторные запросы были безопасны:

Все POST-ы принимают Idempotency-Key. Один и тот же ключ — один и тот же результат.
Webhook'и идут с retry-политикой (1 → 5 → 30 → 180 → 600 секунд).
Каждое событие имеет уникальный event_id. Храните его на своей стороне, чтобы не обработать дважды.

Тарифы

| План | Цена | Платежей/мес | Webhooks | Аккаунты Kaspi | |------|------|----------|----------|----------------| | Пробный | Бесплатно | 30 | 1 | 1 | | Starter | 10 000 ₸/мес | 200 | 1 | 1 | | Professional | 30 000 ₸/мес | 1 500 | 5 | 2 | | Enterprise | Индивидуально | ∞ | ∞ | По запросу |

Комиссии с самих платежей нет. Pay Bot зарабатывает только на подписке.

Частые проблемы

«Пишет, что мой Kaspi отвалился». Сессия Kaspi может разлогиниться — например, если кто-то открыл приложение на том же номере. Запустите health-check в разделе «Аккаунты Kaspi» или повторите SMS-онбординг.

«Webhook не приходит». Проверьте, что ваш эндпоинт отвечает 200 OK быстрее чем за 30 секунд. Pay Bot не ждёт долго. Если ответ медленнее — принимайте webhook в очередь и отвечайте 200 сразу.

«Платёж висит в pending». Это нормально, пока клиент не открыл Kaspi и не подтвердил. По истечении срока (по умолчанию 5 минут) платёж перейдёт в expired.

С чего начать прямо сейчас

Зарегистрироваться в кабинете — займёт 10 секунд.
Скопировать kp_test_... и сделать первый запрос в Sandbox.
Когда заработает — оставить заявку на подключение Kaspi или подключить самостоятельно через SMS-онбординг.

Если что-то непонятно — пишите в @paybotkz_bot, отвечаем быстро.