Тестовый режим (Sandbox)

Тестовый режим позволяет провести полный жизненный цикл платежа — создание, оплату, webhook, возврат — не списывая реальные деньги. Он включается автоматически, когда вы используете API-ключ с префиксом kp_test_. Никакого отдельного sandbox-домена нет: тот же https://api.paybot.kz, отличается только ключ.

Как включить тестовый режим

Возьмите тестовый ключ kp_test_ в кабинете (Настройки → API-ключи) и подставьте его в заголовок X-API-Key:

curl https://api.paybot.kz/v2/qr \
  -H "X-API-Key: kp_test_0123456789abcdef0123456789abcdef" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "description": "CI smoke test"}'

Операция создастся как настоящая, получит operation_id и статусы, но деньги не двигаются, и боевой Kaspi-аккаунт не затрагивается.

Чем тестовый режим отличается от боевого

Поскольку в тестовом режиме лимиты запросов не применяются и session_expired не возникает, он удобен для нагрузочных прогонов и автотестов.

Как отличить тестовый платёж от боевого

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

API_KEY = os.environ["PAYBOT_API_KEY"]
IS_TEST = API_KEY.startswith("kp_test_")

if IS_TEST:
    print("Работаем в песочнице — деньги не двигаются")

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

Интеграция в CI

Тестовый режим предназначен для автоматических прогонов. Типичный сценарий в пайплайне:

• •Создать тестовый платёж POST /v2/qr с kp_test_* и уникальным Idempotency-Key.
• •Проверить, что вернулся operation_id и status: "pending".
• •Опросить GET /v2/qr/{operation_id} или дождаться тестового вебхука.
• •Проверить, что ваш обработчик вебхука корректно валидирует подпись.

Пример smoke-теста на Python:

import os, uuid, requests

def test_create_qr():
    resp = requests.post(
        "https://api.paybot.kz/v2/qr",
        headers={
            "X-API-Key": os.environ["PAYBOT_TEST_KEY"],
            "Idempotency-Key": str(uuid.uuid4()),
        },
        json={"amount": 1000, "description": "ci"},
    )
    assert resp.status_code == 200
    body = resp.json()
    assert body["status"] == "pending"
    assert body["operation_id"]

Проверку обработки вебхуков в тестах удобно делать через POST /me/webhooks/{id}/test — он присылает подписанное тестовое событие на ваш URL. См. Webhooks.

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

Нужен ли отдельный sandbox-домен?

Нет. И тест, и бой работают на https://api.paybot.kz. Режим определяется исключительно префиксом ключа (kp_test_ или kp_live_).

Двигаются ли реальные деньги в тестовом режиме?

Нет. Тестовые платежи проходят полный жизненный цикл (создание, оплата, webhook, возврат), но не списывают средства и не затрагивают ваш боевой Kaspi-аккаунт.

Применяются ли лимиты запросов к тестовому ключу?

Нет, в тестовом режиме rate limit не применяется — это позволяет свободно гонять автотесты. В бою лимиты действуют; см. Лимиты запросов.

Как перейти в бой?

Замените ключ kp_test_* на kp_live_* и подключите боевой Kaspi-аккаунт в кабинете. Больше в коде менять ничего не нужно. См. Быстрый старт.