YooMoney API
Old versions of the API
Help
Sign up for YooMoney
listReturns method

This is an old version of the API. Switch to the YooMoney API.

Description
Getting a selection from the history of operations to refund successful transfers.
Request
Address for calling the operation
https://shop.yookassa.ru/webservice/mws/api/listReturns
Request parameters
ParameterTypeDescription
requestDTdateTimeDate and time of the request according to merchant’s system. Required parameter.
shopIdlongMerchant ID issued by YooMoney during activation.
invoiceId
Unique transaction number in YooMoney.
from
dateTime
Time of the selection “from” in format YYYY-MM-DDThh:mm:ss.fZZZZZ (see Data types)
Must send fractions of second using 1 to 6 characters. For example: 2011-07-01T19:00:00.000+04:00
till
dateTime
Time of the selection “to” in format YYYY-MM-DDThh:mm:ss.fZZZZZ (see Data types)
Must send fractions of second using 1 to 6 characters. For example: 2011-07-01T19:00:00.000+04:00
statusintOperation status. Optional parameter.
partial
boolean
Optional parameter. Possible values:
  • true — selects operations where only part of the transfer amount is refunded;
  • false — selects operations where the full transfer amount is refunded;
  • omitted — selects all operations.
Default values: none.
outputFormatnormalizedStringOutput format. Acceptable values: XML or CSV. Default value: XML.
csvDelimiterstring,
1 character
Value delimiter for CSV format. Must not be the quotation mark character ("). Optional parameter: if omitted in the request, the semicolon (;) separator is used.
Specifics
The from and till request parameters are applied to the createdDT field (the registration time for the refund request, in YooMoney time).
At least one of the following conditions must be in the request parameters:
  • transaction number (invoiceId) and the store ID (shopId);
  • range of time for registering return request according to YooMoney time (from and till) and merchant ID (shopId).
Response
The response format is determined by the outputFormat and csvDelimiter request arguments. If an error occurs, the error code and description are returned in the specified result format.
ParameterTypeDescription
returnIdlongUnique ID of the refund operation in YooMoney.
invoiceIdlongTransaction number.
shopIdlongMerchant ID issued by YooMoney.
amountCurrencyAmountRefund amount.
currencyCurrencyCodeCurrency code.
causestring,
maximum of 255 characters
Description of the reason for return.
statusintRequest status code.
errorintError code.
createdDTdateTimeRegistration time of the refund request.
processedDTdateTimeActual time the funds were refunded to the Payer. This field is present only for a successful refund.
senderstringSender of the request for refund. This parameter contains the CN X509 field of the certificate, which was used to sign the request for refund (returnPayment).
articleAmountCurrencyAmountRefund amount in the product currency.
articleCurrencyCurrencyCodeProduct currency code.
orderNumberstring,
maximum of 64 characters
Order number in the store, unique to this shopId.
Examples
Example of a successful response in XML format
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="buyer refused to accept goods"
            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="buyer refused to accept goods"
            sender="shopName"
            articleAmount="12.00"
            articleCurrency="643"
            orderNumber="12346"
            />
</listReturnsResponse>
Example of a successful response in CSV format
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;"the buyer refused to accept the goods";shopName;10.00;643;12345

124;3;506; 2000000125;6689;12.00;643;2011-07-02T20:38:01.000Z;; "the buyer refused to accept the goods";shopName;12.00;643;12346

If the parameter is omitted, an empty field is passed in CSV format.

Example of error messages in XML format
XML
<listReturnsResponse
         status="3" error="113"
         processedDT="2011-07-02T20:38:01.000Z"/>
Example of error messages in CSV format
status=3;error=113;processedDT=2011-07-02T20:38:01.000Z
See also
Request status codes Error codes Codes of payment notification states Data types