listOrders method — [Archive] Payment solution protocol for merchants

listOrders method

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

Description

Getting a list of orders and their properties.

Request

Address for calling the operation

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

Request parameters

Parameter	Type	Description
requestDT	dateTime	Date and time of the request according to time in the merchant’s system. Required parameter.
outputFormat	normalizedString	Format for the request results. Acceptable values — `XML` or `CSV`. Optional parameter; `XML` by default.
csvDelimiter	string, 1 character	Value delimiter for CSV format. Must not be the quotation mark character ("). Optional parameter: semicolon (;) by default.
shopId	long	ID of the store that the list of orders is being requested for. If this parameter is omitted, orders are returned for the `shopId` that this MWS user has rights to get lists of orders for.
orderCreatedDatetimeGreaterOrEqual	dateTime	Lower bound of the order creation time. Selects orders that were created at the time or later than the time set in this parameter.
orderCreatedDatetimeLessOrEqual	dateTime	Upper bound of the order creation time. Selects orders that were created at the time or earlier than the time set in this parameter.
paid	boolean	If this parameter is set to `true`, only paid orders are returned. If this parameter is set to `false`, only unpaid orders are returned. If this parameter is omitted, both paid and unpaid orders are returned.
paymentDatetimeGreaterOrEqual	dateTime	Lower bound of the order payment time. Selects orders that were paid at the time or later than the time set in this parameter.
paymentDatetimeLessOrEqual	dateTime	Upper bound of the order payment time. Selects orders that were paid at the time or earlier than the time set in this parameter.
invoiceId	long	Unique transaction number in YooMoney.
orderNumber	string, up to 64 characters	Unique order number in the merchant’s system. This parameter can be used if YooMoney gets order numbers from the merchant and stores them.
outputFields	string, up to 4,000 characters	List of order properties that should be output in the request execution results. Names in the list are separated by a semicolon (;). Default value The complete list of order properties is specified in the Response section.

Specifics

At least one of the following conditions must be in the parameters of the request for the list of orders:

transaction number (invoiceId) and the store ID (shopId);
order number (orderNumber) and the store ID (shopId);
time range of order creation (orderCreatedDatetimeGreaterOrEqual and/or orderCreatedDatetimeLessOrEqual);
time range of order payment (paymentDatetimeGreaterOrEqual and/or paymentDatetimeLessOrEqual).

For requests by transaction number (invoiceId) or order number (orderNumber), the request must specify the store ID (shopId).

For requests that restrict the results by the time range of order creation or payment, the following rules apply:

if only one bound is set for the time range of order creation or payment, the default value is taken for the second one. The default value for the upper bound is the current time in the YooMoney service. The default value for the lower bound is the time of the upper bound specified in the request, minus 24 hours;
if the time range for order payment is set, the request must include the paid parameter set to true;
the length of a time range restricting the results must not be longer than 31 days;
the number of records in the results must not exceed 10,000.

Response

Parameter	Type	Description
orderCount	int	Number of orders in the results. Response header field. Present for a successful selection of the list of orders (`listOrders`).
shopId	long	Merchant ID issued by YooMoney during activation.
articleId	long	YooMoney product ID.
shopName	string, maximum of 64 characters	Store name.
articleName	string, maximum of 128 characters	Product name.
invoiceId	long	Unique transaction number in YooMoney.
orderNumber	string, maximum of 64 characters	Order number in merchant’s system. If the YooMoney service gets order numbers from the merchant and stores them, this parameter contains the order number from the merchant’s system. Otherwise, this property contains the YooMoney transaction number.
paymentSystemOrderNumber	string, maximum of 40 characters	YooMoney transfer ID. Shown only for paid orders.
customerNumber	string, maximum of 64 characters	The customer ID from the merchant’s system (sent in the payment form). This could be a unique username, mobile phone number, contract number, and so on, depending on the store.
createdDatetime	dateTime	Time when the order was registered in YooMoney.
paid	boolean	Set to `true` if the order was paid for, otherwise `false`.
paymentDatetime	dateTime	Time of order payment in YooMoney. This value is included in the response only for paid orders.
paymentAuthorizationTime	long	Order number in the YooMoney processing center. This value is included in the response only for paid orders.
payerCode	YMAccount	Payer’s account number. This value is included in the response only for paid orders.
payerAddress	string, maximum of 33 characters	Payer’s IP address, if known. This value is included in the response only for paid orders.
payeeCode	YMAccount	Account number of the transfer recipient when the order was paid. This value is included in the response only for paid orders.
paymentSystemDatetime	dateTime	Time order payment was registered in YooMoney processing center. This value is included in the response only for paid orders.
avisoReceivedDatetime	dateTime	Time order payment was registered in the merchant’s system. Present if the merchant received notification of this payment at the time of request.
avisoStatus	int	Status code for the Payment notification. List of status codes for notifications of payments
avisoRegistryId	long	Number of the report on accepted payments that contains this order. May be omitted in the response.
orderSumAmount	CurrencyAmount	Order amount.
orderSumCurrencyPaycash	CurrencyCode	Currency code for `orderSumAmount`.
orderSumBankPaycash	CurrencyBank	Code of the processing center for `orderSumAmount`.
contractAmount	CurrencyAmount	The amount of the payment in the currency of the payer’s account. May be omitted in the response.
contractCurrency	CurrencyCode	Currency code of the payer’s account. May be omitted in the response.
paidSumAmount	CurrencyAmount	The amount paid by the Payer. This value is included in the response only for paid orders.
paidSumCurrencyPaycash	CurrencyCode	Currency code for `paidSumAmount`. This value is included in the response only for paid orders.
paidSumBankPaycash	CurrencyBank	Code of the processing center for `paidSumAmount`. This value is included in the response only for paid orders.
shopSumAmount	CurrencyAmount	The amount that is credited to the merchant’s account: the order amount, minus the YooMoney commission.
shopSumCurrencyPaycash	CurrencyCode	Currency code for the amount that is credited to the merchant’s account.
shopSumBankPaycash	CurrencyBank	Processing center code for the amount that is credited to the merchant’s account.
receivedSumAmount	CurrencyAmount	The amount that YooMoney receives from the Payer. This value is included in the response only for paid orders.
receivedSumCurrencyPaycash	CurrencyCode	Currency code for `receivedSumAmount`. This value is included in the response only for paid orders.
receivedSumBankPaycash	CurrencyBank	Code of the YooMoney processing center for `receivedSumAmount`. This value is included in the response only for paid orders.
paymentFormParams	string	Payment form parameters. The value is shown in the response only for stores that have the “save payment form parameters” option set.
paymentType	normalizedString	Payment method
agentId	long	YooMoney internal parameter. May be omitted in the response.
uniLabel	string	Unified transaction label in the YooMoney service.
clearing	string	Confirmation status of a payment deferred by the merchant. Possible values: `none` — payment not confirmed; `sale` — payment confirmed; `cancel` — payment canceled. This value is present in the response if the store is set up for deferred payments, and transmitting information about these payments is allowed in the response to `listOrders`.
environment	string	Order status allows for distinguishing real and test operations. Possible values: `Live` — real operation; `Test` — test operation.

If you want to get information about deferred payments in the request for the list of successful payments, contact a YooMoney manager.

Examples

Example of a successful response in XML format

XML
<?xml version="1.0" encoding="utf-8"?>
<listOrdersResponse status="0" error="0"
                    processedDT="2011-08-02T14:50:25.089+03:00"
                    orderCount="2">
    <order shopId="1" articleId="2" invoiceId="2000024720731"
           shopName="Your store"
           articleName="Ushanka"
           orderNumber="14828233603000"
           paymentSystemOrderNumber="483536611593030008"
           customerNumber="800350518"
           createdDatetime="2011-08-02T14:43:30.676+03:00"
           paid="true"
           orderSumAmount="17.28"
           orderSumCurrencyPaycash="643"
           orderSumBankPaycash="1003"
           paidSumAmount="17.28"
           paidSumCurrencyPaycash="643"
           paidSumBankPaycash="1003"
           receivedSumAmount="17.28"
           receivedSumCurrencyPaycash="643"
           receivedSumBankPaycash="1003"
           shopSumAmount="17.28"
           shopSumCurrencyPaycash="643"
           shopSumBankPaycash="1003"
           paymentDatetime="2011-08-02T14:43:31.593+03:00"
           paymentAuthorizationTime="483536611593030008"
           payerCode="41003422841475"
           payerAddress="192.168.1.127"
           payeeCode="41003131475668"
           paymentSystemDatetime="2011-08-02T14:43:31.593+03:00"
           avisoReceivedDatetime="2011-08-02T14:43:31.298+03:00"
           avisoStatus="1000"
           paymentType="AC"
           agentId="200002"
           uniLabel="1cd18622-0004-5000-8000-01d1aac3555b"
           environment="Live"    
            />
    <order shopId="1" articleId="2" invoiceId="2000024720733"
           shopName="Your store"
           articleName="Ushanka"
           orderNumber="40522286348326"
           paymentSystemOrderNumber="483536613043117008"
           customerNumber="810844412"
           createdDatetime="2011-08-02T14:43:32.203+03:00"
           paid="false"
           orderSumAmount="2.08"
           orderSumCurrencyPaycash="643"
           orderSumBankPaycash="1003"
           paidSumAmount="2.07"
           paidSumCurrencyPaycash="643"
           paidSumBankPaycash="1003"
           environment="Live"    
            />
</listOrdersResponse>

If the value of any property can’t be defined (for example, the time of transfer for an unpaid order), the corresponding attribute will be omitted from the XML response.

Example of a successful response in CSV format

status=0;error=0;processedDT=2011-08-02T14:46:58.096+03:00;orderCount=2

shopId;shopName;articleId;articleName;invoiceId;orderNumber;paymentSystemOrderNumber;customerNumber;createdDatetime;paid;orderSumAmount;
orderSumCurrencyPaycash;orderSumBankPaycash;paidSumAmount;paidSumCurrencyPaycash;paidSumBankPaycash;receivedSumAmount;receivedSumCurrencyPaycash;
receivedSumBankPaycash;shopSumAmount;shopSumCurrencyPaycash;shopSumBankPaycash;paymentDatetime;paymentAuthorizationTime;payerCode;payerAddress;payeeCode;
paymentSystemDatetime;avisoReceivedDatetime;avisoStatus;paymentType;agentId;uniLabel;environment

1;"Your store";2;"Ushanka";2000024717776;"2011.08.02 09:07:32";483512879684006008;97881;2011-08-02T08:07:59.148+03:00;true;10.15;643;1003;10.15;643;
1003;10.15;643;1003;10.15;643;1003;2011-08-02T08:07:59.684+03:00;483512879684006008;41003476047679;192.168.1.127;41003131475668;2011-08-02T08:07:59.684+03:00;
2011-08-02T08:07:59.660+03:00;1000;AC;200002;1cd12967-0001-5000-8000-000000034fd8;Live


1;"Your store";2;"Ushanka";2000024717780;2000024717780;483512937773006008;770367;2011-08-02T08:08:57.175+03:00;true;10.00;643;1003;10.00;643;
1003;10.00;643;1003;10.00;643;1003;2011-08-02T08:08:57.773+03:00;483512937773006008;41003494819180;192.168.1.127;41003131475668;2011-08-02T08:08:57.773+03:00;
2011-08-02T08:08:57.730+03:00;1000;AC;200002;1cd129a4-0001-5000-8000-000000034fe1;Live

Example of error messages in XML format

XML
<listOrdersResponse
         status="3" error="111"
         processedDT="2011-07-02T20:38:01.000+04:00"
         techMessage="Invalid value for the requestDT parameter"
         />

Example of error messages in CSV format

status=3;error=111;processedDT=2011-07-21T13:20:14.869+04:00;”techMessage=Invalid value for the requestDT parameter”