QR и счета через API | Pay.Aibot.kz

Прямые вызовы POST /v2/qr и POST /v2/invoices для POS и push-инвойсов

Платёжные ссылки покрывают большинство сценариев. Прямые QR и счета нужны, когда нужен мгновенный QR в собственной POS-системе или push-инвойс в приложение клиента по номеру телефона.

POST /v2/qr — одноразовый QR

Создаёт «голый» QR Kaspi — без hosted-страницы и токена ссылки. Подходит для:

•POS-терминала с собственным экраном
•Касса, выставка, кафе — кассир показывает экран с QR
•Интеграции, где Pay Bot не должен «знать» о клиенте

QR живёт 5 минут — за это время клиент должен отсканировать его в Kaspi.

bash

Скачать

curl -X POST https://payapi.aibot.kz/v2/qr \
  -H "X-API-Key: kp_live_xxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "description": "Капучино, 2 шт"
  }'

python

Скачать

import requests, uuid

resp = requests.post(
    "https://payapi.aibot.kz/v2/qr",
    headers={
        "X-API-Key": "kp_live_xxx",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"amount": 5000, "description": "Капучино, 2 шт"},
)
data = resp.json()
show_qr(data["qr_token"])
poll_status(data["operation_id"])

javascript

Скачать

import { randomUUID } from "crypto";

const res = await fetch("https://payapi.aibot.kz/v2/qr", {
  method: "POST",
  headers: {
    "X-API-Key": "kp_live_xxx",
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: 5000, description: "Капучино, 2 шт" }),
});
const data = await res.json();

php

Скачать

$ch = curl_init("https://payapi.aibot.kz/v2/qr");
curl_setopt_array($ch, [
    CURLOPT_POST =&gt; true,
    CURLOPT_HTTPHEADER =&gt; [
        "X-API-Key: kp_live_xxx",
        "Idempotency-Key: " . uniqid('', true),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS =&gt; json_encode([
        "amount" =&gt; 5000,
        "description" =&gt; "Капучино, 2 шт",
    ]),
    CURLOPT_RETURNTRANSFER =&gt; true,
]);
$data = json_decode(curl_exec($ch), true);

Ответ

json

Скачать

{
  "operation_id": 14837690870,
  "status": "QrTokenCreated",
  "qr_token": "https://qr.kaspi.kz/...",
  "qr_image_url": "https://payapi.aibot.kz/v2/qr/14837690870.png",
  "expire_date": "2026-05-11T12:05:00+05:00",
  "amount": 5000
}

Проверка статуса

bash

Скачать

curl https://payapi.aibot.kz/v2/qr/14837690870 \
  -H "X-API-Key: kp_live_xxx"

Статусы: QrTokenCreated, Processed, Cancelled, Expired. Используйте webhooks вместо polling в продакшене.

POST /v2/invoices — push-инвойс по телефону

Отправляет push-уведомление в Kaspi-приложение клиента — он видит счёт сразу, без сканирования QR. Подходит для:

•Удалённой оплаты услуг (мастер, врач, фрилансер)
•Подписок и регулярных платежей
•Интеграций, где номер клиента известен заранее

Счёт живёт до 24 часов и шлёт push до 3 раз.

bash

Скачать

curl -X POST https://payapi.aibot.kz/v2/invoices \
  -H "X-API-Key: kp_live_xxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "77001234567",
    "amount": 12000,
    "description": "Консультация 60 мин"
  }'

python

Скачать

import requests, uuid

resp = requests.post(
    "https://payapi.aibot.kz/v2/invoices",
    headers={
        "X-API-Key": "kp_live_xxx",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "phone": "77001234567",
        "amount": 12000,
        "description": "Консультация 60 мин",
    },
)

javascript

Скачать

await fetch("https://payapi.aibot.kz/v2/invoices", {
  method: "POST",
  headers: {
    "X-API-Key": "kp_live_xxx",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone: "77001234567",
    amount: 12000,
    description: "Консультация 60 мин",
  }),
});

php

Скачать

$ch = curl_init("https://payapi.aibot.kz/v2/invoices");
curl_setopt_array($ch, [
    CURLOPT_POST =&gt; true,
    CURLOPT_HTTPHEADER =&gt; [
        "X-API-Key: kp_live_xxx",
        "Idempotency-Key: " . uniqid('', true),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS =&gt; json_encode([
        "phone" =&gt; "77001234567",
        "amount" =&gt; 12000,
        "description" =&gt; "Консультация 60 мин",
    ]),
    CURLOPT_RETURNTRANSFER =&gt; true,
]);
$data = json_decode(curl_exec($ch), true);

Параметры

Поле	Тип	Обязательно	Описание
`phone`	string	да	Номер в формате `77XXXXXXXXX`, без `+`
`amount`	int	да	Сумма в тенге, минимум 100
`description`	string	да	Видно клиенту в push-уведомлении
`metadata`	object	нет	JSON ≤ 4KB, вернётся в webhook

Проверка клиента до отправки

Узнать, есть ли у номера активный Kaspi-аккаунт:

bash

Скачать

curl "https://payapi.aibot.kz/v2/client?phone=77001234567" \
  -H "X-API-Key: kp_live_xxx"

Возвращает {available: true, name: "Иван И."} или {available: false}. Используйте, чтобы не слать push на номер без Kaspi.

Отмена счёта

bash

Скачать

curl -X POST https://payapi.aibot.kz/v2/invoices/{operation_id}/cancel \
  -H "X-API-Key: kp_live_xxx"

Pay Bot отзывает push в Kaspi — клиент больше не сможет оплатить этот счёт.

QR или ссылка — что выбрать

Критерий	`/v2/qr`	Платёжная ссылка
Время жизни	5 мин	до 1 года
Hosted-страница	нет	да
Свой домен / брендинг	нет	да
Email-захват клиента	нет	да
Mobile deep link	вручную	автоматически
Сценарий	POS, кассовый монитор	счёт, e-commerce, donate

Если сомневаетесь — берите платёжные ссылки. POST /v2/qr нужен только для интеграций, где вы строите всю UX сами.

Что дальше

•Возвраты — отмена уже оплаченных операций
•Webhooks — payment.completed для QR и invoice
•Идемпотентность — почему Idempotency-Key обязателен