Документация

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

Полная эмуляция Kaspi Pay без денег для разработки и CI

Sandbox — это полноценная копия live-API, которая возвращает реалистичные ответы и шлёт webhooks, но не вызывает Kaspi. Идеально для разработки, e2e-тестов и CI/CD.

Как включить

Используйте API-ключ с префиксом kp_test_. Все эндпоинты автоматически переключаются в режим эмуляции — реальных списаний не происходит.

bash
Скачать
curl -X POST https://payapi.aibot.kz/v2/qr \
  -H "X-API-Key: kp_test_xxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"amount": 1000}'

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

Что доступно

  • •POST /v2/qr — создаёт sandbox-QR с реальной структурой ответа
  • •POST /v2/invoices — создаёт тестовый счёт
  • •POST /v2/payment-links — полностью рабочая платёжная ссылка
  • •POST /v2/refunds — эмулирует возврат
  • •GET /v2/payments, GET /v2/events — отдают только sandbox-операции
  • •Webhooks доставляются с подписью HMAC-SHA256 как в live

Чем sandbox отличается от live

  • •Тестовые ключи не имеют rate-limits — удобно для нагрузочных тестов
  • •QR не открывается в реальном Kaspi — приложение покажет «токен недействителен»
  • •Платежи не попадают в счётчик тарифа
  • •Все объекты помечены mode: "test" в payload
  • •Истории платежей kp_live_ и kp_test_ хранятся раздельно

Принудительное завершение платежа

Чтобы протестировать payment.completed webhook без реального сканирования QR, отметьте операцию как оплаченную через служебный endpoint:

bash
Скачать
curl -X POST https://payapi.aibot.kz/v1/test/mark-paid/{operation_id} \
  -H "X-API-Key: kp_test_xxx"

Pay Bot обновит статус на Processed и пошлёт ваш webhook через несколько секунд.

Сценарии для CI/CD

Smoke-тест после деплоя

python
Скачать
import requests, uuid, time

API = "https://payapi.aibot.kz"
KEY = "kp_test_xxx"

def test_full_payment_flow():
    # 1. Создать ссылку
    r = requests.post(f"{API}/v2/payment-links",
        headers={"X-API-Key": KEY},
        json={"amount": 100, "description": "smoke"})
    assert r.status_code == 201
    token = r.json()["token"]

    # 2. Принудительно отметить оплаченной
    op_id = r.json()["operation_id"]
    requests.post(f"{API}/v1/test/mark-paid/{op_id}",
        headers={"X-API-Key": KEY})

    # 3. Проверить статус
    time.sleep(2)
    s = requests.get(f"{API}/v2/payment-links/{token}",
        headers={"X-API-Key": KEY})
    assert s.json()["status"] == "paid"

GitHub Actions

bash
Скачать
- name: Pay Bot integration test
  env:
    PAYBOT_KEY: ${{ secrets.PAYBOT_TEST_KEY }}
  run: |
    python -m pytest tests/integration/test_paybot.py

Так как тестовые ключи не имеют rate-limits, тесты можно запускать на каждый push.

Чеклист перед переходом в live

  • •HTTPS endpoint для webhooks доступен снаружи
  • •Проверка подписи HMAC-SHA256 включена и протестирована
  • •Обработка статусов: Processed, Cancelled, Expired
  • •Idempotency-Key передаётся на всех POST в /v2/qr, /v2/invoices, /v2/refunds
  • •Retry при 429 и 5xx (exponential backoff)
  • •Логирование request_id из ответов для debug
  • •Метаданные (order_id, user_id) сохраняются и матчатся в webhook

Demo-страница

Открытая демо-страница pay.aibot.kz/demo показывает, как выглядит платёжная ссылка глазами клиента. Используется тестовый аккаунт.

Что дальше