---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://pay.yandex.ru/docs/en/custom/backend/merchant-api/webhook.md
  - https://pay.yandex.ru/docs/ru/custom/backend/merchant-api/webhook.md
---
> **Documentation Index:** Fetch the complete configuration index at https://pay.yandex.ru/docs/ru/llms.txt

<!-- source: ru/custom/backend/merchant-api-hidden/webhook.md -->
<div class="openapi">

# /v1/webhook

<!-- markdownlint-disable-file -->

Нотификации, которые отправляются на бэкенд магазина при изменении статуса заказа или операции по заказу.

Поддерживаемые события:

- `ORDER_STATUS_UPDATED` — обновление статуса заказа;
- `OPERATION_STATUS_UPDATED` — обновление статуса операций списания, возврата или отмены платежа.

## Формат запроса {#webhook-format}

Запрос приходит на бэкенд магазина в формате `application/octet-stream`. В теле запроса передается JWT-токен, подписанный по алгоритму ES256.

Перед обработкой события проверьте подлинность JWT-токена. Подробнее см. в инструкции [Как принимать нотификации](#how-to).

Payload проверенного и декодированного JWT-токена содержит JSON с данными события. Посмотрите [примеры событий](#webhook-examples).

**Пример запроса от Яндекс Пэй:**

```(bash)
curl -X POST https://example.merchant.ru/some/prefix/v1/webhook \
  --header 'User-Agent: YandexPay/1.0' \
  --header 'Accept: */*' \
  --header 'Content-Type: application/octet-stream' \
  --header 'X-Request-Id: ff2a54885c4e45309853d2e33af1d63b_3a70f3062db640fcb2f3c34de1a27bd5' \
  --header 'X-Request-Timeout: 13970' \
  --compressed \
  -d eyJhbGciOiJFUzI1NiIsImV4cCI6MTcwMDk4NzYwMCwiaWF0IjoxNzAwOTg3MzAwLCJraWQiOiIxLW1lcmNoYW50LWFwaSIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElkIjoieHh4eHh4eHh4LXh4eC01eHh4LXh4eHh4LXh4eHh4eHh4IiwiZXZlbnQiOiJPUkRFUl9TVEFUVVNfVVBEQVRFRCIsImV2ZW50VGltZSI6IjIwMjMtMTEtMjZUMDg6MTE6MDkuMzU5MzcwKzAwOjAwIiwib3JkZXIiOnsib3JkZXJJZCI6IjcwMGFhM2YwNGRmNjRiM2I4NzEyZDZiNTFmNzUyZThiIiwicGF5bWVudFN0YXR1cyI6IkNBUFRVUkVEIn19.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Как принимать нотификации {#how-to}

### Шаг 1. Установите Callback URL

Укажите публично доступный HTTPS URL-адрес бэкенда магазина в поле **Callback URL** в личном кабинете Яндекс Пэй в разделе [Настройки](https://console.pay.yandex.ru/settings).

Указывайте Callback URL без `/v1/webhook` — этот путь добавится автоматически:

#|
|| **Callback URL** | **Куда придет запрос** ||
|| `https://example.merchant.ru` | `https://example.merchant.ru/v1/webhook` ||
|| `https://example.merchant.ru/v1/webhook` | `https://example.merchant.ru/v1/webhook/v1/webhook` ||
|#

Подробнее о Callback URL см. в разделе [Установка Callback URL](https://pay.yandex.ru/docs/ru/console/settings-pay-split.md#callback-settings).

### Шаг 2. Реализуйте обработчик нотификаций

На бэкенде магазина реализуйте эндпоинт `/v1/webhook` для обработки нотификаций от Яндекс Пэй. Обработчик должен соответствовать следующим требованиям:

**Входящие запросы:**

- Принимает POST-запросы с заголовком `Content-Type: application/octet-stream` и телом с JWT-токеном, подписанным по алгоритму ES256.
- Перед десериализацией payload JWT-токена проверяет подлинность токена. Подробнее читайте в разделе [Аутентификация](https://pay.yandex.ru/docs/ru/custom/backend/merchant-api/index.md).
- Обрабатывает payload JWT-токена, содержащий JSON с данными события. Посмотрите [примеры событий](#webhook-examples).

**Исходящие ответы:**

- При успешной обработке нотификации возвращает HTTP статус [200](#200-ok).
- При ошибке возвращает другие HTTP статусы, например, [4xx](#400-bad-request), с корректным `reasonCode`.

При отсутствии ответа или любом статусе кроме `200` Яндекс Пэй генерирует новый JWT-токен и повторяет отправку нотификации.

Подробнее об ответах и переотправке вебхуков см. в разделе [Responses](#responses).

## Решение проблем {#troubleshooting}

Если нотификации не приходят, проверьте следующие моменты:

- Неправильный адрес бэкенда

    Нотификации могут приходить не туда, куда ожидаете. [Указывайте Callback URL](https://pay.yandex.ru/docs/ru/console/settings-pay-split.md#callback-settings) без `/v1/webhook` — этот путь добавится автоматически:

    #|
    || **Callback URL** | **Куда придет запрос** ||
    || `https://example.merchant.ru` | `https://example.merchant.ru/v1/webhook` ||
    || `https://example.merchant.ru/v1/webhook` | `https://example.merchant.ru/v1/webhook/v1/webhook` ||
    |#

- Обработка `Content-Type`

    Убедитесь, что бэкенд вашего магазина готов принимать сообщения с заголовком `Content-Type: application/octet-stream`.

- SSL-сертификат

    Система не распознает самоподписанные SSL-сертификаты. Используйте сертификат от доверенного центра сертификации.

- Настройки брандмауэра

    Проверьте, что брандмауэр не блокирует входящие запросы и не обрезает тело запроса.

## Примеры событий {#webhook-examples}

### Оплата заказа

{% list tabs %}

- Успех

  ```json
  {
    "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
    "event": "ORDER_STATUS_UPDATED",
    "eventTime": "2023-11-26T08:11:09.359370+00:00",
    "order": {
      "orderId": "700aa3f04df64b3b8712d6b51f752e8b",
      "paymentStatus": "CAPTURED"
    }
  }
  ```

  Посмотрите пример JWT-токена на [jwt.io](https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImV4cCI6MTcwMDk4NzYwMCwiaWF0IjoxNzAwOTg3MzAwLCJraWQiOiIxLW1lcmNoYW50LWFwaSIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElkIjoieHh4eHh4eHh4LXh4eC01eHh4LXh4eHh4LXh4eHh4eHh4IiwiZXZlbnQiOiJPUkRFUl9TVEFUVVNfVVBEQVRFRCIsImV2ZW50VGltZSI6IjIwMjMtMTEtMjZUMDg6MTE6MDkuMzU5MzcwKzAwOjAwIiwib3JkZXIiOnsib3JkZXJJZCI6IjcwMGFhM2YwNGRmNjRiM2I4NzEyZDZiNTFmNzUyZThiIiwicGF5bWVudFN0YXR1cyI6IkNBUFRVUkVEIn19.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx).

- Неудача

  ```json
  {
    "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
    "event": "ORDER_STATUS_UPDATED",
    "eventTime": "2024-04-25T07:56:29.974810+00:00",
    "order": {
      "orderId": "253222_1714029088",
      "paymentStatus": "FAILED"
    }
  }
  ```

  Посмотрите пример JWT-токена на [jwt.io](https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImV4cCI6MTcxNDAzMjIyMSwiaWF0IjoxNzE0MDMxOTIxLCJraWQiOiIxLW1lcmNoYW50LWFwaSIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElkIjoieHh4eHh4eHh4LXh4eC01eHh4LXh4eHh4LXh4eHh4eHh4IiwiZXZlbnQiOiJPUkRFUl9TVEFUVVNfVVBEQVRFRCIsImV2ZW50VGltZSI6IjIwMjQtMDQtMjVUMDc6NTY6MjkuOTc0ODEwKzAwOjAwIiwib3JkZXIiOnsib3JkZXJJZCI6IjI1MzIyMl8xNzE0MDI5MDg4IiwicGF5bWVudFN0YXR1cyI6IkZBSUxFRCJ9fQ.v9dw_cR3_b4R5v0D8WRisrSPABxhegSSpEq4kz9s10fr5cUK150yWnwJREYCGQCm5BZK1Yydsquh-WE6OyRR2APOST).

{% endlist %}

### Возврат

{% note tip %}

Сначала изучите, как работают возвраты, в разделе [/v2/orders/{order_id}/refund](https://pay.yandex.ru/docs/ru/custom/backend/yandex-pay-api/order/merchant_v2_refund-post.md).

{% endnote %}

#### Полный возврат

Независимо от того, меняется ли статус заказа, отправляется 2 нотификации: по операции и по заказу.

{% list tabs %}

- Успех

  1. `OPERATION_STATUS_UPDATED` — операция возврата завершилась успешно:

  ```json
  {
    "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
    "event": "OPERATION_STATUS_UPDATED",
    "eventTime": "2024-04-19T10:27:53.323878+00:00",
    "operation": {
      "operationId": "73dec2cd-db5c-4386-be6d-10c5b5a2ee09",
      "orderId": "86283",
      "status": "SUCCESS",
      "operationType": "REFUND"
    }
  }
  ```

  2. `ORDER_STATUS_UPDATED` — заказ в перешел в терминальный статус `REFUNDED`. Больше нельзя вызывать возвраты.

  ```json
  {
    "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
    "event": "ORDER_STATUS_UPDATED",
    "eventTime": "2024-04-19T12:16:28.766392+00:00",
    "order": {
      "orderId": "86283",
      "paymentStatus": "REFUNDED"
    }
  }
  ```

  Посмотрите пример JWT-токена на [jwt.io](https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImV4cCI6MTcxMzUyOTI4OSwiaWF0IjoxNzEzNTI4OTg5LCJraWQiOiIxLW1lcmNoYW50LWFwaSIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElkIjoieHh4eHh4eHh4LXh4eC01eHh4LXh4eHh4LXh4eHh4eHh4IiwiZXZlbnQiOiJPUkRFUl9TVEFUVVNfVVBEQVRFRCIsImV2ZW50VGltZSI6IjIwMjQtMDQtMTlUMTI6MTY6MjguNzY2MzkyKzAwOjAwIiwib3JkZXIiOnsib3JkZXJJZCI6Ijg2MjgzIiwicGF5bWVudFN0YXR1cyI6IlJFRlVOREVEIn19.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx).

- Неудача

  1. `OPERATION_STATUS_UPDATED` — операция возврата завершилась неуспешно:

  ```json
  {
    "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
    "event": "OPERATION_STATUS_UPDATED",
    "eventTime": "2024-06-13T22:27:53.323878+00:00",
    "operation": {
      "operationId": "73dec2cd-db5c-4386-be6d-10c5b5a2ee08",
      "orderId": "9c8aed6d-a8e5-4c6a-acd8-645538173f66",
      "status": "FAIL",
      "operationType": "REFUND"
    }
  }
  ```

  Посмотрите пример JWT-токена на [jwt.io](https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImV4cCI6MTcxODMxNzk3NCwiaWF0IjoxNzE4MzE3Njc0LCJraWQiOiIxLW1lcmNoYW50LWFwaSIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElkIjoieHh4eHh4eHh4LXh4eC01eHh4LXh4eHh4LXh4eHh4eHh4IiwiZXZlbnQiOiJPUEVSQVRJT05fU1RBVFVTX1VQREFURUQiLCJldmVudFRpbWUiOiIyMDI0LTA2LTEzVDIyOjI3OjUzLjMyMzg3OCswMDowMCIsIm9wZXJhdGlvbiI6eyJvcGVyYXRpb25JZCI6IjczZGVjMmNkLWRiNWMtNDM4Ni1iZTZkLTEwYzViNWEyZWUwOCIsIm9yZGVySWQiOiI5YzhhZWQ2ZC1hOGU1LTRjNmEtYWNkOC02NDU1MzgxNzNmNjYiLCJzdGF0dXMiOiJGQUlMIiwib3BlcmF0aW9uVHlwZSI6IlJFRlVORCJ9fQ.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx).

  2. `ORDER_STATUS_UPDATED` — заказ остался в предыдущем статусе `CAPTURED`:

  ```json
  {
    "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
    "event": "ORDER_STATUS_UPDATED",
    "eventTime": "2024-06-13T22:27:54.323878+00:00",
    "order": {
      "orderId": "9c8aed6d-a8e5-4c6a-acd8-645538173f66",
      "paymentStatus": "CAPTURED"
    }
  }
  ```

{% endlist %}

#### Частичный возврат

Вы можете вернуть всю сумму заказа несколькими частичными возвратами. Когда сумма всех возвратов достигнет полной стоимости, заказ перейдет в терминальный статус `REFUNDED`. После этого нельзя вызывать возвраты.

Независимо от того, меняется ли статус заказа, отправляется 2 нотификации: по операции и по заказу.

Рассмотрим на примере заказа с тремя пачками сока.

1. Совершили частичный возврат одного сока. Вам придет 2 нотификации:

    1. `OPERATION_STATUS_UPDATED` — операция возврата завершилась успешно:

        ```json
        {
          "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
          "event": "OPERATION_STATUS_UPDATED",
          "eventTime": "2024-04-19T10:27:53.323878+00:00",
          "operation": {
            "operationId": "73dec3cs-sd5t-4356-ne6d-10c79b5d2ee09",
            "externalOperationId": "123-partial-refund-1",
            "orderId": "123",
            "status": "SUCCESS",
            "operationType": "REFUND"
          }
        }
        ```

    2. `ORDER_STATUS_UPDATED` — заказ в перешел в статус `PARTIALLY_REFUNDED`:

        ```json
        {
          "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
          "event": "ORDER_STATUS_UPDATED",
          "eventTime": "2024-04-19T12:16:28.766392+00:00",
          "order": {
            "orderId": "123",
            "paymentStatus": "PARTIALLY_REFUNDED"
          }
        }
        ```

2. Совершили второй частичный возврат одного сока. Вам придет 2 нотификации:

    1. `OPERATION_STATUS_UPDATED` — операция возврата завершилась успешно:

        ```json
        {
          "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
          "event": "OPERATION_STATUS_UPDATED",
          "eventTime": "2024-04-19T13:27:53.323878+00:00",
          "operation": {
            "operationId": "28fba9ds-kl2m-7891-qw3r-45e82c7f1bb12",
            "externalOperationId": "123-partial-refund-2",
            "orderId": "123",
            "status": "SUCCESS",
            "operationType": "REFUND"
          }
        }
        ```

    2. `ORDER_STATUS_UPDATED` — заказ остался в статусе `PARTIALLY_REFUNDED`:

        ```json
        {
          "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
          "event": "ORDER_STATUS_UPDATED",
          "eventTime": "2024-04-19T13:27:54.321878+00:00",
          "order": {
            "orderId": "123",
            "paymentStatus": "PARTIALLY_REFUNDED"
          }
        }
        ```

3. Совершили третий частичный возврат. Сумма всех возвратов достигла полной стоимости. Вам придет 2 нотификации:

    1. `OPERATION_STATUS_UPDATED` — операция возврата завершилась успешно:

        ```json
        {
          "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
          "event": "OPERATION_STATUS_UPDATED",
          "eventTime": "2024-04-19T13:40:51.323878+00:00",
          "operation": {
            "operationId": "64abc2ts-rj4y-3187-mf5g-56b71e9a4dd67",
            "externalOperationId": "123-partial-refund-3",
            "orderId": "123",
            "status": "SUCCESS",
            "operationType": "REFUND"
          }
        }
        ```

    2. `ORDER_STATUS_UPDATED` — заказ в перешел в терминальный статус `REFUNDED`. Больше нельзя вызывать возвраты.

        ```json
        {
          "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
          "event": "ORDER_STATUS_UPDATED",
          "eventTime": "2024-04-19T14:16:28.766392+00:00",
          "order": {
            "orderId": "123",
            "paymentStatus": "REFUNDED"
          }
        }
        ```

### Двухстадийный платеж: списание заблокированных средств

В [двухстадийных платежах](https://pay.yandex.ru/docs/ru/hold/index.md) после подтверждения списания средств методом [/v1/orders/{order_id}/capture](https://pay.yandex.ru/docs/ru/custom/backend/yandex-pay-api/order/merchant_v1_capture-post.md) вам придет 2 нотификации:

1. `OPERATION_STATUS_UPDATED` — операция списания средств завершилась успешно:

    ```json
    {
      "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
      "event": "OPERATION_STATUS_UPDATED",
      "eventTime": "2024-07-22T03:19:07.425889+00:00",
      "operation": {
        "operationId": "2d23342e-6688-4201-bee2-299330ff7ba6",
        "orderId": "000540777",
        "status": "SUCCESS",
        "operationType": "CAPTURE",
        "externalOperationId": "000540777-capture"
      }
    }
    ```

    Посмотрите пример JWT-токена на [jwt.io](https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImV4cCI6MTcyMTYxODY0OCwiaWF0IjoxNzIxNjE4MzQ4LCJraWQiOiIxLW1lcmNoYW50LWFwaSIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElkIjoieHh4eHh4eHh4LXh4eC01eHh4LXh4eHh4LXh4eHh4eHh4IiwiZXZlbnQiOiJPUEVSQVRJT05fU1RBVFVTX1VQREFURUQiLCJldmVudFRpbWUiOiIyMDI0LTA3LTIyVDAzOjE5OjA3LjQyNTg4OSswMDowMCIsIm9wZXJhdGlvbiI6eyJvcGVyYXRpb25JZCI6IjJkMjMzNDJlLTY2ODgtNDIwMS1iZWUyLTI5OTMzMGZmN2JhNiIsIm9yZGVySWQiOiIwMDA1NDA3NzciLCJzdGF0dXMiOiJTVUNDRVNTIiwib3BlcmF0aW9uVHlwZSI6IkNBUFRVUkUiLCJleHRlcm5hbE9wZXJhdGlvbklkIjoiMDAwNTQwNzc3LWNhcHR1cmUifX0.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx).

2. `ORDER_STATUS_UPDATED` — заказ в перешел в статус `CAPTURED`:

    ```json
    {
      "merchantId": "xxxxxxxxx-xxx-5xxx-xxxxx-xxxxxxxx",
      "event": "ORDER_STATUS_UPDATED",
      "eventTime": "2024-07-22T06:29:07.425889+00:00",
      "order": {
        "orderId": "000540777",
        "paymentStatus": "CAPTURED"
      }
    }
    ```

## Request

<div class="openapi__requests">

<div class="openapi__request__wrapper" style="--method: var(--dc-openapi-methods-post);margin-bottom: 12px">

<div class="openapi__request">

POST {.openapi__method}
```text translate=no
https://example.merchant.ru/v1/webhook
```

</div>

Production

</div>

<div class="openapi__request__wrapper" style="--method: var(--dc-openapi-methods-post);margin-bottom: 12px">

<div class="openapi__request">

POST {.openapi__method}
```text translate=no
https://sandbox.example.merchant.ru/v1/webhook
```

</div>

Sandbox

</div>

</div>

<div class="openapi-entity">

### Body

{% cut "application/json" %}

```json translate=no
{
  "event": "TRANSACTION_STATUS_UPDATE",
  "eventTime": "2025-05-26T21:00:36.08847+00:00",
  "merchantId": "123e4567-e89b-12d3-a456-426614174000",
  "operation": {
    "externalOperationId": "example",
    "operationId": "5d32f295-8723-457d-81f9-ab13f17b7bd6",
    "operationType": "AUTHORIZE",
    "orderId": "example",
    "status": "PENDING"
  },
  "order": {
    "cartUpdated": true,
    "orderId": "example",
    "paymentStatus": "PENDING"
  },
  "subscription": {
    "customerSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
    "nextWriteOff": "2025-01-01T00:00:00Z",
    "status": "NEW",
    "subscriptionPlanId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

{% endcut %}

#|
|| **Name** | **Description** ||
||

_event_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

Тип события:
- `ORDER_STATUS_UPDATED` — обновление статуса заказа;
- `OPERATION_STATUS_UPDATED` — обновление статуса операций списания, возврата или отмены платежа.

_Enum:_{.json-schema-reset .json-schema-value} `TRANSACTION_STATUS_UPDATE`, `ORDER_STATUS_UPDATED`, `OPERATION_STATUS_UPDATED`, `SUBSCRIPTION_STATUS_UPDATED`
{.table-cell}
||
||

_eventTime_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string&lt;date-time&gt;

Время события в формате `RFC 3339`: `YYYY-MM-DDThh:mm:ssTZD`.

_Example:_{.json-schema-reset .json-schema-example} `2025-05-26T21:00:36.08847+00:00`
{.table-cell}
||
||

_merchantId_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string&lt;uuid&gt;

ID (идентификатор) продавца.

_Example:_{.json-schema-reset .json-schema-example} `123e4567-e89b-12d3-a456-426614174000`
{.table-cell}
||
||

_operation_{.json-schema-reset .json-schema-property}
{.table-cell}|
{% cut "**All of 1 type**" %}{.json-schema-combinators data-marker=and}

- **Type**: [OperationWebhookData](#entity-OperationWebhookData)

  {% cut "**Example**" %}{.json-schema-example}

  ```json translate=no
  {
    "externalOperationId": "example",
    "operationId": "5d32f295-8723-457d-81f9-ab13f17b7bd6",
    "operationType": "AUTHORIZE",
    "orderId": "example",
    "status": "PENDING"
  }
  ```

  {% endcut %}

{% endcut %}

Информация по операции. Приходит с событием `OPERATION_STATUS_UPDATED`

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "externalOperationId": "example",
  "operationId": "5d32f295-8723-457d-81f9-ab13f17b7bd6",
  "operationType": "AUTHORIZE",
  "orderId": "example",
  "status": "PENDING"
}
```

{% endcut %}
{.table-cell}
||
||

_order_{.json-schema-reset .json-schema-property}
{.table-cell}|
{% cut "**All of 1 type**" %}{.json-schema-combinators data-marker=and}

- **Type**: [OrderWebhookData](#entity-OrderWebhookData)

  {% cut "**Example**" %}{.json-schema-example}

  ```json translate=no
  {
    "cartUpdated": true,
    "orderId": "example",
    "paymentStatus": "PENDING"
  }
  ```

  {% endcut %}

{% endcut %}

Информация по заказу. Приходит с событием `ORDER_STATUS_UPDATED`

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "cartUpdated": true,
  "orderId": "example",
  "paymentStatus": "PENDING"
}
```

{% endcut %}
{.table-cell}
||
||

_subscription_{.json-schema-reset .json-schema-property}
{.table-cell}|
{% cut "**All of 1 type**" %}{.json-schema-combinators data-marker=and}

- **Type**: [SubscriptionWebhookData](#entity-SubscriptionWebhookData)

  {% cut "**Example**" %}{.json-schema-example}

  ```json translate=no
  {
    "customerSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
    "nextWriteOff": "2025-01-01T00:00:00Z",
    "status": "NEW",
    "subscriptionPlanId": "123e4567-e89b-12d3-a456-426614174000"
  }
  ```

  {% endcut %}

{% endcut %}

Состояние подписки.

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "customerSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
  "nextWriteOff": "2025-01-01T00:00:00Z",
  "status": "NEW",
  "subscriptionPlanId": "123e4567-e89b-12d3-a456-426614174000"
}
```

{% endcut %}
{.table-cell}
||
|#{.json-schema-properties}

</div>

<div class="openapi-entity">

### OperationWebhookData {#entity-OperationWebhookData}

#|
|| **Name** | **Description** ||
||

_operationId_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string&lt;uuid&gt;

Идентификатор операции.

_Example:_{.json-schema-reset .json-schema-example} `5d32f295-8723-457d-81f9-ab13f17b7bd6`
{.table-cell}
||
||

_operationType_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

Тип операции. Подробнее о типах операций читайте в разделе [Статусы операций](../../../payments/statuses).

_Enum:_{.json-schema-reset .json-schema-value} `AUTHORIZE`, `BIND_CARD`, `REFUND`, `CAPTURE`, `VOID`, `RECURRING`, `PREPAYMENT`, `SUBMIT`
{.table-cell}
||
||

_orderId_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

ID заказа, переданный в [/v1/orders](https://pay.yandex.ru/docs/ru/custom/backend/yandex-pay-api/order/merchant_v1_orders-post.md) при создании заказа.

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_status_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

Статус операции. Подробнее о статусах операций читайте в разделе [Статусы операций](../../../payments/statuses).

_Enum:_{.json-schema-reset .json-schema-value} `PENDING`, `SUCCESS`, `FAIL`
{.table-cell}
||
||

_externalOperationId_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Идентификатор операции в системе продавца. Должен быть уникальным.

Передайте этот параметр, чтобы отслеживать конкретную операцию через метод [v1/operations/external_operation_id](../yandex-pay-api/operation/merchant_v1_operations-get)

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
|#{.json-schema-properties}

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "externalOperationId": "example",
  "operationId": "5d32f295-8723-457d-81f9-ab13f17b7bd6",
  "operationType": "AUTHORIZE",
  "orderId": "example",
  "status": "PENDING"
}
```

{% endcut %}

</div>

<div class="openapi-entity">

### OrderWebhookData {#entity-OrderWebhookData}

#|
|| **Name** | **Description** ||
||

_orderId_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

ID заказа, переданный в [/v1/orders](https://pay.yandex.ru/docs/ru/custom/backend/yandex-pay-api/order/merchant_v1_orders-post.md) при создании заказа.

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_paymentStatus_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

Статус платежа в заказе. Подробнее читайте в разделе [Статусы платежей](https://pay.yandex.ru/docs/ru/payments/statuses.md#payments-statuses).

_Enum:_{.json-schema-reset .json-schema-value} `PENDING`, `AUTHORIZED`, `CAPTURED`, `VOIDED`, `REFUNDED`, `CONFIRMED`, `PARTIALLY_REFUNDED`, `FAILED`
{.table-cell}
||
||

_cartUpdated_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: boolean

Была ли обновлена корзина. Возвращается при оплате баллами.Если флаг имеет значение `true`, получите актуальную корзину.
{.table-cell}
||
|#{.json-schema-properties}

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "cartUpdated": true,
  "orderId": "example",
  "paymentStatus": "PENDING"
}
```

{% endcut %}

</div>

<div class="openapi-entity">

### SubscriptionWebhookData {#entity-SubscriptionWebhookData}

#|
|| **Name** | **Description** ||
||

_customerSubscriptionId_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string&lt;uuid&gt;

ID подписки. Возвращается из SDK при успешном создании подписки. Также можно сохранить подписку при получении первой нотификации по ней. Дальнейшие обновления по этой подписке будут приходить с таким же значением этого поля.

_Example:_{.json-schema-reset .json-schema-example} `123e4567-e89b-12d3-a456-426614174000`
{.table-cell}
||
||

_status_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

Статус подписки.

_Enum:_{.json-schema-reset .json-schema-value} `NEW`, `ACTIVE`, `CANCELLED`, `EXPIRED`
{.table-cell}
||
||

_subscriptionPlanId_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string&lt;uuid&gt;

ID плана подписки, созданного в личном кабинете или через API.

_Example:_{.json-schema-reset .json-schema-example} `123e4567-e89b-12d3-a456-426614174000`
{.table-cell}
||
||

_nextWriteOff_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string&lt;date-time&gt;

Дата следующей попытки списания денег по подписке.

_Example:_{.json-schema-reset .json-schema-example} `2025-01-01T00:00:00Z`
{.table-cell}
||
|#{.json-schema-properties}

{% cut "**Example**" %}{.json-schema-example}

```json translate=no
{
  "customerSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
  "nextWriteOff": "2025-01-01T00:00:00Z",
  "status": "NEW",
  "subscriptionPlanId": "123e4567-e89b-12d3-a456-426614174000"
}
```

{% endcut %}

</div>

## Responses

<div class="openapi__response__code__200">

## 200 OK

Вебхук успешно получен и обработан.
Тело ответа может быть любым, рекомендуем отправить `{"status": "success"}`.
При получении `200` Яндекс Пэй прекращает отправку повторных вебхуков.

<div class="openapi-entity">

### Body

{% cut "application/json" %}

```json translate=no
{
  "status": "success"
}
```

{% endcut %}

#|
|| **Name** | **Description** ||
||

_status_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

_Default:_{.json-schema-reset .json-schema-value} `success`
{.table-cell}
||
|#{.json-schema-properties}

</div>

</div>

<div class="openapi__response__code__400">

## 400 Bad Request

Ошибка обработки вебхука.
При отсутствии ответа или любом статусе кроме `200` Яндекс Пэй генерирует новый JWT-токен и повторяет отправку вебхука:
- первые 10 раз через 5 мс;
- далее с экспоненциально возрастающим интервалом до 15 минут;
- затем каждые 15 минут в течение 24 часов.
Общее время повторных отправок — 24 часа. После этого вебхук считается недоставленным.

<div class="openapi-entity">

### Body

{% cut "application/json" %}

```json translate=no
{
  "reason": "example",
  "reasonCode": "FORBIDDEN",
  "status": "fail"
}
```

{% endcut %}

#|
|| **Name** | **Description** ||
||

_reasonCode_{.json-schema-reset .json-schema-property .json-schema-required}
{.table-cell}|
**Type**: string

Код ошибки:

- `FORBIDDEN` — заказ существует, но был оплачен не через Яндекс Пэй;
- `ORDER_NOT_FOUND` — заказ не найден в системе продавца;
- `ORDER_AMOUNT_MISMATCH` — сумма заказа не совпадает с суммой в системе продавца;
- `ORDER_DETAILS_MISMATCH` — детали заказа отличаются от данных в системе продавца;
- `OTHER` — общая ошибка;
- `UNAUTHORIZED` — не удалось проверить подпись JWT-токена;
- `TOKEN_EXPIRED` — срок действия JWT-токена истек;
- `CONFLICT` — данные в нотификации расходятся с состоянием заказа в системе продавца. Например, пришла нотификация об оплате для отмененного заказа.

_Enum:_{.json-schema-reset .json-schema-value} `FORBIDDEN`, `ITEM_NOT_FOUND`, `ORDER_NOT_FOUND`, `ORDER_AMOUNT_MISMATCH`, `ORDER_DETAILS_MISMATCH`, `OUT_OF_INVENTORY`, `PICKUP_POINT_NOT_FOUND`, `SHIPPING_DETAILS_MISMATCH`, `OTHER`, `UNAUTHORIZED`, `TOKEN_EXPIRED`, `CONFLICT`
{.table-cell}
||
||

_reason_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

Описание причины ошибки.

_Example:_{.json-schema-reset .json-schema-example} `example`
{.table-cell}
||
||

_status_{.json-schema-reset .json-schema-property}
{.table-cell}|
**Type**: string

_Default:_{.json-schema-reset .json-schema-value} `fail`
{.table-cell}
||
|#{.json-schema-properties}

</div>

</div>

</div>
<!-- endsource: ru/custom/backend/merchant-api-hidden/webhook.md -->


[*Deprecated]: No longer supported, please use an alternative and newer version.