Docs
API ЮKassa
Старые версии API
Помощь
Войти
Подключить ЮKassa
API ЮKassa: Инструкции
API ЮKassa: Справочник
Старые версии API
Помощь
Войти | Подключить ЮKassa
English
Метод returnPayment

Это старая версия API. Переходите на API ЮKassa.

Описание
Возврат успешного перевода на счет плательщика.
Возможность возврата зависит от времени регистрации заказа в ЮKassa (orderCreatedDatetime в уведомлении о проверке заказа):
  • для всех способов оплаты, кроме SberPay: вернуть перевод можно только в течение трех лет с момента регистрации заказа в ЮKassa;
  • для SberPay: сделать возврат можно в течение одного года с момента регистрации заказа;
  • для банковских карт, Mir Pay: по техническим причинам эквайеры могут отказать в возврате перевода, если с момента регистрации заказа прошло больше 15 месяцев.
Возврат в течение суток (до 23:59 МСК), в которые был совершен перевод, считается отменой этого перевода. В этом случае ЮKassa не удерживает комиссию за проведение операции и данные о переводе не попадают в Реестр принятых переводов и акты об оказании услуг.

Для некоторых способов оплаты возвраты с помощью returnPayment невозможны.

Формат запроса
Адрес для вызова операции
https://shop.yookassa.ru/webservice/mws/api/returnPayment
Формат запросов на возврат успешного перевода (returnPayment) отличается от остальных методов. Запросы данного типа необходимо отправлять в виде зашифрованного криптопакета.
Формирование запроса к ЮKassa состоит из следующих шагов:
Шаг 1. Формирование документа-распоряжения на исполнение операции
Документ формируется согласно стандарту XML 1.0 (Fifth Edition). Документ должен быть сформирован в кодировке UTF‑8.
Шаг 2. Формирование криптопакета
Сформированный документ помещается в криптоконтейнер формата PKCS#7. Криптоконтейнер должен содержать АСП (цифровую подпись, аналог собственноручной подписи). Криптоконтейнер не должен содержать цепочки сертификации. Компрессия данных не используется. Шифрование не используется. Криптопакет должен быть закодирован в формате PEM (OpenSSL). Сертификат, который используется при изготовлении криптопакета, должен соответствовать стандарту X.509 Version 3.
Шаг 3. Формирование и передача запроса к ЮKassa
Магазин формирует POST-запрос по протоколу HTTP/1.1 (RFC 2616, RFC 2618). Криптопакет может быть передан одним из двух способов:
  1. криптопакет помещается в тело POST-запроса, MIME тип: application/pkcs7-mime;
  2. криптопакет передается как вложение в сообщение типа multipart/form-data. MIME тип: application/pkcs7-mime. У POST-запроса должна только одна часть — вложение, криптопакет вкладывается как файл. Такой запрос можно отправить из стандартной HTML формы загрузки файла на сервер (см. RFC 2388).
Для авторизации запросов ЮKassa проверяет АСП криптопакета.
Параметры запроса
ПараметрТипОписание
clientOrderId
ClientTransactionNumber
Уникальный идентификатор операции возврата. Обеспечивает защиту от ошибочных повторов операций. Рекомендуемые значения: целое, положительное, линейно нарастающее десятичное число.
Если запрос отправлен с уже обработанным номером операции (clientOrderId) и остальные параметры запроса, кроме requestDT (дата и время запроса по часам магазина), совпадают с предыдущей попыткой, то ЮKassa вернет результат обработки ранее отправленного запроса.
Если запрос отправлен с уже обработанным номером операции (clientOrderId), а остальные параметры имеют отличные от первой попытки значения, то ЮKassa отвергнет такой запрос и вернет в ответе status=3, error=405.
requestDTdateTimeВремя формирования запроса на выполнение операции в системе магазина.
invoiceId
long
Номер транзакции возвращаемого перевода.

Вернуть перевод можно в течение трех лет с момента регистрации заказа (orderCreatedDatetime в уведомлении о проверке заказа).

shopIdlongИдентификатор магазина, который выдала ЮKassa.
amountCurrencyAmountСумма, которую необходимо вернуть на счет плательщика.
currencyCurrencyCodeКод валюты возвращаемого перевода.
causestring,
до 255 символов		Описание причины возврата.
receiptstringДанные для формирования чека. Необязательный параметр: передается, только если магазин настроил работу со своей онлайн-кассой через ЮKassa.
Пример HTTP запроса
POST /webservice/mws/api/returnPayment HTTP/1.1
Content-Type: application/pkcs7-mime
Content-Length: 906

-----BEGIN PKCS7-----
MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAaCA
JIAEgbE8P3htbCB2ZXJzaW9uPSIxLjAiIGVuY29kaW5nPSJVVEYtOCI/Pg0KPG1h
a2VEZXBvc2l0aW9uUmVzcG9uc2UgY2xpZW50T3JkZXJJZD0iMTI5MTExNjIzNDUy
OCIgc3RhdHVzPSIwIiBlcnJvcj0iMCIgcHJvY2Vzc2VkRFQ9IjIwMTAtMTEtMzBU
MTE6MjM6NTQuNjI0WiIgYmFsYW5jZT0iNTQxNDYuNzMiIC8+DQoAAAAAAAAxggF8
MIIBeAIBATB3MGoxCzAJBgNVBAYTAlJVMQ8wDQYDVQQIEwZSdXNzaWExFjAUBgNV
BAcTDVN0LlBldGVyc2J1cmcxITAfBgNVBAoTGEludGVybmV0IFdpZGdpdHMgUHR5
IEx0ZDEPMA0GA1UEAxMGc2VydmVyAgkAy2xbdQckXjIwCQYFKw4DAhoFAKBdMBgG
CSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTEwMTEzMDEx
MjM1NVowIwYJKoZIhvcNAQkEMRYEFEYNh8glwqIXGR/n6oYrApa8DaO5MA0GCSqG
SIb3DQEBAQUABIGAHlgGsYK30RXWBvuQao0V73KIPQEx2hH/9GY6Iag/xlmZ3rBB
kFpszF/O2fB+t84pCHfV15ErZQEkAqIotkEYEgA3hAddEW5+RWUzp+3npHpW5OY7
h3niP5Pj+r0P8EDgHe2j0Zb3dzj2mbwOshZD+FP1IcR8AmiTV3u35C6KAEsAAAAA
AAA=
-----END PKCS7-----
Развернуть
Пример запроса
XML
<returnPaymentRequest
        clientOrderId="12345"
        requestDT="2011-07-02T20:38:00.000Z"
        invoiceId="2000000123"
        shopId="6689"
        amount="10.00"
        currency="643"
        cause="Пользователь отказался принять заказ"
/>
Параметры для чека
Эти параметры нужны (и обязательно передаются), если вы настроили взаимодействие со своей онлайн-кассой через ЮKassa. См. Описание процесса оплаты с отправкой данных для чека
Параметры для чека нужно передавать только в случаях, когда состав чека меняется:
  • при частичном возврате;
  • если платеж, который нужно вернуть, проводился без отправки параметров для чека.
В этом случае в запросе появляется параметр receipt, в котором передаются параметры для чека (по товарам, за которые возвращаются деньги).
Параметры для чека не нужно передавать при полных возвратах (если при платеже уже отправлялись фискальные данные).
ПараметрТипОписание
customerContact
string,
64 символа

Параметр customerContact устарел. Его всё еще можно использовать, но рекомендуется передавать данные в параметре customer.

Телефон или эл. почта покупателя.
Ограничения:
  • номер телефона в формате +79210000000 или адрес электронной почты (проверяется соответствие);
  • следует передавать что-то одно: только адрес почты или только телефон;
  • не следует передавать несколько адресов или телефонов.
Обязательный, если не передан customer
taxSystem
int
Система налогообложения магазина (СНО). Параметр необходим, только если у вас несколько систем налогообложения. В остальных случаях не передается.
Возможные значения — число от 1 до 6:
  • 1 — общая СН;
  • 2 — упрощенная СН (доходы);
  • 3 — упрощенная СН (доходы минус расходы);
  • 4 — единый налог на вмененный доход;
  • 5 — единый сельскохозяйственный налог;
  • 6 — патентная СН.
Важно: товары с разным значением taxSystem необходимо передавать в разных чеках.
Необязательный
customer
Объект
Информация о пользователе.
Обязательный, если не передан customerContact
customer.fullName
string,
не более 256 символов
Для юрлица — название организации, для ИП и физического лица — ФИО. Если у физлица отсутствует ИНН, в этом же параметре передаются паспортные данные.
Необязательный
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, АТОЛ Онлайн.
customer.inn
string
ИНН пользователя (10 или 12 цифр). Если у физического лица отсутствует ИНН, необходимо передать паспортные данные в параметре customer.fullName.
Необязательный
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, АТОЛ Онлайн.
customer.email
string
Электронная почта пользователя для отправки чека.
Обязательный, если не передан phone или customerContact.
customer.phone
string
Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например +79000000000.
Обязательный, если не передан email или customerContact.
items
Объект
Все товары в заказе.
Обязательный
item.quantity
Десятичное число. Максимально возможное значение и максимальное количество знаков после точки зависят от модели вашей онлайн-кассы
Количество товара. Описывает количество товаров в заказе или количество весового товара.
Обязательный
item.price
Объект
Цена товара.
Обязательный
item.price.amount
CurrencyAmount
(десятичное число с точностью до 2 символов после точки)
Цена за единицу товара.
Обязательный
item.price.currency
CurrencyCode
Код валюты: RUB (рубль РФ).
Необязательный
item.tax
int
Ставка НДС. Возможные значения — число от 1 до 10:
  • 1 — без НДС;
  • 2 — ставка НДС 0%;
  • 3 — ставка 10%;
  • 4 — ставка 20%;
  • 5 — расчетная ставка 10/110;
  • 6 — расчетная ставка 20/120;
  • 7 — ставка 5%;
  • 8 — ставка 7%;
  • 9 — расчетная ставка 5/105;
  • 10 — расчетная ставка 7/107.
Обязательный
С 1 января 2025 года вводятся новые ставки НДС 5% и 7% (коды ставок: 7, 8, 9, 10). Новые ставки поддерживают все онлайн-кассы. Если используете Эвотор дополнительно настройте онлайн-кассу по инструкции.
item.text
string,
128 символов
Название товара.
Обязательный
item.paymentSubjectType
string,
128 символов
Признак предмета расчета — категория этого товара для налоговой.
Возможные значения:
  • commodity — товар;
  • excise — подакцизный товар;
  • job — работа;
  • service — услуга;
  • gambling_bet — ставка в азартной игре;
  • gambling_prize — выигрыш в азартной игре;
  • lottery — лотерейный билет;
  • lottery_prize — выигрыш в лотерею;
  • intellectual_activity — результаты интеллектуальной деятельности;
  • payment — платеж;
  • agent_commission — агентское вознаграждение;
  • property_right — имущественные права;
  • non_operating_gain — внереализационный доход;
  • insurance_premium — страховой сбор;
  • sales_tax — торговый сбор;
  • resort_fee — курортный сбор;
  • composite — несколько вариантов;
  • another — другое.
Необязательный
item.paymentMethodType
string,
128 символов
Признак способа расчета — категория способа оплаты для налоговой.
Возможные значения:
  • full_prepayment — полная предоплата;
  • partial_prepayment — частичная предоплата;
  • advance — аванс;
  • full_payment— полный расчет;
  • partial_payment — частичный расчет и кредит;
  • credit — кредит;
  • credit_payment — выплата по кредиту.
Необязательный
item.productCode
string
Код товара — уникальный номер, который присваивается экземпляру товара при маркировке.
Формат: число в шестнадцатеричном представлении с пробелами. Максимальная длина — 32 байта. Пример: 00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00.
Обязательный параметр, если товар нужно маркировать.
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, АТОЛ Онлайн.
item.countryOfOriginCode
string
Код страны происхождения товара по общероссийскому классификатору стран мира (ОК (МК (ИСО 3166) 004-97) 025-2001). Пример: RU.
Необязательный
Онлайн-кассы, которые поддерживают этот параметр: Orange Data.
item.customsDeclarationNumber
string,
от 1 до 32 символов
Номер таможенной декларации.
Необязательный
Онлайн-кассы, которые поддерживают этот параметр: Orange Data.
item.excise
string,
десятичное число с точностью до 2 символов после точки
Сумма акциза товара с учетом копеек.
Необязательный
Онлайн-кассы, которые поддерживают этот параметр: Orange Data.
Пример запроса с параметрами для чека
XML
<returnPaymentRequest clientOrderId="12345"
           requestDT="2011-07-02T20:38:00.000Z"
           invoiceId="2000000123"
           shopId="6689"
           amount="746.47"
           cause="Пользователь отказался принять заказ">
 <receipt taxSystem="">
 <customer email="user@example.com"/>
 <items>
 <item quantity="1.324" tax="3" text="товар А"
          paymentMethodType="full_prepayment"
          paymentSubjectType="commodity">
          <price amount="300.22"/>
 </item>
 <item quantity="2" tax="3" text="товар Б"
         paymentMethodType="full_prepayment"
         paymentSubjectType="commodity">
         <price amount="200.11"/>
 </item>
 </items>
 </receipt>
 </returnPaymentRequest>
Развернуть
Пояснения
Контакты покупателя
  • Чтобы платеж прошел, необходимо передать контактные данные пользователя для отправки чека — синтаксически корректный номер телефона или адрес электронной почты. Эти данные нужно передать в объекте customer или в параметре customerContact.
  • Чек покупателю доставляет ОФД (условия доставки зависят от вашего ОФД). Чеки приходят на мобильные номера российских операторов (они начинаются с +7). На иностранный мобильный номер чек может не дойти.

Параметр customerContact устарел. Его всё еще можно использовать, но рекомендуется передавать данные в объекте customer.

Количество товаров, вес, цена
  • В поле item.price.amount указывается цена за единицу товара, в поле item.quantity — количество. Если в item.price.amount указана цена за один товар, следует передавать количество штук (quantity=2, например, два одинаковых пирога). Если в item.price.amount указана цена за кг, следует передавать вес товара (quantity=1.253, например, пирог весом 1 кг 253 г).
  • Общая сумма в чеке должна совпадать с суммой возврата. То есть если умножить item.price.amount на item.quantity, должно получиться значение, равное amount. Если эти значения не совпадают, чек не сформируется.
  • Общая сумма в чеке после всех расчетов округляется до двух знаков после точки. Иногда точную сумму получить невозможно — только на копейку меньше или на копейку больше. В этом случае следует передавать вариант с суммой на копейку больше.
Пример:
item.quantity = "0.573", item.price.amount = "17.00", amount = "9.75"
0.573*17=9.741, после округления — 9.74
0.574*17=9.758, после округления — 9.76
В этом случае следует передавать item.quantity = "0.574"
Формат ответа
В ответ приходят параметры, общие для всех типов запросов на исполнение финансовых операций. Если в запросе был передан идентификатор перевода, которому больше трех лет, возврат не пройдет, в ответ вернется ошибка (error=616).
Пример ответа
XML
<returnPaymentResponse
         clientOrderId="12345"
         status="0" error="0"
         processedDT="2011-07-02T20:38:01.000Z"
 />
Что почитать еще
Реестры возвращенных переводов Правила обработки запросов Коды ошибок Типы данных
© 2025, ООО НКО «ЮМани»