/v1/orders/{order_id}/refund

Request for refund.

Initiating a refund for the order.

Available only for payments in CAPTURED or PARTIALLY_REFUNDED status. On success, the payment status will change to REFUNDED or PARTIALLY_REFUNDED depending on the amount and the ORDER_STATUS_UPDATED event will be sent. The OPERATION_STATUS_UPDATED event is sent both if the refund succeeds and fails.

In the request, pass the final cart of the provided products and services. The final cart is created from the current cart by excluding some items or by revising the costs of the existing items that were refunded. The cart's total must be equal to the total payment amount minus the refund amount.

Request

POST

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

Production

POST

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

Sandbox

Path parameters

Name

Description

order_id*

Type: string

Order ID on the merchant's side that was passed in response to /order/create.

Max length: 2048

Body

application/json

{
    "cart": {
        "cartId": "string",
        "coupons": [
            {
                "description": "string",
                "status": "VALID",
                "value": "string"
            }
        ],
        "discounts": [
            {
                "amount": "123.45",
                "description": "string",
                "discountId": "string"
            }
        ],
        "externalId": "string",
        "items": [
            {
                "description": "string",
                "discountedUnitPrice": "123.45",
                "measurements": {
                    "height": 0,
                    "length": 0,
                    "weight": 0,
                    "width": 0
                },
                "pointsAmount": "123.45",
                "productId": "string",
                "quantity": {
                    "available": "123.45",
                    "count": "123.45",
                    "label": "string"
                },
                "receipt": {
                    "agent": {
                        "agentType": 1,
                        "operation": "string",
                        "paymentsOperator": {
                            "phones": [
                                "string"
                            ]
                        },
                        "phones": [
                            "string"
                        ],
                        "transferOperator": {
                            "address": "string",
                            "inn": "string",
                            "name": "string",
                            "phones": [
                                "string"
                            ]
                        }
                    },
                    "excise": "123.45",
                    "markQuantity": {
                        "denominator": 0,
                        "numerator": 0
                    },
                    "measure": 0,
                    "paymentMethodType": 1,
                    "paymentSubjectType": 1,
                    "productCode": "string",
                    "supplier": {
                        "inn": "string",
                        "name": "string",
                        "phones": [
                            "string"
                        ]
                    },
                    "tax": 1,
                    "title": "string"
                },
                "subtotal": "123.45",
                "title": "string",
                "total": "123.45",
                "type": "PHYSICAL",
                "unitPrice": "123.45"
            }
        ],
        "measurements": {
            "height": 0,
            "length": 0,
            "weight": 0,
            "width": 0
        },
        "total": {
            "amount": "123.45",
            "label": "string",
            "pointsAmount": "123.45"
        }
    },
    "externalOperationId": "string",
    "orderAmount": "123.45",
    "refundAmount": "123.45",
    "shipping": {
        "amount": "123.45",
        "methodType": "DIRECT"
    }
}

Name	Description
orderAmount*	Type: string<double> Total amount of the order. It's equal to `cart.total.amount` + `shipping.amount` Example: `123.45`
refundAmount*	Type: string<double> Amount to be refunded. Example: `123.45`
cart	Type: CartWithRequiredTotalWithoutFinalPrice Final cart
externalOperationId	Type: string Operation ID in the merchant's system Max length: `2048`
shipping	Type: ShippingPrice

CartWithRequiredTotalWithoutFinalPrice

Name	Description
items*	Type: CartItemWithoutFinalPriceCamelCase[]
total*	Type: CartTotal
cartId	Type: string The internal ID of the Yandex Pay cart. The store's backend must use this parameter as the ID of the customer cart and the idempotency key for the `/order/create` request. If the store's backend receives a repeat `/order/create` request, return the existing order ID. The store's backend can create no more than one order (`orderId`) per cart (`cartId`). Max length: `2048`
coupons	Type: Coupon[] Coupons applied to the cart
discounts	Type: Discount[] Discounts applied to the cart
externalId	Type: string Cart ID passed by the merchant Max length: `2048`
measurements	Type: Measurements

ShippingPrice

Name

Description

amount*

Type: string<double>

It shouldn't include more than two decimal digits. For example: 1.12, 5.1, 10, 11.00 .

Example: 123.45

methodType*

Type: string

Enum: DIRECT, PICKUP, COURIER, YANDEX_DELIVERY

CartItemWithoutFinalPriceCamelCase

Name	Description
productId*	Type: string Product ID in the merchant system Make sure that each `productId` in the request parameters is unique. Max length: `2048`
quantity*	Type: ItemQuantity Product quantity in the order
description	Type: string Product description Max length: `2048`
discountedUnitPrice	Type: string<double> Price per product unit with discount per item Example: `123.45`
measurements	Type: Measurements Product dimensions and weight. Required for the `PHYSICAL` product
pointsAmount	Type: string<double> Number of Plus points Example: `123.45`
receipt	Type: ItemReceipt Data for receipt generation
subtotal	Type: string<double> Total price per item without discount Example: `123.45`
title	Type: string Product name Max length: `2048`
total	Type: string<double> Total price per item with item discount Example: `123.45`
type	Type: string Product type. Important for integrating with delivery services Default: `UNSPECIFIED` Enum: `PHYSICAL`, `DIGITAL`, `UNSPECIFIED`
unitPrice	Type: string<double> Total price per product unit without discount Example: `123.45`

CartTotal

Name	Description
amount*	Type: string<double> Cart cost with all discounts Example: `123.45`
label	Type: string Name of measurement units, for example, "kg" or "pcs" Max length: `2048`
pointsAmount	Type: string<double> Number of plus points Example: `123.45`

Coupon

Name	Description
value*	Type: string Coupon code Max length: `2048`
description	Type: string Description For example, "3% discount" Max length: `2048`
status	Type: string Enum: `VALID`, `INVALID`, `EXPIRED`, `null`

Discount

Name	Description
amount*	Type: string<double> Discount amount Example: `123.45`
description*	Type: string Text description Max length: `2048`
discountId*	Type: string Discount ID in the merchant system Max length: `2048`

Measurements

Name	Description
height*	Type: number<float> Height, in meters
length*	Type: number<float> Length, in meters
weight*	Type: number<float> Weight, in kilograms
width*	Type: number<float> Width, in meters

ItemQuantity

Name	Description
count*	Type: string<double> Product quantity in the order Example: `123.45`
available	Type: string<double> Maximum available product quantity Example: `123.45`
label	Type: string Name of measurement units, for example, "kg" or "pcs" Max length: `2048`

ItemReceipt

Name	Description
tax*	Type: integer Value description: Link Enum: `1`, `2`, `3`, `4`, `5`, `6`
agent	Type: Agent
excise	Type: string<double> It shouldn't include more than two decimal digits. For example: 1.12, 5.1, 10, 11.00 . Example: `123.45`
markQuantity	Type: MarkQuantity
measure	Type: integer Value description: Link Enum: `0`, `10`, `11`, `12`, `20`, `21`, `22`, `30`, `31`, `32`, `40`, `41`, `42`, `50`, `51`, `70`, `71`, `72`, `73`, `80`, `81`, `82`, `83`, `255`, `null`
paymentMethodType	Type: integer Value description: Link Enum: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `null`
paymentSubjectType	Type: integer Value description: Link Enum: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `null`
productCode	Type: string<base64> Product code (a base64-encoded array of 1 to 32 bytes)
supplier	Type: Supplier
title	Type: string Max length: `2048`

Agent

Name	Description
agentType*	Type: integer Agent type by taxable object. See values Enum: `1`, `2`, `3`, `4`, `5`, `6`, `7`
operation	Type: string Max length: `2048`
paymentsOperator	Type: PaymentsOperator
phones	Type: string[] Max length: `2048`
transferOperator	Type: TransferOperator

MarkQuantity

Name	Description
denominator*	Type: integer<int32>
numerator*	Type: integer<int32>

Supplier

Name	Description
inn	Type: string Max length: `2048`
name	Type: string Max length: `2048`
phones	Type: string[] Max length: `2048`

PaymentsOperator

Name

Description

phones

Type: string[]

Max length: 2048

TransferOperator

Name	Description
address	Type: string Max length: `2048`
inn	Type: string Max length: `2048`
name	Type: string Max length: `2048`
phones	Type: string[] Max length: `2048`

Responses

200 OK

Body

application/json

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

Name	Description
code	Type: number Default: `200`
data	Type: OperationResponseData
status	Type: string Default: `success` Enum: `success`

OperationResponseData

Name	Description
operation	Type: Operation

Operation

Name	Description
amount*	Type: string<double> Transaction amount in a fiat currency Example: `123.45`
operationId*	Type: string<uuid> Max length: `2048`
operationType*	Type: string Enum: `AUTHORIZE`, `BIND_CARD`, `REFUND`, `CAPTURE`, `VOID`, `RECURRING`, `PREPAYMENT`, `SUBMIT`
orderId*	Type: string Max length: `2048`
created	Type: string<date-time> Date and time when the operation was created (ISO 8601)
externalOperationId	Type: string Operation ID on the merchant side Max length: `2048`
params	Type: object
pointsAmount	Type: string<double> Transaction amount in Plus points Example: `123.45`
reason	Type: string Error cause Max length: `2048`
status	Type: string Default: `PENDING` Enum: `PENDING`, `SUCCESS`, `FAIL`
updated	Type: string<date-time> Date and time when the operation was updated (ISO 8601)

/v1/orders/{order_id}/refund

Request

Path parameters

Body

CartWithRequiredTotalWithoutFinalPrice

ShippingPrice

CartItemWithoutFinalPriceCamelCase

CartTotal

Coupon

Discount

Measurements

ItemQuantity

ItemReceipt

Agent

MarkQuantity

Supplier

PaymentsOperator

TransferOperator

Responses

200 OK

Body

OperationResponseData

Operation

Was the article helpful?