Метод listReturns

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

Описание

Получение выборки из истории выполнения операций возврата успешных переводов.

Формат запроса

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

https://shop.yookassa.ru/webservice/mws/api/listReturns

Параметры запроса

Параметр	Тип	Описание
requestDT	dateTime	Дата и время запроса по часам магазина. Обязательный параметр.
shopId	long	Идентификатор магазина, который ЮKassa выдала при подключении.
invoiceId		Уникальный номер транзакции в ЮKassa.
from	dateTime	Время выборки «от» в формате `YYYY-MM-DDThh:mm:ss.fZZZZZ` (см. Типы данных) Обязательно передавать дробную часть секунд, от 1 до 6 символов. Например: `2011-07-01T19:00:00.000+04:00`
till	dateTime	Время выборки «до» в формате `YYYY-MM-DDThh:mm:ss.fZZZZZ` (см. Типы данных) Обязательно передавать дробную часть секунд, от 1 до 6 символов. Например: `2011-07-01T19:00:00.000+04:00`
status	int	Статус операции. Необязательный параметр.
partial	boolean	Необязательный параметр. Возможные значения: `true` — будут выведены операции, где возвращается только часть суммы перевода; `false` — будут выведены операции, где возвращается полная сумма перевода; параметр отсутствует — будут выведены все операции. Значение по умолчанию: отсутствует.
outputFormat	normalizedString	Формат представления результата, допустимые значения — `XML` или `CSV`. Значение по умолчанию: `XML`.
csvDelimiter	string, 1 символ	Разделитель значений для формата CSV. Не может быть равен символу «"» (кавычка). Необязательный параметр: если отсутствует в запросе, используется разделитель «;» (точка с запятой, без кавычек).

Особенности

Параметры запроса from и till применяются к полю createdDT (время регистрации запроса на возврат по часам ЮKassa).

В параметрах запроса обязательно должно быть хотя бы одно из условий:

номер транзакции (invoiceId) и идентификатор магазина (shopId);
диапазон времени регистрации запроса на возврат по часам ЮKassa (from и till) и идентификатор магазина (shopId).

Формат ответа

Формат ответа определяется входными параметрами запроса outputFormat и csvDelimiter. В случае ошибки ее код и описание возвращаются в заказанном формате представления результата.

Параметр	Тип	Описание
returnId	long	Уникальный идентификатор операции возврата в ЮKassa.
invoiceId	long	Номер транзакции перевода.
shopId	long	Идентификатор магазина, который выдала ЮKassa.
amount	CurrencyAmount	Сумма возврата.
currency	CurrencyCode	Код валюты.
cause	string, до 255 символов	Описание причины возврата.
status	int	Код состояния запроса.
error	int	Код ошибки.
createdDT	dateTime	Время регистрации запроса на возврат.
processedDT	dateTime	Фактическое время возврата средств плательщику. Поле присутствует только в случае успешного возврата.
sender	string	Отправитель приказа на возврат. Параметр содержит поле CN X509 сертификата, которым был подписан запрос на возврат (`returnPayment`).
articleAmount	CurrencyAmount	Сумма возврата в валюте товара.
articleCurrency	CurrencyCode	Код валюты товара.
orderNumber	string, до 64 символов	Уникальный для данного `shopId` номер заказа в магазине.

Примеры

Пример успешного ответа в формате XML

XML

<listReturnsResponse
        status="0" error="0"
        processedDT="2011-07-02T20:38:01.000Z">
    <returnPayment
            returnId="123"
            status="0" error="0"
            invoiceId="2000000123"
            shopId="6689"
            amount="10.00"
            currency="643"
            createdDT="2011-07-02T20:38:01.000Z"
            processedDT="2011-07-02T20:38:01.000Z"
            cause="покупатель отказался принять товар"
            sender="shopName"
            articleAmount="10.00"
            articleCurrency="643"
            orderNumber="12345"
            />
    <returnPayment
            returnId="124"
            status="3" error="506"
            invoiceId="2000000125"
            shopId="6689"
            amount="12.00"
            currency="643"
            createdDT="2011-07-02T20:38:01.000Z"
            cause="покупатель отказался принять товар"
            sender="shopName"
            articleAmount="12.00"
            articleCurrency="643"
            orderNumber="12346"
            />
</listReturnsResponse>

Пример успешного ответа в формате CSV

status=0;error=0;processedDT=2011-07-02T20:38:01.000Z

123;0;0;2000000123;6689;10.00;643;2011-07-02T20:38:01.000Z;2011-07-02T20:38:01.000Z;"покупатель отказался принять товар";shopName;10.00;643;12345

124;3;506; 2000000125;6689;12.00;643;2011-07-02T20:38:01.000Z;; "покупатель отказался принять товар";shopName;12.00;643;12346

В случае отсутствующего параметра в формате CSV передается пустое поле.

Пример сообщения об ошибке в формате XML

XML

<listReturnsResponse
         status="3" error="113"
         processedDT="2011-07-02T20:38:01.000Z"/>

Пример сообщения об ошибке в формате CSV

status=3;error=113;processedDT=2011-07-02T20:38:01.000Z

Что почитать еще

Коды состояний запроса Коды ошибок Коды состояний уведомления о переводе Типы данных