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

Платёжные ссылки

Создать оплату одним POST-запросом, поделиться URL — получить деньги

Платёжная ссылка — это URL вида https://pay.aibot.kz/checkout/{token}. Откройте на телефоне — увидите QR и кнопку «Открыть в Kaspi». Идеально для счетов, donate, e-commerce без интеграции.

Жизненный цикл

code
draft → active → paid     (успешная оплата)
              ↘ expired   (истёк expires_at)
              ↘ cancelled (отменён вручную)

active означает, что ссылку можно открыть и оплатить. Если установлен allow_repeat: true, ссылка возвращается в active после каждой оплаты — подходит для tip jar или подписки.

Создание ссылки

bash
Скачать
curl -X POST https://payapi.aibot.kz/v2/payment-links \
  -H "X-API-Key: kp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 12000,
    "description": "Курс «Базовый Python»",
    "success_url": "https://yoursite.com/thanks",
    "cancel_url": "https://yoursite.com/cart",
    "expires_in_minutes": 60,
    "metadata": {"order_id": "ord_1234"}
  }'
python
Скачать
import requests

resp = requests.post(
    "https://payapi.aibot.kz/v2/payment-links",
    headers={"X-API-Key": "kp_live_xxx"},
    json={
        "amount": 12000,
        "description": "Курс «Базовый Python»",
        "success_url": "https://yoursite.com/thanks",
        "cancel_url": "https://yoursite.com/cart",
        "expires_in_minutes": 60,
        "metadata": {"order_id": "ord_1234"},
    },
)
link = resp.json()
send_to_customer(link["url"])
javascript
Скачать
const res = await fetch("https://payapi.aibot.kz/v2/payment-links", {
  method: "POST",
  headers: {
    "X-API-Key": "kp_live_xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 12000,
    description: "Курс «Базовый Python»",
    success_url: "https://yoursite.com/thanks",
    cancel_url: "https://yoursite.com/cart",
    expires_in_minutes: 60,
    metadata: { order_id: "ord_1234" },
  }),
});
const link = await res.json();
php
Скачать
<?php
$ch = curl_init("https://payapi.aibot.kz/v2/payment-links");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: kp_live_xxx",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "amount" => 12000,
        "description" => "Курс «Базовый Python»",
        "success_url" => "https://yoursite.com/thanks",
        "cancel_url" => "https://yoursite.com/cart",
        "expires_in_minutes" => 60,
        "metadata" => ["order_id" => "ord_1234"],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$link = json_decode(curl_exec($ch), true);

Параметры запроса

ПолеТипОбязательноОписание
amountintдаСумма в тенге, минимум 100
descriptionstringдаВидимо клиенту на checkout
success_urlstringнетКуда вернуть после успешной оплаты
cancel_urlstringнетКуда вернуть при отмене или истечении
expires_in_minutesintнет, default 1440Сколько минут ссылка активна
allow_repeatboolнет, default falseМожно ли оплачивать несколько раз
email_requiredboolнет, default falseЗапросить email перед оплатой
metadataobjectнетЛюбой JSON ≤ 4KB, вернётся в webhook

Ответ

json
Скачать
{
  "id": 1024,
  "operation_id": 14837690870,
  "token": "pl_abc123def456",
  "url": "https://pay.aibot.kz/checkout/pl_abc123def456",
  "amount": 12000,
  "description": "Курс «Базовый Python»",
  "status": "active",
  "allow_repeat": false,
  "email_required": false,
  "expires_at": "2026-05-11T13:00:00Z",
  "qr_expires_at": "2026-05-11T12:05:00Z",
  "qr_image_url": "https://pay.aibot.kz/qr/pl_abc123def456.png",
  "kaspi_qr_image_url": "https://api.kaspi.kz/qrcode/...",
  "deep_link": "kaspi://qr?token=...",
  "metadata": {"order_id": "ord_1234"},
  "created_at": "2026-05-11T12:00:00Z"
}

url — отдавайте клиенту. qr_image_url — статичная картинка QR для печати. kaspi_qr_image_url — оригинальный QR от Kaspi, обновляется каждые ~5 минут.

Сценарии

E-commerce без интеграции

Сайт на Tilda или Notion, своя оплата невозможна. Создавайте ссылку на каждый заказ, кладите order_id в metadata, по webhook payment.completed ставьте заказ в работу.

Счёт в WhatsApp / Telegram

Менеджер выставил клиенту счёт, шлёт URL. Клиент открывает на телефоне, оплачивает в Kaspi. Webhook приходит за 3–5 секунд.

bash
Скачать
POST /v2/payment-links
{"amount": 75000, "description": "Услуги SEO, март 2026", "expires_in_minutes": 1440}

Donate / tip jar

Одна ссылка, по которой многие платят:

bash
Скачать
POST /v2/payment-links
{
  "amount": 1000,
  "description": "Поддержать проект",
  "allow_repeat": true,
  "expires_in_minutes": 525600
}

allow_repeat: true — после каждой оплаты ссылка снова становится active, QR обновляется. Каждый успешный платёж шлёт отдельный webhook.

Оплата с email-чеком

bash
Скачать
POST /v2/payment-links
{"amount": 12000, "description": "Подписка", "email_required": true}

Перед открытием Kaspi клиент введёт email — он придёт в webhook payload, можно отправить чек или активировать подписку.

Управление ссылками

bash
Скачать
# Получить ссылку
GET /v2/payment-links/{token}

# Список с пагинацией
GET /v2/payment-links?cursor=&limit=25&status=active

# Изменить описание / metadata
PATCH /v2/payment-links/{token}
{"description": "Новое описание"}

# Обновить устаревший Kaspi-QR
POST /v2/payment-links/{token}/refresh-qr

# Отменить
POST /v2/payment-links/{token}/cancel

Best practices

  • •Используйте metadata. Pay Bot не хранит сущности вашего бизнеса. order_id, user_id, invoice_id — кладите туда, и они вернутся в webhook.
  • •Короткий expires для разовых. Для разового счёта хватит 30–60 минут. Долгие ссылки требуют refresh-qr для актуализации Kaspi-QR.
  • •Idempotency для критичных интеграций. Если ваш сервер ретраит создание ссылки — добавьте Idempotency-Key: link_{order_id}, и при повторе получите оригинальный ответ. См. Идемпотентность.
  • •Не парсите url на стороне клиента. Структура pay.aibot.kz/checkout/{token} — стабильная, но любые query-параметры могут добавляться.

Что дальше