Авторизация и ключи

PayBot использует три механизма авторизации: API-ключ в заголовке X-API-Key для платёжного API (/v1/*, /v2/*), JWT в заголовке Authorization: Bearer для кабинетных вызовов (/me/*, /partner/*) и партнёрский ключ X-Partner-API-Key для B2B2C-интеграций (/partner/v1/*). Для приёма платежей вам нужен только API-ключ.

API-ключ (X-API-Key)

Это основной способ авторизации для приёма платежей. Ключ выдаётся в кабинете в разделе Настройки → API-ключи и имеет префикс, кодирующий режим:

Префикс	Режим	Назначение
`kp_live_`	боевой	реальные платежи, реальные деньги
`kp_test_`	тестовый	разработка и CI, деньги не двигаются

Передавайте ключ в каждом запросе к /v1/* и /v2/*:

bash

Скачать

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

Режим ключа определяет режим операции: тем же кодом, сменив только ключ, вы переключаетесь между тестом и боем.

Ротация API-ключа

Если ключ скомпрометирован или вы хотите периодически его менять, перевыпустите его:

bash

Скачать

curl -X POST https://api.paybot.kz/me/api-key/regenerate \
  -H "Authorization: Bearer &lt;jwt&gt;"

Старый ключ немедленно перестаёт работать, а в ответе приходит новый. Обновите его во всех интеграциях сразу после ротации, иначе запросы начнут получать 401.

Ключ kp_live_* даёт полный доступ к приёму платежей от вашего имени. Храните его как пароль: только на сервере, в переменных окружения или секрет-хранилище — никогда в клиентском коде, репозитории или мобильном приложении.

JWT (Authorization: Bearer)

JWT нужен для действий в кабинете от имени пользователя: управление вебхуками, брендинг, команда, тикеты, партнёрский кабинет. Токены выдаёт группа эндпоинтов /auth/*:

Метод	Путь	Назначение
POST	`/auth/register`	регистрация, возвращает пару токенов
POST	`/auth/login`	вход по email+пароль или через провайдера
POST	`/auth/refresh`	обновить пару токенов по `refresh_token`
POST	`/auth/magic-exchange`	обменять одноразовый magic-токен на сессию

Ответ (TokenResponse) содержит access_token, refresh_token, token_type: "Bearer" и expires_in (в секундах). Прикладывайте access-токен так:

bash

Скачать

curl https://api.paybot.kz/me/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Когда access_token истекает, получите новую пару через /auth/refresh, не заставляя пользователя логиниться заново:

python

Скачать

import requests

resp = requests.post(
    "https://api.paybot.kz/auth/refresh",
    json={"refresh_token": stored_refresh_token},
)
tokens = resp.json()
access_token = tokens["access_token"]

Партнёрский ключ (X-Partner-API-Key)

Если вы встраиваете приём платежей в свой SaaS и регистрируете собственных пользователей через PayBot, используется партнёрский ключ pk_live_ / pk_test_ в заголовке X-Partner-API-Key для вызовов /partner/v1/*. Полный сценарий — в разделе Партнёрский API (B2B2C).

Состояние 503 session_expired

Платёжный API опирается на живую сессию вашего Kaspi Business. Если сессия истекла, боевые запросы получают:

json

Скачать

{
  "type": "proxy_error",
  "category": "kaspi",
  "code": "session_expired",
  "message": "Kaspi session expired, reconnect required"
}

Обработайте этот код как сигнал «переподключите Kaspi»: покажите пользователю приглашение переподключиться в кабинете, не считайте это ошибкой платежа. В тестовом режиме session_expired не возникает. Полная модель ошибок — в разделе Коды ошибок.

Безопасность: рекомендации

•Держите kp_live_* и refresh_token только на сервере, в секрет-хранилище или переменных окружения.
•Никогда не логируйте ключи и токены в открытом виде.
•Разделяйте окружения: kp_test_* для стейджинга/CI, kp_live_* только в проде.
•При любом подозрении на утечку немедленно вызывайте POST /me/api-key/regenerate.
•Проверяйте подпись входящих вебхуков — она защищает от подделки уведомлений о платеже. См. Webhooks.

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

Чем API-ключ отличается от JWT?

API-ключ (X-API-Key) идентифицирует ваше приложение и применяется для приёма платежей — он долгоживущий и хранится на сервере. JWT (Authorization: Bearer) идентифицирует пользователя в кабинете, короткоживущий и обновляется через /auth/refresh. Для интеграции приёма платежей достаточно API-ключа.

Что произойдёт со старым ключом после ротации?

Он аннулируется мгновенно. Все запросы со старым ключом начнут получать 401 Unauthorized, поэтому обновляйте ключ во всех сервисах одновременно с ротацией.

Как отличить тестовый ключ от боевого?

По префиксу: kp_test_* — тестовый режим, kp_live_* — боевой. Режим ключа полностью определяет режим операции; см. Тестовый режим.

Можно ли иметь несколько API-ключей?

Основной клиентский ключ один и ротируется целиком. Для сценариев «много клиентов под одним провайдером» используется партнёрский API, где каждый ваш пользователь получает собственный ключ.