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

|

Подключить ЮKassa
English
Метод returnPayment
Описание
Возврат успешного перевода на счет плательщика. Вернуть перевод можно только в течение трех лет с момента регистрации заказа в ЮKassa (orderCreatedDatetime в уведомлении о проверке заказа). Для перевода со способом оплаты SB (SberPay) сделать возврат можно только в течение одного года с момента регистрации заказа.
Возврат в течение суток (до 23:59 МСК), в которые был совершен перевод, считается отменой этого перевода. В этом случае ЮKassa не удерживает комиссию за проведение операции и данные о переводе не попадают в Реестр принятых переводов и акты об оказании услуг.
Формат запроса
Адрес для вызова операции
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 проверяет АСП криптопакета.
Параметры запроса
ПараметрТипОписание
clientOrderIdClientTransactionNumber
Уникальный идентификатор операции возврата. Обеспечивает защиту от ошибочных повторов операций. Рекомендуемые значения: целое, положительное, линейно нарастающее десятичное число.
Если запрос отправлен с уже обработанным номером операции (clientOrderId) и остальные параметры запроса, кроме requestDT (дата и время запроса по часам магазина), совпадают с предыдущей попыткой, то ЮKassa вернет результат обработки ранее отправленного запроса.
Если запрос отправлен с уже обработанным номером операции (clientOrderId), а остальные параметры имеют отличные от первой попытки значения, то ЮKassa отвергнет такой запрос и вернет в ответе status=3, error=405.
requestDTdateTimeВремя формирования запроса на выполнение операции в системе магазина.
invoiceIdlong
Номер транзакции возвращаемого перевода.
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, в котором передаются параметры для чека (по товарам, за которые возвращаются деньги).
Параметры для чека не нужно передавать при полных возвратах (если при платеже уже отправлялись фискальные данные).
ПараметрТипОписание
customerContactstring,
64 символа
Телефон или эл. почта покупателя.
Ограничения:
  • номер телефона в формате +79210000000 или адрес электронной почты (проверяется соответствие);
  • следует передавать что-то одно: только адрес почты или только телефон;
  • не следует передавать несколько адресов или телефонов.
Обязательный, если не передан customer
taxSystemint
Система налогообложения магазина (СНО). Параметр необходим, только если у вас несколько систем налогообложения. В остальных случаях не передается.
Возможные значения — число от 1 до 6:
  • 1 — общая СН;
  • 2 — упрощенная СН (доходы);
  • 3 — упрощенная СН (доходы минус расходы);
  • 4 — единый налог на вмененный доход;
  • 5 — единый сельскохозяйственный налог;
  • 6 — патентная СН.
Важно: товары с разным значением taxSystem необходимо передавать в разных чеках.
Необязательный
customerОбъект
Информация о пользователе.
Обязательный, если не передан customerContact
customer.fullNamestring,
не более 256 символов
Для юрлица — название организации, для ИП и физического лица — ФИО. Если у физлица отсутствует ИНН, в этом же параметре передаются паспортные данные.
Необязательный
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, АТОЛ Онлайн.
customer.innstring
ИНН пользователя (10 или 12 цифр). Если у физического лица отсутствует ИНН, необходимо передать паспортные данные в параметре customer.fullName.
Необязательный
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, АТОЛ Онлайн.
customer.emailstring
Электронная почта пользователя для отправки чека.
Обязательный, если не передан phone или customerContact.
customer.phonestring
Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например +79000000000.
Обязательный, если не передан email или customerContact.
itemsОбъект
Все товары в заказе.
Обязательный
item.quantityДесятичное число. Максимально возможное значение и максимальное количество знаков после точки зависят от модели вашей онлайн-кассы
Количество товара. Описывает количество товаров в заказе или количество весового товара.
Обязательный
item.priceОбъект
Цена товара.
Обязательный
item.price.amountCurrencyAmount
(десятичное число с точностью до 2 символов после точки)
Цена за единицу товара.
Обязательный
item.price.currencyCurrencyCode
Код валюты: RUB (рубль РФ).
Необязательный
item.taxint
Ставка НДС. Возможные значения — число от 1 до 6:
  • 1 — без НДС;
  • 2 — ставка НДС 0%;
  • 3 — ставка 10%;
  • 4 — ставка 20%;
  • 5 — расчетная ставка 10/110;
  • 6 — расчетная ставка 20/120.
Обязательный
item.textstring, 128 символов
Название товара.
Обязательный
item.paymentSubjectTypestring,
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.paymentMethodTypestring,
128 символов
Признак способа расчета — категория способа оплаты для налоговой.
Возможные значения:
  • full_prepayment — полная предоплата;
  • partial_prepayment — частичная предоплата;
  • advance — аванс;
  • full_payment— полный расчет;
  • partial_payment — частичный расчет и кредит;
  • credit — кредит;
  • credit_payment — выплата по кредиту.
Необязательный
item.productCodestring
Код товара — уникальный номер, который присваивается экземпляру товара при маркировке.
Формат: число в шестнадцатеричном представлении с пробелами. Максимальная длина — 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.countryOfOriginCodestring
Код страны происхождения товара по общероссийскому классификатору стран мира (ОК (МК (ИСО 3166) 004-97) 025-2001). Пример: RU.
Необязательный
Онлайн-кассы, которые поддерживают этот параметр: Orange Data.
item.customsDeclarationNumberstring,
от 1 до 32 символов
Номер таможенной декларации.
Необязательный
Онлайн-кассы, которые поддерживают этот параметр: Orange Data.
item.excisestring,
десятичное число с точностью до 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). На иностранный мобильный номер чек может не дойти.
Количество товаров, вес, цена
  • В поле 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"
 />
Что почитать еще
Реестры возвращенных переводовПравила обработки запросовКоды ошибокТипы данных
© 2023, ООО НКО «ЮМани»