YooMoney API
Guides
Old versions of the API
Help
Sign up for YooMoney
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).
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 a request for a refund
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. You’re allowed to make an infinite number of partial refunds, as long as:
  • the total amount of all partial refunds does not exceed the payment amount;
  • the amount of the refund is larger than 1 ruble;
  • the remaining amount is larger than 1 ruble.
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 a refund with the 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.
ValueDescription
yoo_moneyYooMoney
refund_networkAny 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.
ValueDescription
insufficient_fundsNot 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
general_declineNo specific reason provided. Contact the support service to learn more.
rejected_by_payeeIssuer of the means of payment declined the refund due to an unknown reason. Prompt the user to contact the issuer for details or offer to return the money directly to the user, not via YooMoney.
yoo_money_account_closedThe 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.
See also