listReturns method — [Archive] Payment solution protocol for merchants

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

Parameter	Type	Description
requestDT	dateTime	Date and time of the request according to merchant’s system. Required parameter.
shopId	long	Merchant 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`
status	int	Operation 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.
outputFormat	normalizedString	Output format. Acceptable values: `XML` or `CSV`. Default value: `XML`.
csvDelimiter	string, 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.

Parameter	Type	Description
returnId	long	Unique ID of the refund operation in YooMoney.
invoiceId	long	Transaction number.
shopId	long	Merchant ID issued by YooMoney.
amount	CurrencyAmount	Refund amount.
currency	CurrencyCode	Currency code.
cause	string, maximum of 255 characters	Description of the reason for return.
status	int	Request status code.
error	int	Error code.
createdDT	dateTime	Registration time of the refund request.
processedDT	dateTime	Actual time the funds were refunded to the Payer. This field is present only for a successful refund.
sender	string	Sender 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`).
articleAmount	CurrencyAmount	Refund amount in the product currency.
articleCurrency	CurrencyCode	Product currency code.
orderNumber	string, 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