/v2/orders/{order_id}/refund

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

Доступно только для платежей в статусе CAPTURED и PARTIALLY_REFUNDED. В случае успешного выполнения запроса изменится статус платежа:

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

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

Узнать результат возврата можно через механизм событий или вызов метода состояния операции. Событие OPERATION_STATUS_UPDATED будет отправлено как в случае успеха, так и при возникновении ошибки в процессе совершения возврата.

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

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

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

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

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

  Примечание

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

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

Рассмотрим на примере заказа с 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 не указаны, но вполне допустимо указать их прежние значения.

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": "string",
    "externalOperationId": "string",
    "managerId": "string",
    "motive": "string",
    "refundAmount": "123.45",
    "refundCart": {
        "items": [
            {
                "price": "123.45",
                "productId": "string",
                "quantityCount": "123.45"
            }
        ]
    },
    "targetCart": {
        "items": [
            {
                "price": "123.45",
                "productId": "string",
                "quantityCount": "123.45"
            }
        ]
    },
    "targetShipping": {
        "amount": "123.45"
    }
}

Responses

{
    "code": 200,
    "data": {
        "operation": {
            "amount": "123.45",
            "created": "2022-12-29T18:02:01Z",
            "externalOperationId": "string",
            "operationId": "c3073b9d-edd0-49f2-a28d-b7ded8ff9a8b",
            "operationType": "AUTHORIZE",
            "orderId": "string",
            "params": {},
            "pointsAmount": "123.45",
            "reason": "string",
            "status": "PENDING",
            "updated": "2022-12-29T18:02:01Z"
        }
    },
    "status": "success"
}