Webhooks

Webhook — асинхронное уведомление об изменении статуса операции, отправляемое платформой на URL, заданный мерчантом. Применяется в качестве основного способа получения финального состояния операции.

URL получателя

URL определяется по следующему приоритету:

1. Значение integrationMerhcnatData.webHook в теле запроса на создание операции. Действует только в пределах данной операции.
2. URL, сохранённый в настройках личного кабинета мерчанта. Применяется при отсутствии или невалидности значения integrationMerhcnatData.webHook.

При отсутствии URL в обоих источниках доставка событий не выполняется. В этом случае состояние операции определяется опросом эндпойнта GET /operation/operation/platform/{idPlatform}.

Условия доставки

Событие формируется при каждом изменении статуса операции. Для типовой операции Pay In формируются события при следующих переходах:

• created → in_progress;
• in_progress → success или failed.

При наличии промежуточных статусов (booking, pending_retry) формируются дополнительные события.

Финальными статусами считаются success и failed. Бизнес‑решения мерчанта о завершении операции должны приниматься исключительно по этим статусам.

Формат события

HTTP‑метод: POST.

Заголовок: Content-Type: application/json.

Тело запроса соответствует структуре ответа GET /operation/operation/platform/{idPlatform} (раздел Операции).

Pay In, финальный статус success

{
  "id": "d7b8e0f4-1b3a-4a3f-8d29-9c7c0a4d0a01",
  "idTransactionMerchant": "order-42",
  "typeOperation": "payIn",
  "status": "success",
  "currency": "RUB",
  "amountInitial": 1500,
  "amountRandomized": 1500.13,
  "amount": 1500.13,
  "amountComission": 30,
  "amountInCurrencyBalance": 14.95,
  "amountComissionInCurrencyBalance": 0.30,
  "exchangeRate": 100.30,
  "dateAdded": "2026-05-16T12:00:01.123Z",
  "dateUpdated": "2026-05-16T12:00:42.567Z",
  "paymentDetailsData": {
    "paymentMethod": "sbp",
    "bankName": "Банк-эквайер",
    "nameMediator": "И. И.",
    "number": "+79991234567",
    "numberAdditional": null,
    "qRcode": null
  }
}

Pay In, финальный статус failed

{
  "id": "0a4f7e91-6c12-4f30-9b88-1cd2e4f5a012",
  "idTransactionMerchant": "order-43",
  "typeOperation": "payIn",
  "status": "failed",
  "currency": "RUB",
  "amountInitial": 1500,
  "amountRandomized": 1500,
  "amount": 1500,
  "amountComission": 0,
  "amountInCurrencyBalance": 0,
  "amountComissionInCurrencyBalance": 0,
  "exchangeRate": 0,
  "dateAdded": "2026-05-16T12:00:01.123Z",
  "dateUpdated": "2026-05-16T12:08:14.901Z",
  "paymentDetailsData": {
    "paymentMethod": "sbp",
    "bankName": "Банк-эквайер",
    "nameMediator": "И. И.",
    "number": "+79991234567"
  }
}

Pay Out, финальный статус success

{
  "id": "8e1f0d24-3a2b-4c8f-9f1c-d3e8a5b9c021",
  "idTransactionMerchant": "withdraw-101",
  "typeOperation": "payOut",
  "status": "success",
  "currency": "RUB",
  "amount": 5000,
  "amountComission": 50,
  "amountInCurrencyBalance": 49.85,
  "amountComissionInCurrencyBalance": 0.50,
  "exchangeRate": 100.30,
  "dateAdded": "2026-05-16T12:05:11.422Z",
  "dateUpdated": "2026-05-16T12:06:48.901Z",
  "paymentDetailsData": null
}

Промежуточный статус pending_retry (Pay Out)

{
  "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "idTransactionMerchant": "withdraw-202",
  "typeOperation": "payOut",
  "status": "pending_retry",
  "currency": "RUB",
  "amount": 18000,
  "amountComission": 180,
  "amountInCurrencyBalance": 179.45,
  "amountComissionInCurrencyBalance": 1.80,
  "exchangeRate": 100.30,
  "dateAdded": "2026-05-16T12:10:01.000Z",
  "dateUpdated": "2026-05-16T12:11:30.500Z",
  "paymentDetailsData": null
}

Требования к получателю

Получатель события возвращает HTTP‑код из диапазона 2xx. Тело ответа игнорируется. Время ответа — не более 5 секунд.

При получении ответа, отличного от 2xx, при сетевом таймауте или разрыве соединения платформа выполняет повторную доставку с экспоненциальной задержкой. Гарантируется доставка каждого финального события не менее одного раза (at‑least‑once).

Идемпотентность обработки

Получатель обязан реализовать дедупликацию событий. В качестве ключа дедупликации применяется поле id (UUID операции на платформе). Допускается также дедупликация по бизнес‑идентификатору с проверкой текущего состояния заказа в системе мерчанта.

Безопасность

В текущей версии криптографическая подпись тела webhook не предусмотрена. До введения подписи рекомендуется применять следующие компенсирующие меры:

• ограничение источников запросов на уровне сетевой инфраструктуры по диапазону IP‑адресов платформы (запрашивается у менеджера);
• подтверждение состояния операции запросом GET /operation/operation/platform/{id} с предъявлением JWT‑токена до выполнения бизнес‑логики, инициируемой событием.

Содержание события

Событие не содержит:

• сведений о провайдере, обработавшем операцию;
• текстового описания причины статуса failed;
• технических служебных полей, не влияющих на бизнес‑логику.

Уведомления об изменении служебных полей без смены статуса не формируются.