ДокументацияВведение
Коды ошибок

Справочник

Changelog

История изменений API

История изменений публичного API PayBot в обратно-хронологическом порядке: последние записи сверху. Здесь фиксируются новые эндпоинты, изменения контракта, исправления и объявления об устаревании (deprecated). Записи касаются API https://api.paybot.kz; машиночитаемая спека всегда актуальна по адресу https://api.paybot.kz/openapi.json.

Если планируете уход со старого API — см. Переход с v1 на v2. Полный справочник актуальных путей — в API Reference.

2026-07-16

  • •Added: опубликована машиночитаемая спецификация https://api.paybot.kz/openapi.json и сгруппированный справочник API Reference.
  • •Changed: суммы во всех эндпоинтах документированы как целые в тенге (₸), без копеек.
  • •Docs: добавлены страницы SDK и библиотеки с примерами на Python, Node.js, PHP и Go.

2026-07-01

  • •Added: партнёрская интеграция /partner/v1/* (B2B2C) — white-label управление клиентами, их Kaspi-онбордингом, вебхуками и платежами по ключу X-Partner-API-Key.
  • •Added: POST /partner/v1/clients с upsert по external_id, POST /partner/v1/checkout для создания платёжных ссылок от имени клиента.
  • •Added: партнёрские вебхуки с событиями client.created, client.kaspi_connected, client.plan_changed, payment.*, partner.webhook.test.
  • •Added: партнёрская аналитика — GET /partner/analytics/summary, /funnel, /income-graph, /top-clients, /links-performance.
  • •Added: реферальные ссылки партнёра GET/POST/PATCH/DELETE /partner/links с UTM-метками и счётчиками кликов/регистраций.
  • •Changed: минимальная сумма вывода партнёра зафиксирована на 30 000 ₸; заявка на вывод стала двухшаговой (202 → подтверждение telegram_code → 200).

2026-06-15

  • •Added: экспорт платежей GET /me/payments/export — CSV с Content-Disposition: attachment, до 1000 строк.
  • •Added: сводная статистика кабинета GET /me/payments/stats — today / month / week[] / all_time с конверсией paid / (paid + failed).
  • •Added: создание платежей из кабинета по JWT — POST /me/payments/create-qr и POST /me/payments/create-invoice (без API-ключа).
  • •Changed: заголовки лимитов X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset вынесены в CORS-expose и доступны фронтенду.

2026-05-20

  • •Added: hosted checkout — публичные пути /v2/checkout/{token} (данные ссылки + брендинг мерчанта), /status, /refresh-qr, /email.
  • •Added: брендинг чекаута GET/PATCH /me/branding — display_name, logo_url, brand_color, support_email прокидываются в публичную страницу оплаты.
  • •Changed: поллинг статуса чекаута требует параметр op для ссылок с allow_repeat, чтобы разные посетители не видели чужой paid.
  • •Deprecated: загрузка файла логотипа POST /me/branding/logo отключена — эндпоинт всегда отвечает 501 logo_upload_disabled, используйте logo_url.

2026-04-08

  • •Added: платёжные ссылки /v2/payment-links — постоянный paybot.kz/checkout/{token} для печати, страница выдаёт свежий Kaspi QR при каждом визите.
  • •Added: metadata, success_url, cancel_url, allow_repeat, email_required в теле создания ссылки.
  • •Changed: списки платежей, ссылок и событий переведены на курсорную пагинацию — конверт {data[], next_cursor, has_more} вместо плоского массива. См. Пагинация.

2026-04-22

  • •Added: командный доступ /me/team — приглашения по email и роли owner | admin | accountant | support | viewer.
  • •Added: поддержка и уведомления в кабинете — /me/tickets, /me/notifications, WebSocket-каналы /ws/tickets/{id} и /ws/notifications.
  • •Added: интеграции /me/integrations — AmoCRM, Bitrix24, Tilda с включением/выключением и конфигом провайдера.
  • •Added: журнал запросов GET /me/logs для сверки ошибок по request_id.

2026-03-25

  • •Added: возвраты POST /v2/refunds с полем reason и результатом RefundResult{refund_id, status} (completed | pending | failed).
  • •Added: журнал событий аккаунта GET /v2/events — лента payment.*, payment_link.*, plan.changed, webhook.*.
  • •Added: проверка клиента Kaspi перед платежом GET /v2/client?phone= — возвращает доступные методы (qr, invoice).
  • •Fixed: статус QR GET /v2/qr/{op_id} синхронизируется с Kaspi при запросе и отдаёт raw_kaspi_status для диагностики.

2026-03-12

  • •Added: вебхуки с подписью HMAC-SHA256 над "{timestamp}.{body}" и заголовками доставки X-Webhook-ID, X-Webhook-Event, X-Webhook-Timestamp, X-Webhook-Signature.
  • •Added: управление вебхуками /me/webhooks — создание (секрет один раз), ротация секрета, тест, просмотр и ретрай доставок.
  • •Added: авто-отключение вебхука после исчерпания ретраев с экспоненциальным backoff; ручной повтор доставки и повторное включение.
  • •Added: журнал доставок GET /me/webhooks/{id}/deliveries с курсором и полями attempts, status, last_error.
  • •Added: User-Agent: PayBot-Webhooks/1.0 и Content-Type: application/json на всех доставках.
  • •Fixed: enable вебхука сбрасывает failing_since, снимая бейдж «доставки падают».

2026-02-02

  • •Added: обязательная идемпотентность на мутирующих POST /v2/* (/v2/qr, /v2/invoices, /v2/invoices/{op_id}/cancel, /v2/refunds) через заголовок Idempotency-Key.
  • •Changed: параллельный запрос с тем же ключом возвращает 409 idempotency_conflict; повтор на v1 отмечается заголовком X-Idempotent-Replay: true.
  • •Fixed: единый обработчик ошибок — любой сбой возвращается как {error: {type, code, message, request_id, param, category}}. См. Ошибки.

2026-01-15

  • •Added: стабильный релиз API v2 — /v2/qr, /v2/invoices, /v2/refunds, /v2/payments, /v2/events, /v2/client с чистыми JSON-ответами вместо legacy-обёртки {StatusCode, Data, Message}.
  • •Added: мультиаккаунт Kaspi через заголовок X-Kaspi-Account: ; управление аккаунтами /me/kaspi/accounts и онбординг /onboarding/kaspi/* с SMS-OTP.
  • •Added: платёжные ссылки /v2/payment-links в базовом виде и профиль клиента GET /me.
  • •Added: курсорная пагинация в списках платежей и заголовки лимитов X-RateLimit-*.
  • •Deprecated: API /v1/* помечен устаревшим — ответы несут заголовки Deprecation: true и Sunset: Wed, 31 Dec 2026 23:59:59 GMT. План перехода — Переход с v1 на v2.

FAQ

Где смотреть точную схему запросов и ответов на дату релиза?

Актуальная машиночитаемая спецификация всегда доступна по адресу https://api.paybot.kz/openapi.json. Этот changelog фиксирует, что и когда изменилось; точные поля и типы берите из OpenAPI и из API Reference.

Как понять, что мой код зовёт устаревший эндпоинт?

Ответы /v1/* несут заголовок Deprecation: true и Sunset с датой отключения. Проверяйте эти заголовки в логах интеграции — они точно указывают на код, который нужно перенести на v2 до 31 декабря 2026 года.

Назад

← Переход с v1 на v2