Журнал событий

Журнал событий — это единая лента всего, что произошло в вашем аккаунте PayBot: оплаты, отмены, истечения, изменения платёжных ссылок и тарифа, сбои вебхуков. Забирайте его через GET /v2/events с курсорной пагинацией — это pull-модель, надёжная альтернатива и дополнение к push-вебхукам, особенно когда нужно восстановить пропущенные события после простоя вашего сервера.

Endpoint авторизуется API-ключом (X-API-Key) или JWT кабинета (Authorization: Bearer), так что лента доступна и из серверной интеграции, и из личного кабинета.

Как получить ленту событий

Отправьте GET /v2/events. Ответ — стандартный курсорный конверт: массив data и поля next_cursor / has_more.

curl "https://api.paybot.kz/v2/events?limit=20" \
  -H "X-API-Key: kp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "data": [
    {
      "id": "evt_a1b2c3d4",
      "type": "payment.completed",
      "data": {
        "operation_id": "op_7f3c9a12",
        "amount": 5000,
        "status": "paid",
        "phone": "7017770001"
      },
      "created_at": "2026-07-16T09:25:11Z"
    },
    {
      "id": "evt_9f8e7d6c",
      "type": "payment_link.created",
      "data": {
        "token": "pl_a1b2c3",
        "amount": 12000
      },
      "created_at": "2026-07-16T09:10:03Z"
    }
  ],
  "next_cursor": "eyJpZCI6ImV2dF85ZjhlN2Q2YyJ9",
  "has_more": true
}

Каждый элемент EventItem содержит: id (идентификатор события), type (тип), data (полезная нагрузка, структура зависит от типа), created_at (время в UTC).

Какие типы событий бывают

В ленту пишутся девять типов событий:

Поле data — свободный объект, набор ключей зависит от type. Рендерите ленту по словарю известных типов, а для незнакомого типа показывайте data как есть (JSON), чтобы новые события не ломали интеграцию.

Отфильтровать ленту по одному типу можно параметром type.

curl "https://api.paybot.kz/v2/events?type=payment.completed&limit=50" \
  -H "X-API-Key: kp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Чем события отличаются от вебхуков

Это два взгляда на один и тот же поток данных, но с разной механикой доставки.

На практике их комбинируют: вебхуки дают мгновенную реакцию, а GET /v2/events служит страховкой — периодической сверкой, которая догоняет всё, что вебхук мог не доставить.

Как обойти все события циклом

Лента отсортирована created_at DESC (сначала новые). Идите по курсору, пока has_more == true, передавая next_cursor как есть — не парсите и не собирайте его вручную.

import requests

def iter_events(api_key: str, event_type: str | None = None):
    url = "https://api.paybot.kz/v2/events"
    headers = {"X-API-Key": api_key}
    cursor = None
    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor
        if event_type:
            params["type"] = event_type
        page = requests.get(url, headers=headers, params=params).json()
        for event in page["data"]:
            yield event
        if not page["has_more"]:
            break
        cursor = page["next_cursor"]

for event in iter_events("kp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"):
    print(event["created_at"], event["type"])

Чтобы регулярно забирать только новое, сохраняйте id последнего обработанного события и останавливайте обход, когда снова его встретите. Подробнее про курсор и признак has_more — в разделе пагинация.

FAQ

Как забрать события, которые пропустил из-за простоя?

Просто прочитайте GET /v2/events от свежих к старым, пока не дойдёте до последнего обработанного id. В отличие от вебхуков, лента ничего не «теряет» — все девять типов событий пишутся на бэке и доступны по запросу.

Можно ли фильтровать события по дате?

Нет. GET /v2/events принимает только type и курсор — фильтра по датам или диапазону в API нет. Ограничивайте выборку на своей стороне по полю created_at, останавливая обход, когда события становятся старше нужного порога.

Какой лимит на страницу?

Параметр limit — от 1 до 100, по умолчанию 20. Больше 100 за один запрос получить нельзя, листайте курсором.

Нужен ли API-ключ или подойдёт токен кабинета?

Подойдёт любой из двух: X-API-Key для серверной интеграции или Authorization: Bearer для кабинета. Про способы авторизации — раздел аутентификация.

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

• •Вебхуки — push-уведомления о событиях в реальном времени.
• •Пагинация — курсорная модель и обход всех страниц.