API ЮKassa
Помощь
Подключить ЮKassa
Метод listReturns
Описание
Получение выборки из истории выполнения операций возврата успешных переводов.
Формат запроса
Адрес для вызова операции
https://shop.yookassa.ru/webservice/mws/api/listReturns
Параметры запроса
ПараметрТипОписание
requestDTdateTimeДата и время запроса по часам магазина. Обязательный параметр.
shopIdlongИдентификатор магазина, который ЮKassa выдала при подключении.
invoiceIdУникальный номер транзакции в ЮKassa.
fromdateTime
Время выборки «от» в формате YYYY-MM-DDThh:mm:ss.fZZZZZ (см. Типы данных)
Обязательно передавать дробную часть секунд, от 1 до 6 символов. Например: 2011-07-01T19:00:00.000+04:00
tilldateTime
Время выборки «до» в формате YYYY-MM-DDThh:mm:ss.fZZZZZ (см. Типы данных)
Обязательно передавать дробную часть секунд, от 1 до 6 символов. Например: 2011-07-01T19:00:00.000+04:00
statusintСтатус операции. Необязательный параметр.
partialboolean
Необязательный параметр. Возможные значения:
  • true — будут выведены операции, где возвращается только часть суммы перевода;
  • false — будут выведены операции, где возвращается полная сумма перевода;
  • параметр отсутствует — будут выведены все операции.
Значение по умолчанию: отсутствует.
outputFormatnormalizedStringФормат представления результата, допустимые значения — XML или CSV. Значение по умолчанию: XML.
csvDelimiterstring,
1 символ
Разделитель значений для формата CSV. Не может быть равен символу «"» (кавычка). Необязательный параметр: если отсутствует в запросе, используется разделитель «;» (точка с запятой, без кавычек).
Особенности
Параметры запроса from и till применяются к полю createdDT (время регистрации запроса на возврат по часам ЮKassa).
В параметрах запроса обязательно должно быть хотя бы одно из условий:
  • номер транзакции (invoiceId) и идентификатор магазина (shopId);
  • диапазон времени регистрации запроса на возврат по часам ЮKassa (from и till) и идентификатор магазина (shopId).
Формат ответа
Формат ответа определяется входными параметрами запроса outputFormat и csvDelimiter. В случае ошибки ее код и описание возвращаются в заказанном формате представления результата.
ПараметрТипОписание
returnIdlongУникальный идентификатор операции возврата в ЮKassa.
invoiceIdlongНомер транзакции перевода.
shopIdlongИдентификатор магазина, который выдала ЮKassa.
amountCurrencyAmountСумма возврата.
currencyCurrencyCodeКод валюты.
causestring,
до 255 символов
Описание причины возврата.
statusintКод состояния запроса.
errorintКод ошибки.
createdDTdateTimeВремя регистрации запроса на возврат.
processedDTdateTimeФактическое время возврата средств плательщику. Поле присутствует только в случае успешного возврата.
senderstringОтправитель приказа на возврат. Параметр содержит поле CN X509 сертификата, которым был подписан запрос на возврат (returnPayment).
articleAmountCurrencyAmountСумма возврата в валюте товара.
articleCurrencyCurrencyCodeКод валюты товара.
orderNumberstring,
до 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
Пример сообщения об ошибке в формате 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
Что почитать еще
Коды состояний запросаКоды ошибокКоды состояний уведомления о переводеТипы данных