Safe deal: refunding payments to customers — Payment acceptance via the YooMoney API

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):

Remuneration after the successful payment
Remuneration after the deal is closed

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 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": "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.