ЮKassa: POST /refunds — Создание возврата

Создает возврат успешного платежа на указанную сумму. Платеж можно вернуть только в течение трех лет с момента его создания. Комиссия ЮKassa за проведение платежа не возвращается.

Документация: https://yookassa.ru/developers/api#create_refund

Параметр	Где	Тип	Обяз.	Описание
`Idempotence-Key`	header	string	да	Ключ идемпотентности. Рекомендуется использовать строку вида UUID v7
`payment_id`	body	string	да	Идентификатор платежа в ЮKassa.
`amount`	body	object	да	Сумма, которую нужно вернуть пользователю. Указывается вместе с кодом валюты. Должна совпадать с валютой субаккаунта (recipient.gateway_id), если вы разделяете потоки платежей, или с валютой аккаунта (shopId в личном кабинете), если не разделяете.
`amount.value`	body	string	да	Сумма в выбранной валюте, всегда в дробном формате. Разделитель дробной части — точка, разделителя тысяч нет. Количество знаков после точки зависит от выбранной валюты. Пример: 1000.00.
`amount.currency`	body	string (RUB, EUR, USD, KZT, BYN, UAH, UZS, TRY)	да	Трехбуквенный код валюты в формате ISO-4217. Пример: RUB.
`description`	body	string	нет	Комментарий к возврату, основание для возврата денег пользователю.
`receipt`	body	object	нет	Данные для формирования чека. Параметр передается, если вы компания или индивидуальный предприниматель и используете Чеки от ЮKassa, либо используете стороннюю онлайн-кассу и отправляете данные для формирования чеков по одному из сценариев: Платеж и чек одновременно или Сначала чек, потом платеж.
`receipt.customer`	body	object	нет	Информация о пользователе. Необходимо указать как минимум контактные данные: для Чеков от ЮKassa — электронную почту (customer.email), в остальных случаях — электронную почту (customer.email) или номер телефона (customer.phone).
`receipt.items`	body	object[]	нет	Список товаров в заказе. Если вы используете Чеки от ЮKassa, можно указать до 80 товаров, если стороннюю онлайн-кассу — до 100 товаров.
`receipt.internet`	body	boolean	нет	Признак проведения платежа в интернете (тег в 54 ФЗ — 1125). Возможные значения: true — оплата прошла онлайн (например, на вашем сайте или в приложении); false — оплата прошла офлайн, при личном взаимодействии (например, в торговой точке или при встрече с курьером). По умолчанию true; если вы принимаете платежи офлайн, передайте false.
`receipt.tax_system_code`	body	integer	нет	Система налогообложения магазина (тег в 54 ФЗ — 1055). Для сторонних онлайн-касс: обязательный параметр, если вы используете онлайн-кассу Атол Онлайн, обновленную до ФФД 1.2, или у вас несколько систем налогообложения, в остальных случаях не передается. Для Чеков от ЮKassa: параметр передавать не нужно, ЮKassa его проигнорирует.
`receipt.timezone`	body	integer	нет	Номер часовой зоны для адреса, по которому вы принимаете платежи (тег в 54 ФЗ — 1011). Указывается, только если в чеке есть товары, которые подлежат обязательной маркировке (в items.mark_code_info передается параметр gs_1m, short или fur). Перечень возможных значений: для Чеков от ЮKassa; для сторонних онлайн-касс.
`receipt.receipt_industry_details`	body	object[]	нет	Отраслевой реквизит чека (тег в 54 ФЗ — 1261). Можно передавать, если используете Чеки от ЮKassa или онлайн-кассу, обновленную до ФФД 1.2.
`receipt.receipt_operational_details`	body	object	нет	Операционный реквизит чека (тег в 54 ФЗ — 1270). Можно передавать, если используете Чеки от ЮKassa или онлайн-кассу, обновленную до ФФД 1.2.
`sources`	body	object[]	нет	Данные о том, с какого магазина и какую сумму нужно удержать для проведения возврата. Необходимо передавать, если вы используете Сплитование платежей. Сейчас в этом параметре можно передать данные только одного магазина.
`deal`	body	object	нет	Данные о сделке, в составе которой проходит возврат. Необходимо передавать, если вы проводите Безопасную сделку.
`deal.refund_settlements`	body	object[]	нет	Данные о распределении денег.
`refund_method_data`	body	object	нет	Данные для возврата платежа по электронному сертификату.
`refund_method_data.type`	body	string (sbp, electronic_certificate)	нет	Код способа оплаты, который использовался при проведении платежа.
`refund_method_data.electronic_certificate`	body	object	нет	Данные от ФЭС НСПК для возврата на электронный сертификат. Неоходимо передавать только при оплате со сбором данных на вашей стороне.
`refund_method_data.articles`	body	object[]	нет	Корзина возврата (в терминах НСПК) — список возвращаемых товаров, для оплаты которых использовался электронный сертификат. Данные должны соответствовать товарам из одобренной корзины покупки (articles в объекте платежа: https://yookassa.ru/developers/api#payment_object). Необходимо передавать только при оплате на готовой странице ЮKassa.
`metadata`	body	object	нет	Любые дополнительные данные, которые нужны вам для работы (например, ваш внутренний идентификатор заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от ЮKassa. Ограничения: не более 16 ключей, не более 32 символов в названии ключа, не более 512 символов в значении ключа, тип данных — строка в формате UTF-8.

Пример запроса:

{
  "payment_id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  }
}

Пример ответа:

{
  "id": "1ddd77af-0bd7-500d-895b-c475c55fdefc",
  "payment_id": "1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "amount": {
    "value": "1000.00",
    "currency": "RUB"
  },
  "status": "succeeded",
  "created_at": "2017-11-03T11:52:31.827Z"
}

Базовые URL

Основной: https://api.yookassa.ru/v3

Авторизация

Тип: Basic Auth

HTTP Basic Auth: имя пользователя — идентификатор магазина (shopId, раздел Настройки — Магазин) или шлюза для выплат (agentId, раздел Настройки выплат), пароль — секретный ключ (раздел Интеграция — Ключи API). Для тестового магазина ключ выпускается автоматически. Участники партнерской программы используют OAuth 2.0 и передают Bearer-токен. Секретный ключ и OAuth-токен нельзя публиковать.

curl https://api.yookassa.ru/v3/payments/{payment_id} \
  -u <Идентификатор магазина>:<Секретный ключ>

Нюансы

capture по умолчанию false: без capture: true платеж останется в статусе waiting_for_capture и в момент expires_at отменится автоматически, деньги вернутся покупателю.
Для POST и DELETE обязателен заголовок Idempotence-Key — до 64 символов, рекомендуется UUID. Повтор с тем же ключом в течение 24 часов вернет результат первого запроса; для новой операции нужен новый ключ.
HTTP 500 не значит, что операция не прошла: результат неизвестен. Повтори запрос с теми же данными и тем же ключом идемпотентности или запроси объект через GET.
Возврат покупателя на return_url не означает успешную оплату — статус проверяй на сервере или по HTTP-уведомлению.
Сумма — строка с точкой и двумя знаками: "1000.00", вместе с кодом валюты.
Методы /webhooks работают только с OAuth-токеном в партнерской программе. Обычный магазин настраивает уведомления в личном кабинете.
Вернуть платеж можно в течение трех лет с момента создания. Комиссия ЮKassa за платеж не возвращается.
Для Чеков от ЮKassa частичная предоплата, аванс и кредит не поддерживаются.

Сценарии с этим методом

Вернуть деньги покупателю

Если этого недостаточно — официальная документация: https://yookassa.ru/developers/api#create_refund Вся интеграция одним документом: https://mcp-everything.ru/integrations/yookassa.md