/v1/webhook

Notifications of status change.

The request is sent when changing the order status.

Supported events:

ORDER_STATUS_UPDATED - a change in the payment status or delivery status
OPERATION_STATUS_UPDATED - a change in the status of the operation to confirm, cancel, or refund a payment

Request

POST

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

Production

POST

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

Sandbox

Body

application/json

{
  "event": "TRANSACTION_STATUS_UPDATE",
  "eventTime": "2025-01-01T00:00:00Z",
  "merchantId": "123e4567-e89b-12d3-a456-426614174000",
  "operation": {
    "externalOperationId": "example",
    "operationId": "123e4567-e89b-12d3-a456-426614174000",
    "operationType": "AUTHORIZE",
    "orderId": "example",
    "pointsUpdated": true,
    "status": "PENDING"
  },
  "order": {
    "deliveryStatus": "NEW",
    "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"
  }
}

Name	Description
event	Type: string Enum: `TRANSACTION_STATUS_UPDATE`, `ORDER_STATUS_UPDATED`, `OPERATION_STATUS_UPDATED`, `SUBSCRIPTION_STATUS_UPDATED`
eventTime	Type: string<date-time> Event time in the format `RFC 3339`; `YYYY-MM-DDThh:mm:ssTZD` Example: `2025-01-01T00:00:00Z`
merchantId	Type: string<uuid> Example: `123e4567-e89b-12d3-a456-426614174000`
operation	Type: OperationWebhookData Example `{ "externalOperationId": "example", "operationId": "123e4567-e89b-12d3-a456-426614174000", "operationType": "AUTHORIZE", "orderId": "example", "pointsUpdated": true, "status": "PENDING" }`
order	All of 1 type Type: OrderWebhookData Example `{ "deliveryStatus": "NEW", "orderId": "example", "paymentStatus": "PENDING" }` if event == ORDER_STATUS_UPDATED Example `{ "deliveryStatus": "NEW", "orderId": "example", "paymentStatus": "PENDING" }`
subscription	All of 1 type Type: SubscriptionWebhookData Example `{ "customerSubscriptionId": "123e4567-e89b-12d3-a456-426614174000", "nextWriteOff": "2025-01-01T00:00:00Z", "status": "NEW", "subscriptionPlanId": "123e4567-e89b-12d3-a456-426614174000" }` Subscription status. Transmitted if event == SUBSCRIPTION_STATUS_UPDATED. Example `{ "customerSubscriptionId": "123e4567-e89b-12d3-a456-426614174000", "nextWriteOff": "2025-01-01T00:00:00Z", "status": "NEW", "subscriptionPlanId": "123e4567-e89b-12d3-a456-426614174000" }`

OperationWebhookData

Name	Description
operationId	Type: string<uuid> Example: `123e4567-e89b-12d3-a456-426614174000`
operationType	Type: string Enum: `AUTHORIZE`, `BIND_CARD`, `REFUND`, `CAPTURE`, `VOID`, `RECURRING`, `PREPAYMENT`, `SUBMIT`
orderId	Type: string Example: `example`
status	Type: string Enum: `PENDING`, `SUCCESS`, `FAIL`
externalOperationId	Type: string Example: `example`
pointsUpdated	Type: boolean Shows whether Plus points have been updated. If yes, sync the cart.

Example

{
  "externalOperationId": "example",
  "operationId": "123e4567-e89b-12d3-a456-426614174000",
  "operationType": "AUTHORIZE",
  "orderId": "example",
  "pointsUpdated": true,
  "status": "PENDING"
}

OrderWebhookData

Name	Description
orderId	Type: string Order ID received in the /order/create response Example: `example`
deliveryStatus	Type: string Delivery statuses Enum: `NEW`, `ESTIMATING`, `EXPIRED`, `READY_FOR_APPROVAL`, `COLLECTING`, `PREPARING`, `DELIVERING`, `DELIVERED`, `RETURNING`, `RETURNED`, `FAILED`, `CANCELLED`, `null` Example: `NEW`
paymentStatus	Type: string Order status Enum: `PENDING`, `AUTHORIZED`, `CAPTURED`, `VOIDED`, `REFUNDED`, `CONFIRMED`, `PARTIALLY_REFUNDED`, `FAILED`, `null` Example: `PENDING`

Example

{
  "deliveryStatus": "NEW",
  "orderId": "example",
  "paymentStatus": "PENDING"
}

SubscriptionWebhookData

Name	Description
customerSubscriptionId	Type: string<uuid> Subscription ID. The SDK returns it when the subscription is created successfully. You can also save a subscription when you get the first notification on it. The same value will arrive in this field every time the subscription is updated. Example: `123e4567-e89b-12d3-a456-426614174000`
status	Type: string Subscription type Enum: `NEW`, `ACTIVE`, `CANCELLED`, `EXPIRED`
subscriptionPlanId	Type: string<uuid> ID of the subscription plan created in the dashboard or over the API. Example: `123e4567-e89b-12d3-a456-426614174000`
nextWriteOff	Type: string<date-time> Date of the next attempt to debit a subscription fee Example: `2025-01-01T00:00:00Z`

Example

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

Responses

200 OK

success

Body

application/json

{
  "status": "success"
}

Name

Description

status

Type: string

Default: success

400 Bad Request

bad request

Body

application/json

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

Name	Description
reasonCode	Type: string Enum: `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`
reason	Type: string Example: `example`
status	Type: string Default: `fail`

Was the article helpful?

Authentication

/v1/order/render ⦸