Refunding payments to customers
If the customer and seller want to cancel the deal, you can return the payment to the customer. No commission is charged for processing refunds.
Only payments with the 
succeeded
status can be returned. A payment within a deal can only be returned either before the payout is made or before the deal is closed. The refund scenario depends on when the remuneration is credited to you (
fee_moment
in the deal):
Refund if marketplace’s remuneration is credited after the payment
If you set your remuneration to be credited after the successful payment (
fee_moment=payment_succeeded
) when creating the deal, you’ll only be able to refund the customer with the amount that was supposed to be paid out to the seller. The amount can be refunded in full or in parts. There can be multiple partial refunds.
Full refund
To return seller’s remuneration in full, specify the unique payment ID in the 
payment_id
parameter and the full amount of seller's remuneration in the amount and
deal
objects in the request for creating a refund .
The amount in the 
deal
object must match the corresponding value in the 
amount
object.
Example of a request for a full refund of seller’s remuneration
cURL
PHP
Python
curl https://api.yookassa.ru/v3/refunds \
    -X POST \
    -u <Shop ID>:<Secret Key> \
    -H 'Idempotence-Key: <Idempotence Key>' \
    -H 'Content-Type: application/json' \
    -d '{
          "amount": {
            "value": "800.00",
            "currency": "RUB"
          },
          "deal": {
            "refund_settlements": [
              {
                "type": "payout",
                "amount": {
                  "value": "800.00",
                  "currency": "RUB"
                }
              }
            ]
          },
          "payment_id": "2855940e-000f-5000-9000-1ef78d597562",
          "description": "Refund for order No. 37"
        }'
YooMoney will return a created refund object  in response to the request. It’ll also contain the ID of the deal within which the payment was refunded.
Example of the response body
JSON
{
    "id": "28618525-0015-5000-9000-1e336d42672e",
    "status": "succeeded",
    "amount": {
        "value": "800.00",
        "currency": "RUB"
    },
    "created_at": "2021-06-21T16:48:36.804Z",
    "deal": {
        "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
        "refund_settlements": [{
            "type": "payout",
            "amount": {
                "value": "800.00",
                "currency": "RUB"
            }
        }]
    },
    "description": "Refund for order No. 37",
    "payment_id": "2855940e-000f-5000-9000-1ef78d597562"
}
YooMoney will return the full amount meant for the seller to the customer and close the deal. Deal’s balance will go down to zero after the refund.
Partial refund
To refund a part of seller’s remuneration, specify the unique payment ID in the 
payment_id
parameter and the part of seller’s remuneration that you’d like to return in the 
amount
and
deal
objects in the request for creating a refund .
Important:
  • The amount in the 
    deal
    object must match the corresponding value in the 
    amount
    object.
  • After the refund, the amount remaining on deal’s balance must be enough to pay out seller’s remuneration, otherwise, it won’t be possible to make the payout. Learn more about payout limits
Example of a request for a partial refund of seller’s remuneration
cURL
PHP
Python
curl https://api.yookassa.ru/v3/refunds \
    -X POST \
    -u <Shop ID>:<Secret Key> \
    -H 'Idempotence-Key: <Idempotence Key>' \
    -H 'Content-Type: application/json' \
    -d '{
          "amount": {
            "value": "200.00",
            "currency": "RUB"
          },
          "deal": {
            "refund_settlements": [
              {
                "type": "payout",
                "amount": {
                  "value": "200.00",
                  "currency": "RUB"
                }
              }
            ]
          },
          "payment_id": "2855940e-000f-5000-9000-1ef78d597562",
          "description": "Refund for order No. 37"
        }'
YooMoney will return a created refund object  in response to the request.
Example of the response body
JSON
{
    "id": "28618525-0015-5000-9000-1e336d42672e",
    "status": "succeeded",
    "amount": {
        "value": "200.00",
        "currency": "RUB"
    },
    "created_at": "2021-06-21T16:48:36.804Z",
    "deal": {
        "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
        "refund_settlements": [{
            "type": "payout",
            "amount": {
                "value": "200.00",
                "currency": "RUB"
            }
        }]
    },
    "description": "Refund for order No. 37",
    "payment_id": "2855940e-000f-5000-9000-1ef78d597562"
}
YooMoney will return the specified part of the payment to the customer and deduct the refund amount from deal’s balance and seller’s payout amount.
Refund if marketplace’s remuneration is credited after the deal is closed
If you’re going to receive the remuneration after the deal is closed (
fee_moment=deal_closed
), you’ll be able to return the full payment amount to the customer, including your remuneration. You can refund the whole amount or a part of it. There can be multiple partial refunds.
YooMoney’s commission can’t be refunded. If you’d like to refund the payment amount in full, YooMoney will refund the acquiring commission from your store’s balance. In this case, deal’s balance in the 
deal
object can become negative. If there’s not enough money for refunding the amount of YooMoney’s commission on the balance of marketplace’s store, the payment can’t be returned.
Full refund
To refund the whole payment amount, specify the unique payment ID in the 
payment_id
parameter and the amount of the payment to be returned in the 
amount
object in the request for creating a refund .
If you use the YooMoney solution for 54-FZ, the request for creating a refund must be sent without the 
receipt
object. To create a refund receipt for your remuneration, send a separate request to YooMoney.
Example of a request for a full refund of a payment
cURL
PHP
Python
curl https://api.yookassa.ru/v3/refunds \
    -X POST \
    -u <Shop ID>:<Secret Key> \
    -H 'Idempotence-Key: <Idempotence Key>' \
    -H 'Content-Type: application/json' \
    -d '{
          "amount": {
            "value": "1000.00",
            "currency": "RUB"
          },
          "payment_id": "2855940e-000f-5000-9000-1ef78d597562",
          "description": "Refund for order No. 37"
        }'
YooMoney will return a created refund object  in response to the request.
Example of a refund object
JSON
{
    "id": "28618906-0015-5000-a000-1555d6d94c48",
    "status": "succeeded",
    "amount": {
        "value": "1000.00",
        "currency": "RUB"
    },
    "created_at": "2021-06-21T17:05:10.506Z",
    "deal": {
        "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
        "refund_settlements": [{
            "type": "payout",
            "amount": {
                "value": "800.00",
                "currency": "RUB"
            }
        }]
    },
    "description": "Refund for order No. 37",
    "payment_id": "2855940e-000f-5000-9000-1ef78d597562"
}
If the refund was processed successfully, YooMoney will return the full payment amount to the customer, including the acquiring commission (YooMoney will debit it from your store’s balance, and deal’s balance will become negative). After that, YooMoney will close the deal.
Example of a deal object after a full refund of a payment
JSON
{
  "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
  "status": "closed",
  "balance": {
    "value": "-45.00",
    "currency": "RUB"
  },
  "payout_balance":{
     "value":"0.00",
     "currency":"RUB"
  },
  "created_at": "2021-06-18T07:28:39.390497Z",
  "type": "safe_deal",
  "fee_moment": "deal_closed",
  "metadata": {
    "order_id": "37"
  }
  "description":"SAFE_DEAL 123554642-2432FF344R"
}
Refund of a part of the amount
To refund only a part of the payment amount, specify the following information in the request for creating a refund : the unique payment ID in the 
payment_id
parameter, the part of the total amount that you’d like to return in the 
amount
object, and the information about how much seller’s remuneration should be decreased in the 
deal
object.
Important:
  • After the refund, the amount remaining on deal’s balance must be enough to pay out seller’s remuneration, otherwise, it won’t be possible to make the payout. Learn more about payout limits
  • If you use the YooMoney solution for 54-FZ, the request for creating a refund must be sent without the 
    receipt
    object. To create a refund receipt for your remuneration, send a separate request to YooMoney.
Example of a request for a partial refund of seller’s remuneration
cURL
PHP
Python
curl https://api.yookassa.ru/v3/refunds \
    -X POST \
    -u <Shop ID>:<Secret Key> \
    -H 'Idempotence-Key: <Idempotence Key>' \
    -H 'Content-Type: application/json' \
    -d '{
            "amount": {
              "value": "200.00",
              "currency": "RUB"
            },
            "deal": {
                "refund_settlements": [
                  "type": "payout",
                  "amount": {
                    "value": "160.00",
                    "currency": "RUB"
                   }
                ]
            },
            "payment_id": "2855940e-000f-5000-9000-1ef78d597562",
            "description": "Refund for order No. 37"
        }'
YooMoney will return a created refund object  in response to the request.
Example of the response body
JSON
{
  "id": "27dd7a4f-0015-5000-8000-1e8caf204668",
  "status": "succeeded",
  "amount": {
    "value": "200.00",
    "currency": "RUB"
  },
  "created_at": "2020-02-12T13:03:11.398Z",
  "description": "Refund for order No. 37",
  "deal": {
    "id": "dl-285e5ee7-0022-5000-8000-01516a44b147",
    "refund_settlements": [
        "type": "payout",
        "amount": {
           "value": "160.00",
           "currency": "RUB"
        }
     ]
  },
  "payment_id": "2855940e-000f-5000-9000-1ef78d597562"
}
YooMoney will return the specified part of the payment to the customer and deduct the refund amount from deal’s balance and seller’s payout amount.

Do you have any questions or comments regarding the documentation?

We can set up a call and discuss them: we'll help you solve the problem and you'll help us understand what we need to improve. To do that, share your contact information and select the time.
Yes, I'd like to set up a meeting
See also
Basics of using the APITesting Safe dealSubmitting receipts with Safe dealRefund reports