Быстрый старт

Чтобы принять первый платёж через PayBot, выполните пять шагов: зарегистрируйтесь, получите API-ключ, подключите свой Kaspi Business, создайте QR или счёт одним POST-запросом к https://api.paybot.kz/v2/qr и получите webhook payment.completed, когда клиент оплатит. Договор эквайринга не нужен — деньги идут напрямую на ваш счёт в Kaspi, PayBot выступает программным шлюзом к Kaspi Pay.

Шаг 1. Регистрация и API-ключ

Зарегистрируйтесь на paybot.kz через Google или Telegram. Сразу после входа в кабинете в разделе Настройки → API-ключи доступен ваш ключ. Ключ имеет вид kp_live_<32 hex-символа> для боевых операций и kp_test_<32 hex-символа> для тестовых.

Ключ передаётся в заголовке X-API-Key при каждом вызове платёжного API (/v1/* и /v2/*):

curl https://api.paybot.kz/v2/qr \
  -H "X-API-Key: kp_test_0123456789abcdef0123456789abcdef" \
  -H "Idempotency-Key: 8f14e45f-ceea-467a-9575-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{"amount": 2500, "description": "Тестовый заказ №1"}'

Подробнее о ключах, JWT и безопасности — в разделе Авторизация и ключи.

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

PayBot принимает оплату через ваш собственный кабинет Kaspi Business. В кабинете PayBot откройте Kaspi-аккаунты и пройдите подключение: укажите номер телефона, привязанный к Kaspi Business, и подтвердите вход. После успешного подключения статус аккаунта станет активным, и вы сможете создавать платежи.

Если у вас несколько кабинетов Kaspi, вы подключаете их все и выбираете нужный в каждом запросе заголовком X-Kaspi-Account: . Аккаунт по умолчанию используется, когда заголовок не передан.

Шаг 3. Первый платёж — QR или счёт

Есть два основных способа принять оплату напрямую через API:

• •QR-код — покупатель сканирует его в приложении Kaspi. Подходит для касс, POS, офлайн-точек.
• •Счёт (invoice) — push-уведомление на телефон покупателя в Kaspi по номеру. Подходит для онлайн-заказов и доставки.

Создание QR через POST /v2/qr:

curl https://api.paybot.kz/v2/qr \
  -H "X-API-Key: kp_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount": 25000, "description": "Заказ KP-4821"}'

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

{
  "operation_id": "op_5f8c2a1b9d",
  "status": "pending",
  "amount": 25000,
  "qr_url": "https://pay.kaspi.kz/pay/abc123",
  "qr_image": "data:image/png;base64,iVBORw0KGgo...",
  "expires_at": "2026-07-16T12:45:00Z"
}

Тот же вызов на Python:

import uuid
import requests

resp = requests.post(
    "https://api.paybot.kz/v2/qr",
    headers={
        "X-API-Key": "kp_live_...",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"amount": 25000, "description": "Заказ KP-4821"},
)
data = resp.json()
print(data["qr_url"], data["operation_id"])

Заголовок Idempotency-Key обязателен для создающих запросов — он защищает от двойного списания при повторной отправке. См. Идемпотентность. Полный обзор QR и счетов — в разделе QR и счета через API.

Шаг 4. Узнать, что платёж оплачен

Не опрашивайте статус в цикле без необходимости — правильный способ узнать об оплате мгновенно — webhook. Зарегистрируйте endpoint один раз:

curl https://api.paybot.kz/me/webhooks \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-site.kz/paybot/webhook", "events": ["payment.completed"]}'

Когда клиент оплатит, PayBot отправит на ваш URL подписанный POST:

{
  "event": "payment.completed",
  "operation_id": "op_5f8c2a1b9d",
  "amount": 25000,
  "status": "completed",
  "paid_at": "2026-07-16T12:37:11Z"
}

Каждая доставка подписана HMAC-SHA256 — обязательно проверяйте подпись из заголовка X-Webhook-Signature перед тем, как доверять данным. Полностью процесс описан в разделе Webhooks.

Если webhook по какой-то причине не дошёл, статус всегда можно запросить напрямую: GET /v2/qr/{operation_id}.

Шаг 5. Переход в боевой режим

Пока вы разрабатываете, используйте ключ kp_test_* — платежи не двигают реальные деньги, а лимиты запросов не применяются. Когда интеграция готова, замените ключ на kp_live_* и подключите боевой Kaspi-аккаунт. Логика запросов не меняется — меняется только ключ. Подробнее — Тестовый режим (Sandbox).

Частые вопросы

Нужен ли договор эквайринга?

Нет. PayBot работает поверх вашего собственного Kaspi Business, поэтому отдельный договор эквайринга с банком не требуется. Деньги приходят напрямую на ваш счёт в Kaspi, а PayBot даёт к нему программный доступ через API.

Как быстро приходит уведомление о платеже?

Webhook о завершённом платеже обычно доставляется за 3–5 секунд после оплаты. Если ваш endpoint временно недоступен, PayBot повторяет доставку с нарастающими интервалами. См. Webhooks.

Можно ли протестировать без реальных денег?

Да. Используйте ключ kp_test_* — все платежи в тестовом режиме проходят полный жизненный цикл, но не списывают средства. Это удобно для разработки и CI. См. Тестовый режим.

Сколько стоит подключение?

Пробный тариф включает 30 платежей без привязки карты. PayBot не берёт комиссию с суммы платежа — вы платите только за тариф сервиса. Актуальные условия — на странице тарифов paybot.kz.