API Reference (v2)

Базовый URL API PayBot — https://api.paybot.kz. Все актуальные эндпоинты приёма платежей живут под префиксом /v2 и авторизуются заголовком X-API-Key; кабинетные вызовы под /me авторизуются Authorization: Bearer ; партнёрская интеграция — под /partner/v1 с заголовком X-Partner-API-Key. Полная машиночитаемая спецификация — https://api.paybot.kz/openapi.json. Эта страница — сгруппированный справочник реальных путей с методом, назначением, типом авторизации и обязательными заголовками.

Прежде чем звать эндпоинты, получите ключ и разберитесь с типами авторизации в разделе Авторизация. Формат ошибок, коды и request_id описаны в Ошибки. Модель доставки и подпись событий — в Вебхуки. Готовые сниппеты на четырёх языках — в SDK и библиотеки.

Как авторизовать запрос к API

PayBot использует три независимых механизма авторизации, каждый привязан к своей группе путей.

• •X-API-Key: kp_live_ (или kp_test_... в тестовом режиме) — для /v1/* и большинства /v2/*. Ключ выдаётся один раз в кабинете (POST /me/api-key/regenerate).
• •Authorization: Bearer (JWT) — для кабинетных путей /me/*, /partner/* (кабинет), /onboarding/*, /v1/subscription/*. Токен выдаёт /auth/login.
• •X-Partner-API-Key: pk_live_ — для white-label интеграции партнёра под /partner/v1/*.

Часть путей /v2/payment-links* и /v2/events принимают любой из двух вариантов — API-ключ или JWT. Публичные пути /v2/checkout/* авторизации не требуют вовсе.

Какие заголовки обязательны

Кроме заголовка авторизации, мутирующие вызовы требуют дополнительных заголовков.

• •Idempotency-Key — обязателен на POST /v2/qr, POST /v2/invoices, POST /v2/invoices/{op_id}/cancel, POST /v2/refunds и на всех мутирующих /v1/*. Без него вернётся 400 idempotency_key_required. Подробно — Идемпотентность.
• •X-Kaspi-Account: — выбор конкретного Kaspi-аккаунта при мультиаккаунте (/v2/qr, /v2/invoices, /me/payments/create-qr, /me/payments/create-invoice). Без заголовка берётся аккаунт по умолчанию.
• •Content-Type: application/json — на всех запросах с телом.

Заголовки лимитов присутствуют в каждом ответе и вынесены в CORS-expose: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Читайте их для backoff — см. Лимиты запросов.

Платежи v2

Ядро API: Kaspi QR, счета (invoice) с push на телефон, возвраты, список платежей и журнал событий. Авторизация — X-API-Key, если не указано иное.

POST /v2/qr принимает {amount, items?, comment?} и возвращает QrCreated{operation_id, qr_token, deep_link, expires_at, status}. QR живёт около 5 минут — отслеживайте expires_at. POST /v2/invoices принимает {phone, amount, comment?} и возвращает InvoiceCreated{operation_id, status, expires_at}; счёт живёт около 24 часов. POST /v2/refunds принимает {operation_id, amount, reason?} и возвращает RefundResult{refund_id, status} со статусом completed | pending | failed.

GET /v2/payments поддерживает query cursor, limit (1–100, def 20), status, type (qr | invoice) и отдаёт конверт {data[], next_cursor, has_more}. Как перебирать страницы — в Пагинация. Как создавать QR и счета детально — в QR и счета.

Платёжные ссылки v2

Платёжная ссылка (payment link) — это постоянный paybot.kz/checkout/{token}, который можно напечатать на наклейке: страница каждый раз выдаёт свежий Kaspi QR. Авторизация — X-API-Key или JWT.

Создание принимает {amount, description(1–500), success_url?, cancel_url?, expires_in_minutes(5–43200, def 1440), allow_repeat, email_required, metadata?}. Полная механика — в Платёжные ссылки. Публичная страница оплаты, которая отдаётся по ссылке, — в Hosted checkout.

Hosted checkout (публичные пути)

Публичная страница оплаты по токену ссылки. Авторизация не нужна — доступ по знанию token. У каждого пути свой rate-limit на токен+IP.

Параметр op в поллинге обязателен для ссылок с allow_repeat — иначе два посетителя увидят чужой paid. Подробно — в Hosted checkout.

Аккаунт `/me`

Кабинетные пути: профиль, оферта, ключ, использование, логи, организация. Все требуют JWT.

Полный ключ отдаётся только в ответе POST /me/api-key/regenerate и больше не читается нигде — см. Авторизация.

Платежи из кабинета (JWT)

Те же операции, что и через /v2, но авторизуются JWT — для кабинетного UI без API-ключа.

Вебхуки `/me/webhooks`

Управление подписками на события и просмотр доставок. Все пути требуют JWT. Секрет вебхука показывается в открытом виде один раз при создании и при ротации.

Допустимые события клиента: payment.completed, payment.cancelled, payment.expired, payment.refunded, webhook.test. Подпись — HMAC-SHA256 над "{timestamp}.{body}". Полная механика доставки, заголовки и проверка подписи — в Вебхуки.

Kaspi-аккаунты и онбординг

Подключение и управление Kaspi-аккаунтами мерчанта. Все пути требуют JWT.

При мультиаккаунте передавайте X-Kaspi-Account: в вызовах создания платежа. Поле session_alive в карточке аккаунта — сигнал «переподключите Kaspi».

Брендинг чекаута

Кастомизация публичной страницы оплаты. JWT.

Загрузка файла логотипа отключена (501) — используйте logo_url. Настройка бренда — в Брендинг. Валидация: brand_color строго ^#[0-9A-Fa-f]{6}$, support_email должен содержать @.

Партнёрский кабинет `/partner`

B2B2C-кабинет партнёра: баланс, комиссии, клиенты, ссылки, выводы, аналитика. Авторизация — JWT с активным партнёрским профилем.

Минимальная сумма вывода — 30 000 ₸. Полный сценарий подключения партнёра — в Партнёрский API.

Партнёрская интеграция `/partner/v1`

White-label REST-API для партнёров: управление клиентами, их Kaspi-онбордингом, вебхуками и платежами. Авторизация — X-Partner-API-Key.

Партнёрские ключи выдаются в кабинете: POST /partner/integration/api-keys (ключ показывается один раз). Детали — в Партнёрский API.

Прочие кабинетные группы

Кабинет PayBot покрывает больше, чем платежи. Все пути ниже требуют JWT.

Роли команды: owner | admin | accountant | support | viewer. Тарифы подписки зашиты в коде: starter=10000 ₸, professional=30000 ₸ в месяц; лимиты платежей в месяц — trial=30, starter=200, professional=1500, enterprise=999999.

Журнал событий

GET /v2/events (авторизация X-API-Key или JWT) отдаёт ленту активности аккаунта в конверте {data:[{id, type, data, created_at}], next_cursor, has_more}. Реально пишутся события payment.completed, payment.cancelled, payment.expired, payment_link.created, payment_link.updated, payment_link.cancelled, plan.changed, webhook.delivery_failed, webhook.auto_reactivated. Поле data — свободный объект, структура зависит от type. Полный список типов событий — в События.

Пример: создать QR и проверить статус

Минимальный сквозной вызов через X-API-Key с обязательным Idempotency-Key.

curl -X POST https://api.paybot.kz/v2/qr \
  -H "X-API-Key: kp_live_0123456789abcdef0123456789abcdef" \
  -H "Idempotency-Key: 6f9619ff-8b86-d011-b42d-00cf4fc964ff" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "comment": "Заказ #1042"}'

Ответ QrCreated:

{
  "operation_id": "op_3fa85f6457174562",
  "qr_token": "kzqr_9d8f7a6b5c4d",
  "deep_link": "https://kaspi.kz/pay/9d8f7a6b5c4d",
  "expires_at": "2026-07-16T12:05:00Z",
  "status": "created"
}

Затем опрашивайте статус, пока не придёт paid (или включите Вебхуки вместо поллинга):

curl https://api.paybot.kz/v2/qr/op_3fa85f6457174562 \
  -H "X-API-Key: kp_live_0123456789abcdef0123456789abcdef"

{
  "operation_id": "op_3fa85f6457174562",
  "status": "paid",
  "amount": 5000,
  "sender_name": "Айгерим Т.",
  "transaction_id": "tx_88213004",
  "paid_at": "2026-07-16T12:02:41Z",
  "raw_kaspi_status": "Processed"
}

Что со старым API v1

Версия /v1/* объявлена deprecated и отключается 31 декабря 2026 года. Каждый ответ v1 несёт заголовки Deprecation: true, Sunset: Wed, 31 Dec 2026 23:59:59 GMT и Link: ; rel="successor-version". Новые интеграции должны использовать только /v2. Таблицу соответствий путей и пошаговый перенос смотрите в Переход с v1 на v2.

Единственный путь без прямого аналога в v2 — GET /v1/status (живость сессии и счётчики использования); в кабинете те же данные доступны через GET /me и GET /me/usage.

FAQ

Где взять полный список запросов и ответов?

Машиночитаемая OpenAPI-спека с точными телами и схемами — https://api.paybot.kz/openapi.json. Эта страница — сгруппированный человекочитаемый срез тех же путей. Схемы полей (QrCreated, PaymentLinkResponse и т.п.) там же.

Чем `/v2/qr` отличается от `/me/payments/create-qr`?

Это одна и та же операция с разной авторизацией. /v2/qr авторизуется API-ключом (X-API-Key) и предназначен для серверной интеграции. /me/payments/create-qr авторизуется JWT и вызывается из кабинета/фронтенда, где нет API-ключа. Обязательный Idempotency-Key нужен обоим.

Почему список платежей отстаёт после создания?

Ответы /v2/payments и /v2/payment-links кэшируются на бэке 5 секунд. Сразу после создания платёж может не появиться в списке до истечения кэша — это ожидаемо. Для мгновенного статуса опрашивайте конкретную операцию через GET /v2/qr/{op_id}.

Какой лимит запросов у API?

По умолчанию 20 запросов в минуту на ключ. Лимит не действует для тарифа enterprise и для ключей в тестовом режиме (kp_test_...). Читайте заголовки X-RateLimit-* и делайте backoff — см. Лимиты запросов.