/v1/webhook

Notifications about status updates.

A request is sent when the order status or order operation status changes.

Supported events:

• ORDER_STATUS_UPDATED: Update of the order status.
• OPERATION_STATUS_UPDATED: Status updated for charge, refund, or cancellation operations.

Request format

A request is received in application/octet-stream format as a JWT token signed by the ES256 algorithm. Before handling the request, validate it. To learn how to do this, see Authentication.

The payload of a validated and decoded JWT token contains JSON with event data. See sample events.

Operation idempotency

When performing operations with an order, such as making a refund via the /v2/orders/{order_id}/refund method call, be sure to pass the unique operation ID in the externalOperationId parameter.

This allows you to:

• Understand what operation you received a notification for.
• Check the operation status by calling the v1/operations/{external_operation_id} method.
• Prevent duplication.

If you repeat a request with the same externalOperationId value, you'll get the following:

• Information about the current operation if it's in progress.
• An error with the reasonCode: "DUPLICATE_EXTERNAL_OPERATION_ID" if the operation is complete.

Sample events

Paying for an order

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

  curl -X POST https://test.uz/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

{
  "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"
  }
}

Return

Full refund

Regardless of whether the order status changes, two notifications are sent: one for the operation and one for the order.

Partial refund

You can refund the order amount as multiple partial refunds. Once the sum of all refunds reaches the total order value, the order switches to the REFUNDED terminal status. After that, you can no longer call refund methods.

Regardless of whether the order status changes, two notifications are sent: one for the operation and one for the order.

Let's take an example of an order of three cartons of juice.

1. A partial refund is made for one carton of juice. You'll get two notifications:

   1. OPERATION_STATUS_UPDATED: Refund has been successfully completed:

      {
        "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: The order is now in the PARTIALLY_REFUNDED status.

      {
        "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. Another partial refund is made for one carton of juice. You'll get two notifications:

   1. OPERATION_STATUS_UPDATED: Refund has been successfully completed:

      {
        "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: The order is still in the PARTIALLY_REFUNDED status:

      {
        "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. A third partial refund is issued. The sum of all refunds is now equal to the total order value. You'll get two notifications:

   1. OPERATION_STATUS_UPDATED: Refund has been successfully completed:

      {
        "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: The order is now in the REFUNDED terminal status. You can no longer call refund methods.

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

Request

https://example.merchant.uz/v1/webhook

https://sandbox.example.merchant.uz/v1/webhook

{
  "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"
  }
}

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

{
  "cartUpdated": true,
  "orderId": "example",
  "paymentStatus": "PENDING"
}

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

Responses

{
  "status": "success"
}

{
  "reason": "example",
  "reasonCode": "FORBIDDEN",
  "status": "fail"
}