Split payments: refunds — Payment acceptance via the YooMoney API

Payment refunds

If you use Split payments, you can make a refund for a successful payment from your Merchant Profile or using the YooMoney API.

The store can also refund payments from the Merchant Profile. To learn more about the refunds, set up incoming notifications for the refund.succeeded event.

Making a refund

When you make a full refund using the YooMoney API, the commission that you charged upon payment is refunded at the expense of the stores where the goods and services were purchased. If you want to refund the entire payment and refund the commission back at your own expense, create several partial refunds, a separate one for each store. In each request for a partial refund, send the additional parameter platform_fee_amount with the amount of the commission to be refunded.

If you’re making a refund via your Merchant Profile, the commission you charged during payment will not be refunded.

YooMoney does not send notifications of refunds to stores: you will need to do that independently.

Full refund creation

To make a refund for the entire payment that you’ve accepted from the user, send a refund creation request to YooMoney. Specify the payment ID in the payment_id parameter and the refund amount in amount. The request is sent without the platform_fee_amount object. If you want to refund the commission at your own expense, make several partial refunds, a separate one for each store.

The refund creation request must be sent without the receipt object. To generate a refund receipt, send a separate request to YooMoney.

Example of request for a full 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 '{
        "payment_id": "24e89cb0-000f-5000-9000-1de77fa0d6df",
        "amount": {
           "value": "11000.00",
           "currency": "RUB"
        }
      }'

In response, YooMoney will send you the receipt object in its current status.

Example of response

JSON
{
  "id": "24eca812-0015-5000-9000-188e730d6114",
  "status": "succeeded",
  "amount": {
    "value": "11000.00",
    "currency": "RUB"
  },
  "created_at": "2019-08-19T12:21:38.575Z",
  "payment_id": "24e89cb0-000f-5000-9000-1de77fa0d6df",
  "sources": [
    {
      "account_id": "123",
      "amount": {
        "value": "2000.00",
        "currency": "RUB"
      }
    },
    {
      "account_id": "456",
      "amount": {
        "value": "9000.00",
        "currency": "RUB"
      }
    }
  ]
}

Partial refund creation

If you want to make a partial refund for multiple items from several different stores, you will need to create a separate refund for each store. If the user bought all the returned products in one store, create a single refund.

To make a partial refund, send a refund creation request to YooMoney. Specify the payment ID in the payment_id parameter, the refund amount in amount, and the sources array with data for the refund: store ID, amount to be refunded, and the amount of the commission that was charged from a specific store.

Example of request for a partial 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 '{
        "payment_id": "24e89cb0-000f-5000-9000-1de77fa0d6df",
        "amount": {
          "value": "9000.00",
          "currency": "RUB"
        },
        "sources": [
        {
          "account_id": "456",
          "amount": {
            "value": "9000.00",
            "currency": "RUB"
          },
          "platform_fee_amount": {
            "value": "90.00",
            "currency": "RUB"
          }
        }]     
      }'

In response, YooMoney will send you the receipt object in its current status. The response will contain the additional sources parameter with the distribution of funds: the price and the seller of the product returned by the user as well as the commission amount to be refunded.

Example of response

JSON
{
  "id": "24eca812-0015-5000-9000-188e730d6114",
  "status": "succeeded",
  "amount": {
    "value": "9000.00",
    "currency": "RUB"
  },
  "created_at": "2019-08-19T12:21:38.575Z",
  "payment_id": "24e89cb0-000f-5000-9000-1de77fa0d6df",
  "sources": [
  {
    "account_id": "456",
    "amount": {
       "value": "9000.00",
       "currency": "RUB"
    },
    "platform_fee_amount": {
       "value": "90.00",
       "currency": "RUB"
    }
  }
 ]
}

When processing payments in two stages, you can cancel the payment if its status is waiting_for_capture. In this case, the status will change to canceled, money will be refunded to the user, and YooMoney won’t charge any commission for processing the payment.

If a payment receipt has been generated for the canceled payment, you must generate a refund receipt.