BANKA BOT Merchant API
    • Payments
      • Создать платёж
        POST
      • Получить платёж
        GET
    • Вебхук об изменении статуса платежа
    • Schemas
      • PaymentCreate
      • Payment
      • PaymentStatus
      • WebhookEvent
      • Error

      Вебхук об изменении статуса платежа

      Webhook
      POST
      payment_status
      Отправляется на ваш callback_url (из запроса создания платежа или
      из настроек кабинета; URL в платеже приоритетнее) при каждом переходе
      платежа в конечный статус: paid, expired, cancelled,
      underpaid. Если URL не задан нигде, вебхуки не отправляются.

      Требования к вашему endpoint#

      только HTTPS с валидным сертификатом (self-signed не поддерживается);
      публичный домен или IP, localhost и приватные диапазоны запрещены;
      ответ 2xx в течение 10 секунд, тело ответа игнорируется.

      Подпись#

      Каждый вебхук подписан HMAC SHA-256:
      заголовок: X-Webhook-Signature;
      подписываемая строка: сырое тело HTTP-запроса, байт в байт;
      ключ подписи: ваш webhook-секрет из кабинета (не API-ключ);
      значение: hex-строка в нижнем регистре.
      Проверка: вычислите hex(hmac_sha256(webhook_secret, raw_body)) и
      сравните с заголовком функцией постоянного времени
      (hmac.compare_digest и аналоги). Тело для подписи берите сырыми
      байтами до парсинга JSON: перепаковка JSON меняет байты и ломает
      подпись. Вебхук с неверной подписью отбрасывайте с ответом 400.

      Повторы и идемпотентность#

      Нет ответа 2xx — доставка повторяется с нарастающим интервалом
      (1 мин, 5 мин, 30 мин, далее каждые 2 часа) до 24 часов. Один и тот
      же вебхук может прийти повторно, в том числе после успешной
      доставки. Храните обработанные event_id: повторное событие
      подтверждайте ответом 200 без повторной обработки. Заказ не должен
      активироваться дважды.

      Request

      Authorization
      Bearer Token
      Provide your bearer token in the
      Authorization
      header when making requests to protected resources.
      Example:
      Authorization: Bearer ********************
      or
      Body Params application/jsonRequired

      Examples

      Responses

      🟢200OK
      Вебхук принят. Тело ответа игнорируется.
      This response does not have a body.
      Request Request Example
      Shell
      JavaScript
      Java
      Swift
      curl --location 'https://your-api-server.com' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "event_id": "9c7e6f7a-1b2c-4d3e-8f90-a1b2c3d4e5f6",
    "event_type": "payment.paid",
    "created_at": "2026-08-02T12:03:28Z",
    "payment": {
        "payment_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "order_code": "7XK4M2QD",
        "payment_url": "https://pay.banka.bot/7XK4M2QD",
        "status": "paid",
        "amount": 500,
        "amount_total": 540,
        "currency": "RUB",
        "method": "sbp",
        "order_id": "order_123",
        "created_at": "2026-08-02T12:00:00Z",
        "paid_at": "2026-08-02T12:03:27Z",
        "expires_at": "2026-08-02T13:00:00Z"
    }
}'
      Modified at 2026-08-02 13:09:09
      Previous
      Получить платёж
      Next
      PaymentCreate
      Built with