/v2/orders/{order_id}/refund

Запрос на возврат средств за заказ.

Метод является асинхронным.

Схема процесса возврата

Ограничения

Вы можете сделать полный или частичный возврат платежа.

Возвраты доступны для платежей в одном из статусов paymentStatus:

• CAPTURED — заказ успешно оплачен, средства списаны со счета плательщика;
• PARTIALLY_REFUNDED — совершен частичный возврат средств за заказ.

После успешного выполнения возврата статус платежа paymentStatus изменится:

• на REFUNDED, если был произведен полный возврат;
• на PARTIALLY_REFUNDED, если после совершения возврата в заказе остались товары.

Сумма возвратов за текущий день будет удержана на следующий рабочий день из выплаты партнеру за заказ.

Пример: в вашем магазине совершен заказ на 1000 рублей и сделан возврат на 200 рублей. На следующий рабочий день вы получите выплату 800 рублей (1000 − 200).

Отслеживать изменения статуса возврата можно через нотификации /webhook, а также с помощью запросов:

• /operations/{external_operation_id}/
• /order/{order_id}/

Примеры проверки статуса возврата

С помощью метода /operations/{external_operation_id}/ по externalOperationId можно проверить состояние текущего возврата.

В примере ниже операция не завершена — "status": "PENDING". Нельзя отправить повторный запрос на возврат.

{
  "code": 200,
  "status": "success",
  "data": {
    "operation": {
      "operationId": "52b3c4a8-528b-45eb-a57f-8f808f65d28f",
      "operationType": "REFUND",
      "orderId": "OrderS-2038",
      "amount": "250.00",
      "pointsAmount": null,
      "status": "PENDING", // возврат в процессе
      "reason": null,
      "params": { "motive": null, "branch_id": null, "manager_id": null },
      "externalOperationId": "OrderS-2038",
      "created": "2025-03-14T14:58:45.850206+03:00",
      "updated": "2025-03-14T14:58:45.850206+03:00"
    }
  }
}

С помощью метода /operations/{external_operation_id}/ можно проверить все детали заказа.

В примере ниже операция возврата завершена успешно — "status": "SUCCESS", а платеж в статусе "paymentStatus": "PARTIALLY_REFUNDED". Можно отправить повторный запрос на возврат.

{
  "code": 200,
  "status": "success",
  "data": {
    "operations": [
      {
        "operationId": "52b3c4a8-528b-45eb-a57f-8f808f65d28f",
        "operationType": "REFUND",
        "orderId": "OrderS-2038",
        "amount": "250.00",
        "status": "SUCCESS", // возврат успешно завершен
        "reason": null,
        "params": { "motive": null, "branch_id": null, "manager_id": null },
        "externalOperationId": "OrderS-2038",
        "created": "2025-03-14T14:58:45.850206+03:00",
        "updated": "2025-03-14T14:58:46.084886+03:00",
        "approvalCode": null
      },
      {
        "operationId": "9c763cfb-dcf6-4056-be8f-ca9e2e61d772",
        "operationType": "AUTHORIZE",
        "orderId": "OrderS-2038",
        "amount": "500.00",
        "status": "SUCCESS",
        "reason": null,
        "params": {},
        "externalOperationId": null,
        "created": "2025-03-14T14:58:07.161667+03:00",
        "updated": "2025-03-14T14:58:07.414886+03:00",
        "approvalCode": null
      }
    ],
    "order": {
      "currencyCode": "RUB",
      "cart": {
        "items": [
          {
            "productId": "p2",
            "quantity": { "count": "1", "available": null, "label": null },
            "type": "UNSPECIFIED",
            "title": "Яндекс.Станция Мини",
            "description": null,
            "total": "250",
            "subtotal": null,
            "discountedUnitPrice": "250",
            "unitPrice": null,
            "measurements": null,
            "receipt": null,
            "finalPrice": "250",
            "pointsAmount": null,
            "features": null
          }
        ],
        "total": { "amount": "250", "pointsAmount": null, "label": null },
        "cartId": "1eed9a9827e68ba8981d9961c1237624fabc19cda05044b574e06302e83c7549",
        "externalId": null,
        "coupons": null,
        "discounts": null,
        "measurements": null
      },
      "merchantId": "76cc0f5c-91c4-40f2-9794-64a64c3c6011",
      "orderAmount": "250.00",
      "orderId": "OrderS-2038",
      "paymentMethod": { "methodType": "CARD", "cardLast4": "0412", "cardNetwork": "MASTERCARD" },
      "shippingMethod": null,
      "metadata": null,
      "created": "2025-03-14T14:58:03.699930+03:00",
      "updated": "2025-03-14T14:58:46.084886+03:00",
      "paymentStatus": "PARTIALLY_REFUNDED", // платеж частично возвращен
      "reason": null,
      "paymentUrl": "https://`[`sandbox.pay.ya.ru`](http://sandbox.pay.ya.ru)`/l/I1RnP9",
      "isPrepayment": false,
      "splitCode": null
    },
    "delivery": null
  }
}

Виды возвратов

Доступен полный или частичный возврат платежа.

Для выполнения полного возврата передайте только refundAmount, равный сумме заказа.

Для выполнения частичного передайте refundAmount, равный сумме возврата, и добавьте корзину предоставляемых товаров и услуг. Сформировать корзину можно одним из способов:

• Способ 1: Указать состояние корзины после возврата.

  Используйте поле targetCart — целевая корзина, которая должна остаться у покупателя после выполнения возврата. Если это поле не указано, то считается, что корзина возвращается полностью.

  Поле targetShipping применимо только к Yandex Pay Checkout. В остальных случаях следует оставить это поле пустым. Если это поле не указано, то считается, что стоимость доставки возвращается полностью.

• Способ 2: Указать возвращаемые товары.

  Используйте поле refundCart — данные о возвращаемых позициях: количество единиц товара для возврата или сумма, на которую нужно уменьшить стоимость конкретного товара. Если поле не указано, возврат осуществляется на всю корзину.

Примеры возвратов

Рассмотрим на примере заказа с orderId = Order-123 и следующей корзиной:

{
  "items": [
    {
      "productId": "id-1",
      "price": "50",
      "title": "Шариковая ручка",
      "quantity": {
        "count": "10"
      }
    },
    {
      "productId": "id-2",
      "price": "200",
      "title": "Блокнот",
      "quantity": {
        "count": "2"
      }
    }
  ]
}

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

http POST https://sandbox.pay.yandex.ru/api/merchant/v2/orders/Order-123/refund \
  "Authorization: Api-Key ${API_KEY}" 'refundAmount:="900.00"'

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

Возврат единиц товара

Допустим, необходимо вернуть две шариковые ручки. Это делается следующим запросом:

http POST https://sandbox.pay.yandex.ru/api/merchant/v2/orders/Order-123/refund \
  "Authorization: Api-Key ${API_KEY}" \
  'targetCart[items][0]:={"productId": "id-1", "quantityCount": "8"}' \
  'targetCart[items][1]:={"productId": "id-2", "quantityCount": "2"}' \
  'refundAmount:="100.00"'

В этом примере:

• Количество шариковых ручек уменьшилось на 2, с 10 до 8 единиц.
• Поле price в запросе пропущено, но его вполне допустимо указать.
• quantityCount у позиции с блокнотом не изменилось, его можно было не указывать.

Возврат части денег

Допустим, необходимо вернуть 30 рублей за каждый из блокнотов. Это достигается путем уменьшения цены позиции.

http POST https://sandbox.pay.yandex.ru/api/merchant/v2/orders/Order-123/refund \
  "Authorization: Api-Key ${API_KEY}" \
  'targetCart[items]:=[{"productId": "id-1"}, {"productId": "id-2", "price": "170"}]' \
  'refundAmount:="60.00"'

В этом примере:

• Цена блокнота уменьшилась на 30 рублей, с 200 до 170 рублей;
• Таким образом, производится возврат 60 рублей, поскольку блокнотов было два.
• quantityCount не указаны, но вполне допустимо указать их прежние значения.

Возврат c указанием количества возвращаемого товара

Допустим, необходимо вернуть две шариковые ручки. Это делается следующим запросом:

http POST https://sandbox.pay.yandex.ru/api/merchant/v2/orders/Order-123/refund \
  "Authorization: Api-Key ${API_KEY}" \
  'refundCart[items][0]:={"productId": "id-1", "quantityCount": "2"}' \
  'refundAmount:="100.00"'

В этом примере:

• Количество шариковых ручек уменьшилось на 2, с 10 до 8 единиц.
• Поле price в запросе пропущено, но его вполне допустимо было указать.

Возврат с указанием, какую часть от стоимости товара необходимо вернуть

Допустим, необходимо вернуть 30 рублей за каждый из блокнотов. Это достигается путем уменьшения цены позиции.

http POST https://sandbox.pay.yandex.ru/api/merchant/v2/orders/Order-123/refund \
  "Authorization: Api-Key ${API_KEY}" \
  'refundCart[items]:=[{"productId": "id-1"}, {"productId": "id-2", "price": "30"}]' \
  'refundAmount:="60.00"'

В этом примере:

• Цена блокнота уменьшилась на 30, с 200 рублей до 170 рублей.
• Таким образом, производится возврат 60 рублей, поскольку блокнотов было два.
• quantityCount не указаны, но вполне допустимо указать их прежние значения.

Ошибки при возврате

Пример

{
  "status": "fail",
  "reasonCode": "ORDERUPDATE_INVALID_ITEM_QUANTITY",
  "reason": "Item with productId=\"123456\" has invalid quantity \"5\". Quantity expected to be between \"0\" and \"4\".",
  "details": {
      "min": "0",
      "max": "4",
      "actual": "5",
      "product_id": "123456",
      "description": "Item with productId=\"123456\" has invalid quantity \"5\". Quantity expected to be between \"0\" and \"4\"."
  }
}

Коды ошибок

Возможные значения reasonCode:

• REFUND_AMOUNT_TOO_LARGE — Сумма возврата refundAmount превышает доступный остаток для возврата.
• REFUND_AMOUNT_EXPECTATION_FAILED — Сумма возврата refundAmount не совпадает с фактической суммой на основе корзины refundCart или targetCart и стоимости доставки targetShipping.
• REFUND_ONLY_ONE_CART_EXPECTATION_FAILED — Одновременно переданы параметры targetCart и refundCart. Используйте только один из них.
• REFUND_NOT_POSITIVE_AMOUNT — Сумма возврата refundAmount должна быть больше нуля.
• REFUND_NOT_POSITIVE_POINTS_AMOUNT — Сумма возврата баллов Плюса должна быть больше нуля. Баллы возвращаются пропорционально сумме возврата, проверьте валидность полей refundAmount, price и quantityCount.
• PARTIAL_REFUND_NOT_ALLOWED — Для текущего заказа частичный возврат не разрешен.
• INVALID_PAYMENT_STATUS — Текущий статус платежа не позволяет выполнить возврат. Смотрите разрешенные статусы в поле reason.
• EXTERNAL_AMOUNT_NOT_ALLOWED — Поле externalAmount недоступно для вашего магазина. Для подключения обратитесь к менеджеру интеграции.
• REFUND_EXTERNAL_AMOUNT_EXCEEDED — Запрошенная сумма externalAmount превышает доступный остаток для возврата.
• ORDER_SHIPPING_MISMATCH — Данные о доставке в запросе не соответствуют исходному заказу (наличие доставки, тип доставки).
• ORDER_CART_EMPTY — Добавьте корзину refundCart или targetCart.
• ORDER_AMOUNT_MISMATCH — Общая сумма заказа не совпадает с суммой корзины и доставки, либо сумма корзины не равна сумме всех позиций.
• ORDER_CART_ITEM_ERROR — Некорректные данные в одной из позиций корзины.
• ORDER_CART_DATA_ERROR — Некорректные данные корзины.
• ORDER_CART_POINTS_ERROR — Невозможно корректно рассчитать сумму баллов Плюса с текущими параметрами. Проверьте валидность полей refundAmount, price и quantityCount.
• CART_DISCOUNTS_NOT_SUPPORTED — Версия корзины не поддерживает скидки. Для подключения обратитесь к менеджеру интеграции.
• SHARED_MERCHANTS_DUPLICATE_ORDERS — У магазинов, связанных по Merchant ID, найдено несколько заказов с одинаковым идентификатором.
• REFUND_AMOUNT_TOO_SMALL — Сумма возврата меньше минимальной. Минимальная сумма возврата — 1 рубль.
• REFUND_LEAVES_LESS_THAN_MINIMAL_AMOUNT — После возврата в заказе останется сумма меньше минимально допустимой. Минимальная сумма остатка — 1 рубль.
• ORDER_NOT_FOUND_ERROR — Заказ с указанным идентификатором не найден.
• ORDERUPDATE_INVALID_ITEM_PRICE_RANGE — Цена позиции вне допустимого диапазона.
• ORDERUPDATE_INVALID_ITEM_PRICE — Некорректная цена позиции price.
• ORDERUPDATE_INVALID_ITEM_QUANTITY — Некорректное количество единиц товара quantityCount.
• ORDERUPDATE_INVALID_ITEM_TOTAL — Некорректная итоговая сумма возврата по позиции total.
• ORDERUPDATE_ITEM_TOTAL_EXPECTED — Не указана итоговая сумма возврата по позиции total.
• ORDERUPDATE_INVALID_ITEM_TOTAL_NON_ZERO — При нулевой цене price или количестве quantityCount итоговая сумма позиции total должна быть равна нулю.
• ORDERUPDATE_INVALID_ITEM_PRICE_WITH_QUANTITY — Некорректное сочетание цены price и количества quantityCount для возврата.
• ORDERUPDATE_INVALID_SHIPPING_PRICE — Стоимость доставки вне допустимого диапазона.
• ORDERUPDATE_DUPLIATE_ITEM_PRODUCT_ID — В корзине несколько позиций с одинаковым productId.
• ORDERUPDATE_UNKNOWN_ITEM_PRODUCT_ID — Товар с указанным productId отсутствует в исходной корзине заказа.
• ORDERUPDATE_UNABLE_TO_BALANCE_SEMIVALID_CART — Не удалось пересчитать корзину с частичной валидацией после применения возврата.

Request

https://pay.yandex.ru/api/merchant/v2/orders/{order_id}/refund

https://sandbox.pay.yandex.ru/api/merchant/v2/orders/{order_id}/refund

Path parameters

{
  "branchId": "example",
  "externalOperationId": "example",
  "managerId": "example",
  "extensions": null,
  "motive": "example",
  "refundAmount": "123.45",
  "refundCart": {
    "items": [
      {
        "price": "123.45",
        "productId": "example",
        "quantityCount": "123.45"
      }
    ]
  },
  "refundExternalAmount": "123.45",
  "targetCart": null,
  "targetShipping": {
    "amount": "123.45"
  }
}

{
  "items": [
    {
      "price": "123.45",
      "productId": "example",
      "quantityCount": "123.45"
    }
  ]
}

{
  "items": [
    {
      "price": "123.45",
      "productId": "example",
      "quantityCount": "123.45"
    }
  ]
}

{
  "amount": "123.45"
}

{
  "branchId": "null",
  "managerId": "null",
  "ksoId": "null",
  "externalClientId": "null",
  "externalOperationId": "null",
  "externalOperationTime": "null"
}

{
  "branchId": "null",
  "managerId": "null",
  "ksoId": "null",
  "externalClientId": "null",
  "externalOperationId": "null",
  "externalOperationTime": "null"
}

{
  "billingReport": {
    "branchId": "null",
    "managerId": "null",
    "ksoId": "null",
    "externalClientId": "null",
    "externalOperationId": "null",
    "externalOperationTime": "null"
  }
}

{
  "price": "123.45",
  "productId": "example",
  "quantityCount": "123.45"
}

[
  {
    "price": "123.45",
    "productId": "example",
    "quantityCount": "123.45"
  }
]

{
  "items": [
    {
      "price": "123.45",
      "productId": "example",
      "quantityCount": "123.45"
    }
  ]
}

{
  "amount": "123.45"
}

Responses

{
  "code": 200,
  "data": {
    "operation": {
      "amount": "123.45",
      "created": "2025-01-01T00:00:00Z",
      "externalOperationId": "example",
      "operationId": "123e4567-e89b-12d3-a456-426614174000",
      "operationType": "AUTHORIZE",
      "orderId": "example",
      "params": {},
      "pointsAmount": "123.45",
      "reason": "example",
      "status": "PENDING",
      "updated": "2025-01-01T00:00:00Z"
    }
  },
  "status": "success"
}

{
  "operation": {
    "amount": "123.45",
    "created": "2025-01-01T00:00:00Z",
    "externalOperationId": "example",
    "operationId": "123e4567-e89b-12d3-a456-426614174000",
    "operationType": "AUTHORIZE",
    "orderId": "example",
    "params": {},
    "pointsAmount": "123.45",
    "reason": "example",
    "status": "PENDING",
    "updated": "2025-01-01T00:00:00Z"
  }
}

{
  "params": {
    "motive": "Товар не устроил", // причина возврата
    "branch_id": "42", // идентификатор точки продаж
    "manager_id": "12345" // идентификатор менеджера
  }
}

{
  "params": {
    "cancel_reason": "Покупатель отказался" // причина отмены
  }
}

{}

{
  "amount": "123.45",
  "created": "2025-01-01T00:00:00Z",
  "externalOperationId": "example",
  "operationId": "123e4567-e89b-12d3-a456-426614174000",
  "operationType": "AUTHORIZE",
  "orderId": "example",
  "params": {},
  "pointsAmount": "123.45",
  "reason": "example",
  "status": "PENDING",
  "updated": "2025-01-01T00:00:00Z"
}

{
  "amount": "123.45",
  "created": "2025-01-01T00:00:00Z",
  "externalOperationId": "example",
  "operationId": "123e4567-e89b-12d3-a456-426614174000",
  "operationType": "AUTHORIZE",
  "orderId": "example",
  "params": {},
  "pointsAmount": "123.45",
  "reason": "example",
  "status": "PENDING",
  "updated": "2025-01-01T00:00:00Z"
}

{
  "operation": {
    "amount": "123.45",
    "created": "2025-01-01T00:00:00Z",
    "externalOperationId": "example",
    "operationId": "123e4567-e89b-12d3-a456-426614174000",
    "operationType": "AUTHORIZE",
    "orderId": "example",
    "params": {},
    "pointsAmount": "123.45",
    "reason": "example",
    "status": "PENDING",
    "updated": "2025-01-01T00:00:00Z"
  }
}