PayApi.Aibot.kz — Kaspi Pay API

Быстрый старт

Базовый URL для всех запросов:

Base URL https://pay.aibot.kz

Все запросы и ответы используют формат application/json. Авторизация не требуется для базовых операций.

⚡

Попробуйте прямо сейчас: отправьте GET запрос на /api/health, чтобы убедиться, что API доступен.

cURL

curl https://pay.aibot.kz/api/health

cURL

curl -X POST https://pay.aibot.kz/api/qr/create \
  -H "Content-Type: application/json" \
  -d '{"amount": 1500}'

Эндпоинты

Health Check

Проверка состояния API сервера.

GET /api/health

Ответ

JSON

{
  "status": "ok",
  "ready": true
}

Создать QR для оплаты

Генерирует QR-код для приёма оплаты через Kaspi Pay.

POST /api/qr/create

Тело запроса (простой)

JSON

{
  "amount": 1500
}

Тело запроса (несколько позиций)

JSON

{
  "amount": 3300,
  "items": [
    { "name": "Кофе", "price": 1500, "count": 1 },
    { "name": "Вода", "price": 500, "count": 2 }
  ]
}

Ответ

JSON

{
  "Data": {
    "QrOperationId": 14826283600,
    "Status": "QrTokenCreated",
    "QrToken": "https://qr.kaspi.kz/...",
    "ExpireDate": "2026-04-01T17:01:26.000+05:00"
  },
  "StatusCode": 0,
  "Message": "OK"
}

Ключевые поля

QrToken — ссылка для генерации QR-кода, отправьте клиенту
QrOperationId — ID операции для проверки статуса
ExpireDate — время истечения QR-кода

Проверить статус оплаты

Получить текущий статус операции по её ID.

GET /api/qr/status/{operation_id}

Ответ

JSON

{
  "Data": {
    "Id": 14826283600,
    "Status": "QrTokenCreated"
  }
}

Статусы

Статус	Описание
`QrTokenCreated`	◯ Ожидает сканирования
`QrTokenScanned`	👁 Клиент отсканировал QR
`Confirmed`	✓ Оплачен
`CancelledByUser`	✗ Отменён клиентом
`Expired`	⌛ Время истекло

🔄

Рекомендуем опрашивать статус каждые 3 секунды до получения финального статуса (Confirmed, CancelledByUser или Expired).

Выставить счёт по номеру

Отправить счёт на оплату клиенту по номеру телефона.

POST /api/invoice/create

Тело запроса

JSON

{
  "phone": "87001234567",
  "amount": 5000,
  "comment": "Заказ #123"
}

Тело запроса (с позициями)

JSON

{
  "phone": "87001234567",
  "amount": 3300,
  "items": [
    { "name": "Кофе", "price": 1500, "count": 1 },
    { "name": "Вода", "price": 500, "count": 2 }
  ],
  "comment": "Заказ #123"
}

Ответ

JSON

{
  "Data": {
    "QrOperationId": 14826283709,
    "CartId": "..."
  },
  "StatusCode": 0
}

Отменить счёт

Отмена ранее выставленного счёта по ID операции.

POST /api/invoice/cancel

Тело запроса

JSON

{
  "operation_id": 14826283709
}

Ответ

JSON

{
  "StatusCode": 0,
  "Message": "OK"
}

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

Получить список всех операций.

GET /api/history

Возвращает массив операций с их статусами, суммами и датами.

История удалённых платежей

Получить список удалённых (remote) платежей.

GET /api/remote/history

Возвращает историю платежей, инициированных удалённо (по номеру телефона).

Возврат

Выполнить возврат средств по операции.

POST /api/refund

Тело запроса

JSON

{
  "operation_id": 14826283600,
  "items": [
    { "price": 1500 }
  ]
}

Sign Mode (Режим подписи)

Вместо проксирования запросов через наш сервер, вы можете получить подписанные headers и отправить запрос к Kaspi API напрямую со своего сервера.

POST /api/sign

Тело запроса (простой)

JSON

{
  "action": "qr/create",
  "amount": 1500
}

Тело запроса (с позициями)

JSON

{
  "action": "qr/create",
  "amount": 3300,
  "items": [
    { "name": "Кофе", "price": 1500, "count": 1 },
    { "name": "Вода", "price": 500, "count": 2 }
  ]
}

Доступные actions

Action	Описание
`qr/create`	Создать QR для оплаты
`invoice/create`	Выставить счёт по номеру телефона
`invoice/cancel`	Отменить счёт
`refund`	Возврат средств

Пример для invoice/create

JSON

{
  "action": "invoice/create",
  "phone": "87001234567",
  "amount": 5000,
  "comment": "Заказ #123"
}

Ответ

JSON

{
  "url": "https://qrpay.kaspi.kz/v01/qr-token/create-with-cart",
  "method": "POST",
  "body": "{...}",
  "headers": {
    "X-Kb-TokenSn": "...",
    "X-Kb-TokenSnMac": "...",
    "X-Device-ID": "...",
    "x-sign": "MEYCIQDclWYI...",
    "X-Time": "...",
    "X-SH": "..."
  },
  "response": "{...kaspi response...}"
}

⚡

Ответ содержит как подписанные headers, так и ответ от Kaspi (сервер также выполняет запрос). Вы можете использовать только response, или использовать headers для собственных запросов.

Пример (Python)

Python

import requests
import json

API = "https://pay.aibot.kz"

# Get signed headers + response
result = requests.post(f"{API}/api/sign", json={
    "action": "qr/create",
    "amount": 1500
}).json()

# Response already included
qr_link = json.loads(result["response"])["Data"]["QrToken"]
print(f"QR: {qr_link}")

# Or send yourself with signed headers:
# headers = result["headers"]
# requests.post(result["url"], data=result["body"], headers=headers)

Примеры кода

Полные рабочие примеры интеграции с Kaspi Pay API на разных языках.

Python

import requests
import time

API = "https://pay.aibot.kz"

# Создать QR
resp = requests.post(f"{API}/api/qr/create", json={"amount": 1500})
data = resp.json()
qr_link = data["Data"]["QrToken"]
op_id = data["Data"]["QrOperationId"]

print(f"QR: {qr_link}")

# Проверить оплату (polling)
while True:
    status = requests.get(f"{API}/api/qr/status/{op_id}").json()
    if status["Data"]["Status"] == "Confirmed":
        print("Оплачено!")
        break
    time.sleep(3)

JavaScript

const API = "https://pay.aibot.kz";

// Создать QR
const res = await fetch(`${API}/api/qr/create`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ amount: 1500 })
});
const data = await res.json();
console.log("QR:", data.Data.QrToken);

// Polling
const poll = setInterval(async () => {
  const s = await fetch(
    `${API}/api/qr/status/${data.Data.QrOperationId}`
  );
  const status = await s.json();
  if (status.Data.Status === "Confirmed") {
    console.log("Оплачено!");
    clearInterval(poll);
  }
}, 3000);

PHP

$api = "https://pay.aibot.kz";

$ch = curl_init("$api/api/qr/create");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    json_encode(["amount" => 1500]));
curl_setopt($ch, CURLOPT_HTTPHEADER,
    ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

echo $result["Data"]["QrToken"];

cURL

# Создать QR на 1500 тенге
curl -X POST https://pay.aibot.kz/api/qr/create \
  -H "Content-Type: application/json" \
  -d '{"amount": 1500}'

# Проверить статус
curl https://pay.aibot.kz/api/qr/status/14826283600

# Выставить счёт
curl -X POST https://pay.aibot.kz/api/invoice/create \
  -H "Content-Type: application/json" \
  -d '{"phone": "87001234567", "amount": 5000, "comment": "Заказ #123"}'

# Отменить счёт
curl -X POST https://pay.aibot.kz/api/invoice/cancel \
  -H "Content-Type: application/json" \
  -d '{"operation_id": 14826283709}'

# История
curl https://pay.aibot.kz/api/history

# Возврат
curl -X POST https://pay.aibot.kz/api/refund \
  -H "Content-Type: application/json" \
  -d '{"operation_id": 14826283600, "items": [{"price": 1500}]}'

Формат телефона

Для выставления счёта по номеру используйте казахстанский формат телефона:

Формат 87XXXXXXXXX

⚠

Номер должен содержать 11 цифр, начинаться с 87. Пример: 87001234567

Коды ошибок

Все ответы API содержат поле StatusCode. Значение 0 означает успех.

StatusCode	Значение	Описание
`0`	Успех	Запрос выполнен успешно
`-401`	Ошибка авторизации	Проверьте учётные данные или сессию
`-10001`	Временная ошибка	Повторите запрос через несколько секунд

🛈

При получении StatusCode: -10001 рекомендуется повторить запрос через 5-10 секунд. Если ошибка сохраняется, обратитесь в поддержку.