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

Hosted Checkout

Готовая страница оплаты Pay Bot — что увидит клиент по платёжной ссылке

Hosted Checkout — это страница pay.aibot.kz/checkout/{token}, которую открывает клиент. Адаптивна для десктопа и мобильного, поддерживает брендирование и POS-режим для планшета.

Как клиент видит оплату

На десктопе клиент видит:

  • •Логотип и название продавца (из брендирования)
  • •Сумму, описание и срок действия
  • •Динамический QR-код Kaspi (обновляется автоматически)
  • •Кнопку «Открыть в Kaspi» для мобильных
  • •Поле email, если включено email_required

На мобильном устройстве страница распознаёт iOS / Android и предлагает сразу открыть Kaspi-приложение через deep link. После оплаты — редирект на success_url, если задан.

URL и параметры

code
https://pay.aibot.kz/checkout/{token}

Где {token} — pl_abc123def456 из ответа POST /v2/payment-links.

QueryЗначение
?display=1Полноэкранный режим для POS-планшета. QR обновляется, лишние UI скрыты.
?lang=kkКазахский интерфейс (по умолчанию — русский).
?return_to=…Куда вернуться, если клиент нажмёт «назад».

POS-режим

code
https://pay.aibot.kz/checkout/{token}?display=1

Для оплаты на месте — кассир показывает планшет покупателю. Страница занимает весь экран, обновляет QR при истечении и пишет крупно «Оплачено» при подтверждении. Подходит для кафе, точек выдачи, выставок.

Mobile deep links

Pay Bot автоматически определяет устройство:

  • •iOS — кнопка kaspi://qr?token=…
  • •Android — кнопка intent с фоллбэком на Play Store
  • •Desktop — показывает QR во весь блок

Логика без дополнительной настройки — работает из коробки.

Public API для checkout-страницы

Если хотите построить свою страницу оплаты вместо нашей — используйте публичные эндпоинты. Авторизация не нужна, только token.

bash
Скачать
# Полные данные ссылки
curl https://payapi.aibot.kz/v2/checkout/pl_abc123def456

# Только статус для polling
curl https://payapi.aibot.kz/v2/checkout/pl_abc123def456/status

# Обновить устаревший Kaspi-QR
curl -X POST https://payapi.aibot.kz/v2/checkout/pl_abc123def456/refresh-qr

# Сохранить email клиента
curl -X POST https://payapi.aibot.kz/v2/checkout/pl_abc123def456/email \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Polling в JS

javascript
Скачать
async function pollStatus(token) {
  while (true) {
    const r = await fetch(`https://payapi.aibot.kz/v2/checkout/${token}/status`);
    const { status } = await r.json();
    if (status === "paid") return showSuccess();
    if (status === "expired") return showExpired();
    if (status === "cancelled") return showCancelled();
    await new Promise(r => setTimeout(r, 2000));
  }
}

Минимальный интервал — 2 секунды. Лимита запросов на публичные эндпоинты нет, но не злоупотребляйте.

Что происходит после оплаты

  • •Kaspi подтверждает платёж Pay Bot
  • •Pay Bot переводит ссылку в статус paid
  • •Шлёт webhook payment.completed на ваш сервер
  • •Hosted Checkout автоматически делает редирект на success_url

Если success_url не задан — страница показывает экран «Оплачено».

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

Кастомизация

  • •Цвет кнопки, логотип, имя — брендирование
  • •Свой домен (например, pay.yourbrand.kz) — Enterprise-тариф, обратитесь в поддержку
  • •Полностью своя страница — стройте на public API выше или через виджет

Что дальше