Refunds — Payment acceptance via the YooMoney API

Refunds

You can use the YooMoney API to refund successful payments. No commission is charged for a refund. YooMoney's commission for processing the payment is not returned after the refund.

Specifics

Refunds via YooMoney can only be made to the means of payment that was used for the payment. For example, if money was debited from card 5555555555554477 during the payment, you can make a refund only to that card.

Payment refunds can be full or partial: you can return either the full amount of an accepted payment or just a part of it (for example, if you'd like to make a refund for one item instead of the whole purchase). Some payment methods don’t support partial refunds.

Before making a payment refund, make sure that:

the payment with the sberbank payment method has been created less than a year ago, and payments with other methods have been created less than three years ago;
the payment has been successfully processed and is now is succeeded status;
the payment method supports the type of refund you need (full, partial).

For bank cards, Mir Pay: acquirers may refuse to refund payments created more than 15 months ago for technical reasons. When making a refund, you'll get an error. In this case, discuss with the user how you return them the money directly.

Full refund

To make a full refund, specify the unique identifier (payment_id) and amount (amount) of the refunded payment in the request for creating a refund .

Example of the refund request

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": "2.00",
          "currency": "RUB"
        },
        "payment_id": "21740069-000f-50be-b000-0486ffbf45b0"
      }'

Example of the response body

JSON
  {
    "id": "216749f7-0016-50be-b000-078d43a63ae4",
    "status": "succeeded",
    "amount": {
      "value": "2.00",
      "currency": "RUB"
    },
    "created_at": "2017-10-04T19:27:51.407Z",
    "payment_id": "21740069-000f-50be-b000-0486ffbf45b0"
  }

Partial refund

Partial refunds are created the same way as the full refunds, except the amount parameter must contain only the part of the accepted amount that you want to return.

Minimum amount of the partial refund is 1 ruble. You can make as many partial refunds as you need, if:

the total amount of all partial refunds does not exceed the total payment amount;
there is at least 1 ruble or 0 rubles left of the payment amount after refunds were made.

This means that if you accepted a payment for 10 rubles, you won't be able to make a refund for 9 rubles 50 kop. In this case, you can refund 9 rubles and then 1 ruble, or make a full refund for the whole purchase at once.

Or you can make several partial refunds: for example, refund 3 rubles and then 5,5 rubles. After that, it'll be possible to make only a partial refund for 1,5 rubles.

Unsuccessful refunds

Something might go wrong during a refund. For example, there might not be enough money for a refund. In this case, the refund will be canceled and its status will be updated correspondingly.

In order for you to have a better understanding of what happened and what you need to do with it, YooMoney will provide a comment to the canceled refund (cancellation_details) in the refund object . The comment will contain information about the initiator and reason for the cancellation. You can use this information to analyze and solve problems, display messages to the customer, or for any other purposes.

Example of the refund with canceled status

JSON
  {
    "id": "216749f7-0016-50be-b000-078d43a63ae4",
    "status": "canceled",
    "amount": {
      "value": "2.00",
      "currency": "RUB"
    },
    "created_at": "2017-10-04T19:27:51.407Z",
    "payment_id": "21740069-000f-50be-b000-0486ffbf45b0",
    "cancellation_details": {
        "party": "yoo_money",
        "reason": "insufficient_funds"
    }
  }

Initiators of the cancellation of the refund

The initiator of the cancellation is returned in the party parameter of the cancellation_details object.

Value	Description
yoo_money	YooMoney
refund_network	Any participant of the refund process except you and YooMoney (for example, the issuer of the bank card)

Reasons why the refund was canceled

The reason for the cancellation is returned in the reason parameter of the cancellation_details object.

Value	Description
For all payment methods
general_decline	No specific reason provided. Contact the support service to learn more.
insufficient_funds	Not enough money for a refund: the amount of payments you received on the day of the refund is less than the refund amount, or you have a debt. What to do in this case
rejected_by_payee	Issuer of the means of payment or other participant of the refund process declined the transaction due to an unknown reason. Refunds via YooMoney is not possible in this case. Prompt the user to contact the issuer (e.g. bank) for details and wait for a response: If the cause of the cancellation has been removed, repeat the refund with a new idempotence key. If the problem persists, make the refund directly to the user, not via YooMoney.
rejected_by_timeout	Technical issues on the side of the initiator of the refund cancellation. Repeat the request with a new idempotence key. If the result does not change, repeat the request at increasing reasonable intervals (for example, you can use the Fibonacci sequence). If more than half an hour has passed and you are still receiving `rejected_by_timeout`, contact the initiator of the refund cancellation for details.
Only for YooMoney wallets
yoo_money_account_closed	The user has closed the YooMoney wallet to which you are trying to return the payment. Refunds via YooMoney is not possible in this case. Discuss with the user how you return them the money directly.
Only for electronic certificates
payment_article_number_not_found	There are products that were paid without the use of electronic certificate: `payment_article_number` value for the authorized shopping cart is missing. Correct the details and submit the request again with a new idempotence key.
payment_basket_id_not_found	The National Payment Card System (NSPK) didn't find an authorized shopping cart for this refund. Correct the details and submit the request again with a new idempotence key.
payment_tru_code_not_found	There are products that were paid without the use of an electronic certificate: `tru_code` value for the authorized shopping cart is missing. Correct the details and submit the request again with a new idempotence key.
some_articles_already_refunded	Some products have already been returned. Correct the details and submit the request again with a new idempotence key.
too_many_refunding_articles	The number of returned items (`quantity`) for one or more products is greater than the quantity specified for the authorized shopping cart. Correct the details and submit the request again with a new idempotence key.