Метод returnPayment

Attention. Это старая версия API. Переходите на API Яндекс.Кассы.

Описание

Возврат успешного перевода на счет плательщика.

Возврат в течение суток (до 23:59 МСК), в которые был совершен перевод, считается отменой этого перевода. В этом случае Яндекс.Касса не удерживает комиссию за проведение операции и данные о переводе не попадают в Реестр принятых переводов и акты об оказании услуг.

Restriction.

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

Адрес для вызова операции returnPayment

https://server:port/webservice/mws/api/returnPayment
Note.

Формат запросов на возврат успешного перевода (returnPayment) отличается от остальных методов. Запросы данного типа необходимо отправлять в виде зашифрованного криптопакета.

Формирование запроса к Яндекс.Кассе состоит из следующих шагов:

  1. Формирование документа-распоряжения на исполнение операции Документ формируется согласно стандарту XML 1.0 (Fifth Edition), опубликованному по адресу: http://www.w3.org/TR/xml. Документ должен быть сформирован в кодировке UTF-8, согласно стандарту: http://www.ietf.org/rfc/rfc2279.txt.
  2. Формирование криптопакета Сформированный документ помещается в криптоконтейнер формата PKCS#7, согласно стандарту http://www.ietf.org/rfc/rfc5652.txt. Криптоконтейнер должен содержать АСП (цифровую подпись, аналог собственноручной подписи). Криптоконтейнер не должен содержать цепочки сертификации. Компрессия данных не используется. Шифрование не используется. Криптопакет должен быть закодирован в формате PEM (OpenSSL). Сертификат, который используется при изготовлении криптопакета, должен соответствовать стандарту X.509 Version 3 (http://www.ietf.org/rfc/rfc2459.txt).
  3. Формирование и передача запроса к Яндекс.Кассе Магазин формирует POST-запрос по протоколу HTTP/1.1 (http://www.ietf.org/rfc/rfc2616.txt, http://www.ietf.org/rfc/rfc2618.txt). Криптопакет может быть передан одним из двух способов:
    1. криптопакет помещается в тело POST-запроса, MIME тип: application/pkcs7-mime;
    2. криптопакет передается как вложение в сообщение типа multipart/form-data. MIME тип: application/pkcs7-mime. У POST-запроса должна только одна часть — вложение, криптопакет вкладывается как файл. Такой запрос можно отправить из стандартной HTML формы загрузки файла на сервер (см. http://www.ietf.org/rfc/rfc2388.txt).

Для авторизации запросов Яндекс.Касса проверяет АСП криптопакета.

Входные параметры

Параметр

Тип

Описание

clientOrderId

ClientTransactionNumber

Уникальный идентификатор операции возврата. Обеспечивает защиту от ошибочных повторов операций. Рекомендуемые значения: целое, положительное, линейно нарастающее десятичное число.

Note.
  • Если запрос отправлен с уже обработанным номером операции (clientOrderId) и остальные параметры запроса, кроме requestDT (дата и время запроса по часам магазина), совпадают с предыдущей попыткой, то Яндекс.Касса вернет результат обработки ранее отправленного запроса.
  • Если запрос отправлен с уже обработанным номером операции (clientOrderId), а остальные параметры имеют отличные от первой попытки значения, то Яндекс.Касса отвергнет такой запрос и вернет в ответе status=3, error=405.

requestDT

dateTime

Время формирования запроса на выполнение операции в системе магазина.

invoiceId

long

Номер транзакции возвращаемого перевода.

shopId

long

Идентификатор магазина, выданный Яндекс.Кассой.

amount

CurrencyAmount

Сумма, которую необходимо вернуть на счет плательщика.

currency

CurrencyCode

Код валюты возвращаемого перевода.

cause

string, до 255 символов

Описание причины возврата.

receipt string Данные для формирования чека. Необязательный параметр: передается, только если магазин настроил работу со своей онлайн-кассой через Яндекс.Кассу.

Параметр

Тип

Описание

clientOrderId

ClientTransactionNumber

Уникальный идентификатор операции возврата. Обеспечивает защиту от ошибочных повторов операций. Рекомендуемые значения: целое, положительное, линейно нарастающее десятичное число.

Note.
  • Если запрос отправлен с уже обработанным номером операции (clientOrderId) и остальные параметры запроса, кроме requestDT (дата и время запроса по часам магазина), совпадают с предыдущей попыткой, то Яндекс.Касса вернет результат обработки ранее отправленного запроса.
  • Если запрос отправлен с уже обработанным номером операции (clientOrderId), а остальные параметры имеют отличные от первой попытки значения, то Яндекс.Касса отвергнет такой запрос и вернет в ответе status=3, error=405.

requestDT

dateTime

Время формирования запроса на выполнение операции в системе магазина.

invoiceId

long

Номер транзакции возвращаемого перевода.

shopId

long

Идентификатор магазина, выданный Яндекс.Кассой.

amount

CurrencyAmount

Сумма, которую необходимо вернуть на счет плательщика.

currency

CurrencyCode

Код валюты возвращаемого перевода.

cause

string, до 255 символов

Описание причины возврата.

receipt string Данные для формирования чека. Необязательный параметр: передается, только если магазин настроил работу со своей онлайн-кассой через Яндекс.Кассу.

Параметры для чека

Эти параметры нужны (и обязательно передаются), если вы настроили взаимодействие со своей онлайн-кассой через Яндекс.Кассу. См. Описание процесса оплаты с отправкой данных для чека

Параметры для чека нужно передавать только в случаях, когда состав чека меняется:

  • при частичном возврате;
  • если платеж, который нужно вернуть, проводился без отправки параметров для чека.

В этом случае в запросе появляется параметр receipt, в котором передаются параметры для чека (по товарам, за которые возвращаются деньги).

Параметры для чека не нужно передавать при полных возвратах (если при платеже уже отправлялись фискальные данные).

Изменения в чеках с 1 июля 2019 года

1 июля 2019 года вступили в силу новые поправки к 54-ФЗ. Теперь в некоторых случаях необходимо передавать в чеке дополнительные данные о пользователе и товаре.

Данные о пользователе

Появилась возможность передать дополнительные данные о пользователе (customer):

  • наименование пользователя (тег 1227) — fullName;
  • ИНН пользователя (тег 1228) — inn.

Онлайн-кассы, которые поддерживают новые параметры: Orange Data, АТОЛ Онлайн.

Attention. Параметр customerContact устарел — его всё еще можно использовать, но передавать номер телефона и электронную почту рекомендуется в объекте customer.
Дополнительные данные о товаре

Для каждого товара (items) можно передать:

  • код товара (тег 1162) — productCode;
  • код страны происхождения товара (тег 1230) — countryOfOriginCode;
  • номер таможенной декларации (тег 1231) — customsDeclarationNumber;
  • акциз товара (тег 1229) — excise.

Онлайн-кассы, которые поддерживают новые параметры: Orange Data, АТОЛ Онлайн (только код товара).

Параметр

Тип

Обязательность Описание

customerContact

string, 64 символа

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

Телефон или эл. почта покупателя.

Ограничения:

  • номер телефона в формате +792100000000 или адрес электронной почты (проверяется соответствие);
  • следует передавать что-то одно: только адрес почты или только телефон;
  • не следует передавать несколько адресов или телефонов.

taxSystem

int

Необязательный

Система налогообложения магазина (СНО). Параметр необходим, только если у вас несколько систем налогообложения. В остальных случаях не передается.

Возможные значения — число от 1 до 6:

1 — общая СН;

2 — упрощенная СН (доходы);

3 — упрощенная СН (доходы минус расходы);

4 — единый налог на вмененный доход;

5 — единый сельскохозяйственный налог;

6 — патентная СН.

Важно: товары с разным значением taxSystem необходимо передавать в разных чеках.

customer

Объект

Необязательный

Информация о пользователе.

customer.fullName

string, не более 256 символов

Необязательный

Для юрлица — название организации, для ИП и физического лица — ФИО. Если у физлица отсутствует ИНН, в этом же параметре передаются паспортные данные.

customer.inn

string

Необязательный

ИНН пользователя (10 или 12 цифр). Если у физического лица отсутствует ИНН, необходимо передать паспортные данные в параметре customer.fullName.

customer.email

string

Обязательный, если не передан phone или customerContact.

Электронная почта пользователя для отправки чека.

customer.phone

string

Обязательный, если не передан email или customerContact.

Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например +79000000000.

items

Объект

Обязательный

Все товары в заказе.

item.quantity

Десятичное число с точностью 3 символа после запятой

Обязательный

Количество товара. Описывает количество товаров в заказе или количество весового товара.

item.price

Объект

Обязательный

item.price.amount

CurrencyAmount (десятичное число с точностью до 2 символов после точки)

Обязательный

Цена за единицу товара.

item.price.currency

CurrencyCode

Необязательный

Код валюты: RUB (рубль РФ).

item.tax

int

Обязательный

Ставка НДС. Возможные значения — число от 1 до 6:

1 — без НДС;

2 — НДС по ставке 0%;

3 — НДС чека по ставке 10%;

4 — НДС чека по ставке 20%;

5 — НДС чека по расчетной ставке 10/110;

6 — НДС чека по расчетной ставке 20/120.

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.

item.countryOfOriginCode string Необязательный

Код страны происхождения товара по общероссийскому классификатору стран мира (OК (MК (ИСО 3166) 004-97) 025-2001). Пример: RU.

item.customsDeclarationNumber string, от 1 до 32 символов Необязательный

Номер таможенной декларации.

item.excise string, десятичное число с точностью до 2 символов после точки Необязательный

Сумма акциза товара с учетом копеек.

Параметр

Тип

Обязательность Описание

customerContact

string, 64 символа

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

Телефон или эл. почта покупателя.

Ограничения:

  • номер телефона в формате +792100000000 или адрес электронной почты (проверяется соответствие);
  • следует передавать что-то одно: только адрес почты или только телефон;
  • не следует передавать несколько адресов или телефонов.

taxSystem

int

Необязательный

Система налогообложения магазина (СНО). Параметр необходим, только если у вас несколько систем налогообложения. В остальных случаях не передается.

Возможные значения — число от 1 до 6:

1 — общая СН;

2 — упрощенная СН (доходы);

3 — упрощенная СН (доходы минус расходы);

4 — единый налог на вмененный доход;

5 — единый сельскохозяйственный налог;

6 — патентная СН.

Важно: товары с разным значением taxSystem необходимо передавать в разных чеках.

customer

Объект

Необязательный

Информация о пользователе.

customer.fullName

string, не более 256 символов

Необязательный

Для юрлица — название организации, для ИП и физического лица — ФИО. Если у физлица отсутствует ИНН, в этом же параметре передаются паспортные данные.

customer.inn

string

Необязательный

ИНН пользователя (10 или 12 цифр). Если у физического лица отсутствует ИНН, необходимо передать паспортные данные в параметре customer.fullName.

customer.email

string

Обязательный, если не передан phone или customerContact.

Электронная почта пользователя для отправки чека.

customer.phone

string

Обязательный, если не передан email или customerContact.

Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например +79000000000.

items

Объект

Обязательный

Все товары в заказе.

item.quantity

Десятичное число с точностью 3 символа после запятой

Обязательный

Количество товара. Описывает количество товаров в заказе или количество весового товара.

item.price

Объект

Обязательный

item.price.amount

CurrencyAmount (десятичное число с точностью до 2 символов после точки)

Обязательный

Цена за единицу товара.

item.price.currency

CurrencyCode

Необязательный

Код валюты: RUB (рубль РФ).

item.tax

int

Обязательный

Ставка НДС. Возможные значения — число от 1 до 6:

1 — без НДС;

2 — НДС по ставке 0%;

3 — НДС чека по ставке 10%;

4 — НДС чека по ставке 20%;

5 — НДС чека по расчетной ставке 10/110;

6 — НДС чека по расчетной ставке 20/120.

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.

item.countryOfOriginCode string Необязательный

Код страны происхождения товара по общероссийскому классификатору стран мира (OК (MК (ИСО 3166) 004-97) 025-2001). Пример: RU.

item.customsDeclarationNumber string, от 1 до 32 символов Необязательный

Номер таможенной декларации.

item.excise string, десятичное число с точностью до 2 символов после точки Необязательный

Сумма акциза товара с учетом копеек.

Пояснения

Контакты покупателя

  • Чтобы платеж прошел, неоходимо передать контактные данные пользователя для отправки чека — синтаксически корректный номер телефона или адрес электронной почты. Эти данные нужно передать в объекте customer или в параметре customerContact.
    Attention. Параметр customerContact устарел. Его всё еще можно использовать, но рекомендуется передавать данные в объекте customer.
  • Чек покупателю доставляет ОФД (условия доставки зависят от вашего ОФД). Чеки приходят на мобильные номера российских операторов (они начинаются с +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"

Выходные параметры

В ответ приходят параметры, общие для всех типов запросов на исполнение финансовых операций.

Примеры

Пример 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-----
Пример запроса
<returnPaymentRequest
        clientOrderId="12345"
        requestDT="2011-07-02T20:38:00.000Z"
        invoiceId="2000000123"
        shopId="6689"
        amount="10.00"
        currency="643"
        cause="Пользователь отказался принять заказ"
        />
Пример запроса с параметрами для чека
<returnPaymentRequest clientOrderId="12345"
           requestDT="2011-07-02T20:38:00.000Z"
           invoiceId="2000000123"
           shopId="6689"
           amount="746.47"
           cause="Пользователь отказался принять заказ">
 <receipt taxSystem="">
 <customer email="johndoe@yandex.ru"/>
 <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>
Пример ответа
<returnPaymentResponse
         clientOrderId="12345"
         status="0" error="0"
         processedDT="2011-07-02T20:38:01.000Z"
         />

Смотрите также

Реестры возвращенных переводов

Правила обработки запросов

Коды ошибок

Типы данных