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

Авторизация в PayBot API — ключи kp_live и kp_test, JWT для дашборда, ротация ключей и правила безопасности при работе с Kaspi Pay.

У PayBot два способа аутентификации: API-ключи для серверных интеграций и JWT для веб-приложений на стороне пользователя.

API-ключи

API-ключи — основной способ авторизации для серверных интеграций. Передаются в заголовке X-API-Key.

Префикс	Режим	Поведение
`kp_live_`	Live	Реальные платежи через Kaspi. Считаются по тарифу.
`kp_test_`	Sandbox	Тестовые платежи, нет rate-limits, без денег.

Где взять

В дашборде paybot.kz/dashboard/api-keys. Live-ключ показывается один раз при генерации — сохраните его в секреты вашего приложения. Тестовый ключ можно посмотреть в любой момент.

Как использовать

bash

Скачать

curl https://api.paybot.kz/v2/payments \
  -H "X-API-Key: kp_live_xxx"

python

Скачать

import requests
requests.get(
    "https://api.paybot.kz/v2/payments",
    headers={"X-API-Key": "kp_live_xxx"},
)

javascript

Скачать

await fetch("https://api.paybot.kz/v2/payments", {
  headers: { "X-API-Key": "kp_live_xxx" },
});

php

Скачать

$ch = curl_init("https://api.paybot.kz/v2/payments");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER =&gt; ["X-API-Key: kp_live_xxx"],
    CURLOPT_RETURNTRANSFER =&gt; true,
]);
$data = json_decode(curl_exec($ch), true);

Ротация ключей

Если ключ утёк или сотрудник уволился, нажмите Регенерировать в дашборде. Старый ключ перестаёт работать немедленно. Live-ключ выдаётся ровно один на аккаунт — генерация нового удаляет старый.

Безопасность

•Никогда не коммитьте ключ в git и не публикуйте на фронтенде
•Используйте секреты CI (GitHub Actions, GitLab CI), Vault, Kubernetes Secrets
•Live-ключ хранится в БД только в виде SHA-256 хеша, plaintext недоступен после генерации
•Для серверов с фиксированным IP можно ограничить ключ по IP — обратитесь в поддержку
•При утечке немедленно ротируйте — все pending-платежи продолжат работать через новый ключ

JWT для дашборда

JWT-токены используются веб-приложением на paybot.kz. Алгоритм — RS256, ключи ротируются автоматически.

JWT-токены принимают эндпоинты /me/* и часть /v2/payment-links/*.

bash

Скачать

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

JWT выдаётся при логине через Google или Telegram, его обновлением занимается NextAuth. Прямые интеграции через JWT не рекомендуются — для сервер-сервер связки используйте API-ключи.

Когда что использовать

Сценарий	Авторизация
Серверная интеграция (бэкенд → PayBot)	`X-API-Key: kp_live_…`
CI/CD, e2e-тесты, dev-окружение	`X-API-Key: kp_test_…`
Дашборд / личный кабинет	`Authorization: Bearer`
Управление webhooks из своей админки	`Authorization: Bearer`
Public checkout / widget	Без авторизации (по токену ссылки)

Ошибки авторизации

Код	Когда
`401 invalid_api_key`	Ключ не существует или отозван
`401 missing_api_key`	Не передан заголовок `X-API-Key`
`401 invalid_token`	JWT просрочен или подписан другим ключом
`403 inactive_account`	Аккаунт заблокирован администратором
`403 plan_limit_exceeded`	Исчерпан лимит платежей по тарифу

Подробнее: Коды ошибок.

Что дальше

•Тестовый режим — sandbox без реальных платежей
•Rate Limits — лимиты и заголовки
•API Reference — полный список эндпоинтов