Партнёрский API (B2B2C)

Регистрация ваших пользователей, hosted checkout, webhook от партнёра

Партнёрский API (/partner/v1/*) позволяет встроить приём платежей PayBot в ваш собственный продукт: вы регистрируете своих пользователей как клиентов PayBot, white-label подключаете их Kaspi, создаёте за них hosted checkout и получаете вебхуки об их оплатах. Все запросы авторизуются заголовком X-Partner-API-Key: pk_(live|test)_ — одним ключом на всё портфолио ваших клиентов.

Это B2B2C-модель: ваш аккаунт партнёра — «зонтик», под которым живут аккаунты ваших пользователей. Клиент видит платежи как свои, а вы управляете его онбордингом и ключами через партнёрский API, не заставляя пользователя разбираться в PayBot напрямую.

Партнёрский API-ключ выдаётся в кабинете партнёра через POST /partner/integration/api-keys (авторизация — JWT партнёра) и показывается один раз — сохраните его сразу.

Как проверить ключ

Начните с GET /partner/v1/ping — простой health-check ключа.

bash

Скачать

curl https://api.paybot.kz/partner/v1/ping \
  -H "X-Partner-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Успешный ответ подтверждает, что ключ активен. Используйте pk_test_... для отладки — тестовый режим не тратит боевые лимиты.

Как зарегистрировать своего клиента

POST /partner/v1/clients создаёт клиента PayBot или возвращает существующего — это upsert по вашему external_id. Передавайте свой идентификатор пользователя в external_id, чтобы связать его аккаунт в вашей системе с аккаунтом PayBot.

bash

Скачать

curl -X POST https://api.paybot.kz/partner/v1/clients \
  -H "X-Partner-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Кофейня «Астана»",
    "email": "[email protected]",
    "external_id": "user_88421",
    "plan": "trial"
  }'

Тело: name (2–255), email (обязателен), phone, external_id (ваш ID для upsert), plan (по умолчанию trial), send_invite_email (по умолчанию false), metadata.

json

Скачать

{
  "created": true,
  "client": {
    "id": 5012,
    "public_id": "cl_a1b2c3d4",
    "name": "Кофейня «Астана»",
    "email": "[email protected]",
    "partner_external_id": "user_88421",
    "plan": "trial",
    "plan_active": true,
    "plan_expires_at": "2026-08-15T00:00:00Z",
    "kaspi_connected": false,
    "is_active": true,
    "created_at": "2026-07-16T09:00:00Z"
  },
  "login_url": "https://paybot.kz/login/magic?token=...",
  "onboarding_url": "https://paybot.kz/onboarding/kaspi?token=..."
}

Поле created показывает, создан ли новый клиент (true) или возвращён существующий (false). onboarding_url ведёт клиента на подключение Kaspi, а login_url — одноразовый вход в его кабинет.

Список ваших клиентов — GET /partner/v1/clients с курсорной пагинацией (параметры cursor, limit, external_id, plan). Один клиент — GET /partner/v1/clients/{client_ref}, где client_ref — это либо PayBot ID, либо ваш external_id.

Как выдать клиенту API-ключ

У каждого клиента есть свой API-ключ для вызовов /v2/*. Префикс активного ключа — GET /partner/v1/clients/{ref}/api-key, а новый ключ — POST /partner/v1/clients/{ref}/api-key/rotate.

bash

Скачать

curl -X POST https://api.paybot.kz/partner/v1/clients/user_88421/api-key/rotate \
  -H "X-Partner-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

json

Скачать

{
  "prefix": "kp_live_a1b2c3",
  "mode": "live",
  "api_key": "kp_live_a1b2c3d4e5f60718293a4b5c6d7e8f90"
}

Полный api_key возвращается только при ротации и только один раз — при обычном GET поле api_key будет null, доступен лишь prefix. Передайте этот ключ клиенту (или используйте на его стороне для вызовов QR и счетов).

Как white-label подключить Kaspi клиента

Онбординг Kaspi проходит через SMS-OTP, но под вашим брендом — пользователь не уходит на paybot.kz. Флоу: start → verify, статус — status, переотправка кода — resend.

bash

Скачать

# 1. Отправить SMS-OTP на номер клиента
curl -X POST https://api.paybot.kz/partner/v1/clients/user_88421/kaspi/start \
  -H "X-Partner-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"phone": "7017770001"}'

# 2. Проверить код из SMS
curl -X POST https://api.paybot.kz/partner/v1/clients/user_88421/kaspi/verify \
  -H "X-Partner-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"code": "1234"}'

json

Скачать

{
  "state": "otp_sent",
  "phone": "7017770001",
  "connected": false,
  "org_name": null,
  "org_bin": null
}

После verify при успехе connected станет true. Проверить состояние в любой момент — GET /partner/v1/clients/{ref}/kaspi/status. Kaspi-аккаунты клиента — GET /partner/v1/clients/{ref}/kaspi/accounts, назначить основной — POST /partner/v1/clients/{ref}/kaspi/accounts/{id}/set-default.

Как создать hosted checkout за клиента

POST /partner/v1/checkout создаёт платёжную ссылку от имени клиента. Укажите клиента по client_id или external_id и передайте сумму и описание.

bash

Скачать

curl -X POST https://api.paybot.kz/partner/v1/checkout \
  -H "X-Partner-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 7f3c9a12-b7d4-4056-a1c2-e3f4b5d6c7e8" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_88421",
    "amount": 5000,
    "description": "Подписка на месяц",
    "expires_in_minutes": 60
  }'

Тело: client_id или external_id, amount (целые тенге), description (1–500), success_url, cancel_url, expires_in_minutes (5–10080, по умолчанию 60), allow_repeat, email_required, kaspi_account_id, metadata.

json

Скачать

{
  "id": 90321,
  "token": "pl_x1y2z3",
  "url": "https://paybot.kz/checkout/pl_x1y2z3",
  "qr_image_url": "https://api.paybot.kz/qr/pl_x1y2z3.png",
  "deep_link": "https://kaspi.kz/pay/...",
  "amount": 5000,
  "description": "Подписка на месяц",
  "status": "active",
  "expires_at": "2026-07-16T10:00:00Z",
  "client_id": 5012,
  "external_id": "user_88421"
}

Ведите пользователя на url (страница hosted checkout) или покажите qr_image_url. Заголовок Idempotency-Key здесь опционален, но защищает от двойного создания ссылки при повторе запроса.

Как получать вебхуки от партнёра

Есть два уровня вебхуков. Первый — вебхук на конкретного клиента: POST /partner/v1/clients/{ref}/webhooks создаёт приёмник, куда приходят события платежей этого клиента.

bash

Скачать

curl -X POST https://api.paybot.kz/partner/v1/clients/user_88421/webhooks \
  -H "X-Partner-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-saas.kz/paybot/user_88421/webhook",
    "events": ["payment.completed", "payment.refunded"]
  }'

Ответ 201 содержит secret (один раз) — проверка подписи такая же, как у обычных вебхуков: HMAC-SHA256 над "{timestamp}.{body}", см. раздел вебхуки. Удалить приёмник клиента — DELETE /partner/v1/clients/{ref}/webhooks/{id} (204).

Второй уровень — партнёрский вебхук на уровне всего портфеля (/partner/integration/webhook, авторизация JWT кабинета). Он присылает события о ваших клиентах в целом: client.created, client.kaspi_connected, client.plan_changed, payment.completed, payment.cancelled, payment.expired, payment.refunded, partner.webhook.test. Так вы узнаёте, например, что клиент подключил Kaspi, не опрашивая статус вручную.

Как впустить клиента в его кабинет

POST /partner/v1/clients/{ref}/login-link генерирует одноразовую ссылку входа в кабинет клиента — удобно, чтобы дать пользователю кнопку «Открыть платежи» прямо из вашего интерфейса.

bash

Скачать

curl -X POST https://api.paybot.kz/partner/v1/clients/user_88421/login-link \
  -H "X-Partner-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

json

Скачать

{
  "login_url": "https://paybot.kz/login/magic?token=...",
  "expires_at": "2026-07-16T09:15:00Z"
}

Ссылка одноразовая и с коротким сроком (expires_at) — генерируйте её в момент перехода пользователя, а не заранее.

Как смотреть платежи клиентов

GET /partner/v1/payments возвращает платежи по всем вашим клиентам с курсорной пагинацией (параметры cursor, limit, status, client_ref). Один платёж — GET /partner/v1/payments/{operation_id}. О курсорной модели — раздел пагинация.

FAQ

Чем X-Partner-API-Key отличается от X-API-Key?

X-Partner-API-Key (pk_...) авторизует вас как партнёра для /partner/v1/* — управление вашими клиентами. X-API-Key (kp_...) — это ключ конкретного клиента для /v2/* (создание его QR и счетов). Партнёрский ключ вы получаете один на всё портфолио, клиентские — выдаёте каждому через ротацию. Подробнее — аутентификация.

Нужно ли пользователю самому регистрироваться в PayBot?

Нет. Вы создаёте клиента через POST /partner/v1/clients, подключаете его Kaspi white-label через kaspi/start → verify, и пользователь остаётся в вашем интерфейсе. При необходимости даёте ему вход через одноразовый login-link.

Что вернёт повторный POST /partner/v1/clients с тем же external_id?

Существующего клиента с created: false — это upsert. Один external_id всегда соответствует одному аккаунту PayBot, так что повторный вызов безопасен и не создаёт дубликат.

Как узнать, что клиент подключил Kaspi?

Либо опросом GET /partner/v1/clients/{ref}/kaspi/status (поле connected), либо через партнёрский вебхук — событие client.kaspi_connected придёт автоматически, как только онбординг завершится.

Смежные разделы

•Аутентификация — ключи pk_..., kp_... и токены.
•Вебхуки — проверка подписи и обработка доставок.
•Hosted checkout — страница оплаты, на которую ведёт ссылка.