API Reference

Базовый URL

https://payapi.aibot.kz

Все запросы по HTTPS. Ответы в JSON. Кодировка UTF-8.

Аутентификация

Платежи — QR-оплата

POST /v1/qr/create

Создание QR-кода для оплаты. Клиент сканирует QR в приложении Kaspi.

• •Auth: X-API-Key
• •Headers: Idempotency-Key (обязательный, UUID — защита от дублей)
• •Таймаут QR: 180 секунд от Kaspi. Рекомендуем показывать клиенту 120 секунд.

{
  "amount": 5000
}

Ответ (200):

{
  "Data": {
    "QrOperationId": 14837690870,
    "Status": "QrTokenCreated",
    "QrToken": "https://qr.kaspi.kz/pay/abc123",
    "DeepLink": "kaspikz://pay?qr=abc123"
  },
  "StatusCode": 0
}

• •QrToken — URL для генерации QR-изображения
• •DeepLink — ссылка для мобильных устройств (открывает Kaspi напрямую)

GET /v1/qr/status/{operationId}

Проверка статуса QR-платежа. Рекомендуем поллинг каждые 3 секунды.

• •Auth: X-API-Key

Ответ (200):

{
  "Data": {
    "Status": "Paid",
    "Amount": 5000,
    "SenderName": "ИВАНОВ ИВАН",
    "TransactionId": "CT240402001234"
  },
  "StatusCode": 0
}

Возможные статусы:

Платежи — Выставление счёта

POST /v1/invoice/create

Выставление счёта на номер телефона. Клиент получает push-уведомление в Kaspi.

• •Auth: X-API-Key
• •Headers: Idempotency-Key (обязательный)
• •Срок действия: 24 часа. Если не оплатят — автоматическая отмена.

{
  "phone": "+77001234567",
  "amount": 3000,
  "comment": "Заказ #42"
}

Ответ (200):

{
  "Data": {
    "OperationId": 14837690871,
    "Status": "InvoiceCreated"
  },
  "StatusCode": 0
}

POST /v1/invoice/cancel

Отмена счёта до оплаты.

{
  "operation_id": "14837690871"
}

История и возвраты

POST /v1/history

История операций за период.

{
  "page_size": 20,
  "period": 0
}

period: 0 = сегодня, 1 = вчера, 7 = неделя, 30 = месяц.

POST /v1/refund

Возврат платежа. Требует Idempotency-Key.

{
  "operation_id": "14837690870",
  "items": [{"price": 5000}]
}

GET /v1/client/{phone}

Информация о клиенте Kaspi по номеру телефона.

GET /v1/client/+77001234567

GET /v1/status

Статус аккаунта: сессия Kaspi, использование, лимиты.

{
  "session_alive": true,
  "plan": "starter",
  "payments_used": 45,
  "payments_limit": 200
}

Аккаунт

GET /me

Профиль текущего клиента. Auth: Bearer JWT.

{
  "id": 1,
  "name": "Иван Иванов",
  "email": "[email protected]",
  "plan": "starter",
  "plan_active": true,
  "session_alive": true,
  "api_key_prefix": "kp_live_a1b2",
  "is_admin": false
}

POST /me/api-key/regenerate

Перегенерация API ключа. Старый ключ мгновенно перестаёт работать.

GET /me/usage

Статистика использования.

{
  "today": 12,
  "month": 156,
  "daily": [
    {"date": "2026-04-01", "count": 15},
    {"date": "2026-04-02", "count": 12}
  ]
}

GET /me/logs?limit=50

Логи API запросов.

Webhooks

POST /me/webhooks

{
  "url": "https://example.com/hook",
  "events": ["payment.completed"]
}

GET /me/webhooks

Список webhooks.

DELETE /me/webhooks/{id}

Удаление webhook.

Авторизация

POST /auth/register

{
  "name": "Иван",
  "email": "[email protected]",
  "provider": "google"
}

POST /auth/login

{
  "email": "[email protected]",
  "provider": "google"
}

Ответ: {"access_token": "eyJ...", "refresh_token": "...", "expires_in": 900}

POST /auth/refresh

{
  "refresh_token": "your_refresh_token"
}

Коды ответов

Rate Limits