Метод 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 Данные для формирования чека. Необязательный параметр: передается, только если магазин настроил работу со своей онлайн-кассой через Яндекс.Кассу.

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

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

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

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

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

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

Параметр

Тип

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

customerContact

string, 64 символа

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

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

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

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

taxSystem

int

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

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

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

1 — общая СН;

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

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

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

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

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

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

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 — НДС чека по ставке 18%;

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

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

text

string, 128 символов

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

Название товара.

Пояснения

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

  • Поле 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"

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

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

Примеры

Пример 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="RUB"
        cause="Пользователь отказался принять заказ"
        />
Пример запроса с параметрами для чека
<returnPaymentRequest clientOrderId="12345"
 requestDT="2011-07-02T20:38:00.000Z"
 invoiceId="2000000123"
 shopId="6689"
 amount="746.47"
 cause="Пользователь отказался принять заказ">
 <receipt customerContact="+79123456543" taxSystem="">
 <items>
 <item quantity="1.324" tax="3" text="товар А">
 <price amount="300.22"/>
 </item>
 <item quantity="2" tax="3" text="товар Б">
 <price amount="200.11"/>
 </item>
 </items>
 </receipt>
 </returnPaymentRequest>
Пример ответа
<returnPaymentResponse
         clientOrderId="12345"
         status="0" error="0"
         processedDT="2011-07-02T20:38:01.000Z"
         />

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

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

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

Коды ошибок

Типы данных