Hosted Checkout

Hosted Checkout — это публичная страница оплаты PayBot по адресу https://paybot.kz/checkout/{token}, которую вам не нужно программировать: создайте платёжную ссылку и отдайте покупателю её url. Страница сама показывает Kaspi QR и deep-link, сама опрашивает статус оплаты, сама редиректит покупателя обратно в ваш магазин и сама подставляет ваш логотип и цвет из брендинга.

Под капотом страница ходит в публичные эндпоинты /v2/checkout/*, которые не требуют авторизации (токен ссылки — сам по себе доступ). Если вам нужна не готовая страница, а собственный интерфейс оплаты, вы можете вызывать эти эндпоинты напрямую — ниже описан их флоу и лимиты.

Как устроен флоу оплаты

Оплата на hosted checkout проходит в четыре шага, и первые три PayBot делает за вас, если вы используете готовую страницу.

• •Покупатель открывает paybot.kz/checkout/{token} — страница читает данные ссылки через GET /v2/checkout/{token}.
• •Покупатель сканирует Kaspi QR или жмёт кнопку и уходит в приложение Kaspi по deep_link.
• •Страница опрашивает GET /v2/checkout/{token}/status?op={operation_id} раз в ~1–2 секунды, пока статус не станет финальным.
• •После оплаты бэкенд отдаёт готовый redirect_url, и страница возвращает покупателя на ваш success_url.

Параллельно вы получаете серверное подтверждение через вебхук payment.completed — на него и следует опираться для выдачи товара, а не на редирект браузера.

Как получить данные страницы оплаты

GET /v2/checkout/{token} возвращает всё, что нужно нарисовать: сумму, описание, текущий Kaspi QR, срок его жизни и блок брендинга мерчанта. Авторизация не нужна.

curl https://api.paybot.kz/v2/checkout/pl_abc123

Пример ответа:

{
  "token": "pl_abc123",
  "amount": 5000,
  "description": "Заказ #1234",
  "status": "active",
  "operation_id": "1450012345",
  "qr_token": "3010100100AC0000QRTOKEN...",
  "qr_image_url": "https://api.qrserver.com/v1/create-qr-code/?size=600x600&data=3010...",
  "deep_link": "https://qr.kaspi.kz/pay/abc123",
  "qr_expires_at": "2026-07-16T10:05:00Z",
  "expires_at": "2026-07-17T10:00:00Z",
  "allow_repeat": false,
  "email_required": false,
  "success_url": "https://shop.example/success",
  "cancel_url": "https://shop.example/cancel",
  "merchant": {
    "display_name": "Кофейня «Астана»",
    "logo_url": "https://cdn.example/logo.png",
    "brand_color": "#00A651",
    "support_email": "[email protected]"
  }
}

Поле operation_id — это идентификатор текущего цикла оплаты Kaspi; он понадобится для поллинга статуса. Блок merchant — это ваши настройки брендирования, которые применяются к странице целиком.

Как отследить оплату (поллинг статуса)

GET /v2/checkout/{token}/status?op={operation_id} возвращает текущий статус оплаты и, если оплата завершилась, готовый URL для редиректа.

curl "https://api.paybot.kz/v2/checkout/pl_abc123/status?op=1450012345"

{
  "status": "paid",
  "paid_at": "2026-07-16T10:03:12Z",
  "sender_name": "IVAN I.",
  "redirect_url": "https://shop.example/success"
}

Лимит на этот эндпоинт — 120 запросов в минуту на токен, поэтому опрашивайте не чаще, чем примерно раз в 500 мс. Поле redirect_url уже вычислено бэкендом: success_url для оплаченной ссылки, cancel_url для отменённой или истёкшей — фронтенду остаётся просто выполнить переход.

Как обновить истёкший QR

Kaspi QR живёт около 5 минут (qr_expires_at). Когда он истёк, а ссылка ещё активна, вызовите POST /v2/checkout/{token}/refresh-qr — вернётся тот же CheckoutPublic со свежим qr_token, qr_image_url и новым operation_id.

curl -X POST https://api.paybot.kz/v2/checkout/pl_abc123/refresh-qr

Лимит — 10 запросов в минуту, поэтому вызывайте обновление только по факту наступления qr_expires_at, а не в таймере. Если ссылка уже не активна, бэкенд молча ничего не делает (no-op), так что гонки на странице не ломают UI.

Как собрать email плательщика

Если платёжная ссылка создана с email_required: true, страница обязана спросить email покупателя до оплаты и отправить его через POST /v2/checkout/{token}/email.

curl -X POST https://api.paybot.kz/v2/checkout/pl_abc123/email \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Эндпоинт работает только при email_required: true и status == "active"; в остальных случаях вернётся 409 payment_link_not_active. Лимит — 20 запросов в минуту.

Какие бывают статусы checkout

Статус в GET /v2/checkout/{token} и в ответе поллинга принимает одни и те же значения.

Лимиты публичных эндпоинтов checkout

Данные страницы кешируются на бэке ~30 секунд (для allow_repeat-ссылок — 3 секунды, QR ротируется на посетителя), а статус — 3 секунды. Поэтому статус может «отставать» на пару секунд — это нормально, финальным источником истины остаётся вебхук.

Как выглядит брендирование на странице

Страница оплаты подставляет ваш логотип (logo_url), фирменный цвет (brand_color) и контакт поддержки (support_email) из блока merchant. Эти поля вы задаёте в разделе Брендирование через PATCH /me/branding, и они прилетают в CheckoutPublic.merchant без дополнительных вызовов — то есть весь checkout перекрашивается под ваш бренд.

FAQ

Нужно ли мне размещать страницу оплаты у себя?

Нет. Страница целиком хостится на стороне PayBot по адресу paybot.kz/checkout/{token}. Вы только создаёте платёжную ссылку и отдаёте покупателю её url. Если же вам нужен полный контроль над версткой, встройте кнопку через виджет или вызывайте публичные /v2/checkout/* из своего кода.

Как понять, что оплата прошла, надёжно?

Опирайтесь на серверный вебхук payment.completed, а не на редирект браузера: покупатель может закрыть вкладку до перехода на success_url. Редирект — это UX, вебхук — источник истины для выдачи товара.

Что будет, когда QR на странице протухнет?

Ничего страшного: при наступлении qr_expires_at вызовите POST /v2/checkout/{token}/refresh-qr (или это сделает готовая страница), и покупатель увидит новый Kaspi QR. Сама ссылка при этом остаётся активной до expires_at.