/v2/orders/{order_id}/refund

Request for refund.

Available only for payments in CAPTURED or PARTIALLY_REFUNDED status. On success, the payment status changes as follows:

• to REFUNDED if the full amount was refunded
• or PARTIALLY_REFUNDED if the cart has some items left after the refund.

The method is asynchronous. You can find out the refund result by using the event mechanism or calling the operation status method. The OPERATION_STATUS_UPDATED event is sent both if the refund succeeds and fails.

If a full refund is required, just pass refundAmount set to the order amount.

For a partial refund, you should additionally pass the final cart of the provided products and services in the request. The final cart is created from the current cart by excluding some items or by revising the quantity/costs of the items that were refunded.

The targetCart field describes the final cart status after the refund. If the field is not specified, it's considered that the cart is refunded in full.

The targetShipping field is only applicable to Yandex Pay Checkout. In other cases, leave the field blank. The field describes the final delivery status after the refund. If the field is not specified or is null, it's considered that the delivery cost is refunded in full.

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

Let's take an example of an order with the orderId = Order-123 and the following cart:

{
    "items": [
        {
            "productId": "id-1",
            "price": "50",
            "title": "Ballpoint pen",
            "quantity": {
                "count": "10"
            },
        },
        {
            "productId": "id-2",
            "price": "200",
            "title": "Notepad",
            "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"'

Примеры частичного возврата

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

Suppose that two ballpoint pens need to be refunded. This is done using the following request

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"'

In this example:

• The quantity of ballpoint pens is decreased by 2, from 10 to 8 units.
• The price field is skipped in the request, but it's quite acceptable to specify it.
• quantityCount of the notepad item remains unchanged, it could have been omitted.

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

Let's say a refund of RUB 30 is requested for each notepad. This is achieved by reducing the item price.

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"'

In this example:

• The notepad price is decreased by 30, from RUB 200 to RUB 170.
• That is, a refund of RUB 60 is made, since there're two notepads.
• The quantityCount fields are missing, but it's quite acceptable to specify their previous values.

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