Метод listOrders — [Архив] Протокол приема платежей через ЮKassa

Метод listOrders

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

Описание

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

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

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

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

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

Параметр	Тип	Описание
requestDT	dateTime	Дата и время запроса по часам системы магазина. Обязательный параметр.
outputFormat	normalizedString	Формат представления результата запроса. Допустимые значения — `XML` или `CSV`. Необязательный параметр, значение по умолчанию: `XML`
csvDelimiter	string, 1 символ	Разделитель значений для формата CSV. Не может быть равен символу «"» (кавычка). Необязательный параметр: значение по умолчанию «;» (точка с запятой).
shopId	long	Идентификатор магазина, список заказов которого запрашивается. Если параметр не задан, то возвращаются заказы по `shopId`, для которых у данного пользователя MWS имеется право получать список заказов.
orderCreatedDatetimeGreaterOrEqual	dateTime	Нижняя граница времени создания заказа. Выбираются заказы, время создания которых больше или равно значению этого параметра.
orderCreatedDatetimeLessOrEqual	dateTime	Верхняя граница времени создания заказа. Выбираются заказы, время создания которых меньше или равно значению этого параметра.
paid	boolean	Если параметр имеет значение `true`, то возвращаются только оплаченные заказы. Если параметр имеет значение `false`, то возвращаются только неоплаченные заказы. Если параметр не задан, будут возвращены как оплаченные, так и неоплаченные заказы.
paymentDatetimeGreaterOrEqual	dateTime	Нижняя граница времени оплаты заказа. Выбираются заказы, время оплаты которых больше или равно значению этого параметра.
paymentDatetimeLessOrEqual	dateTime	Верхняя граница времени оплаты заказа. Выбираются заказы, время оплаты которых меньше или равно значению этого параметра.
invoiceId	long	Уникальный номер транзакции в ЮKassa.
orderNumber	string, до 64 символов	Уникальный номер заказа в системе магазина. Использование параметра возможно, если сервис ЮKassa получает от магазина и хранит номера заказов.
outputFields	string, до 4000 символов	Список свойств заказа, которые должны быть выведены в результате выполнения запроса. Разделитель имен в списке — символ «;» (точка с запятой, без кавычек). Значение по умолчанию Полный список свойств заказа указан в разделе Формат ответа.

Особенности

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

номер транзакции (invoiceId) и идентификатор магазина (shopId);
номер заказа (orderNumber) и идентификатор магазина (shopId);
диапазон времени создания заказа (orderCreatedDatetimeGreaterOrEqual и/или orderCreatedDatetimeLessOrEqual);
диапазон времени оплаты заказа (paymentDatetimeGreaterOrEqual и/или paymentDatetimeLessOrEqual).

При запросах по номеру транзакции (invoiceId) или номеру заказа (orderNumber) в запросе обязательно должен быть указан идентификатор магазина (shopId).

Для запросов, выборка в которых ограничена диапазоном времени создания или времени оплаты заказа, действуют следующие правила:

если задана только одна граница диапазона для времени создания или оплаты заказа, то значение второй берется по умолчанию. Значение по умолчанию для верхней границы — текущее время в ЮKassa, значение по умолчанию для нижней границы — время верхней границы, указанное в запросе, минус одни сутки;
если задан диапазон времени оплаты заказа, то в запросе обязательно должен присутствовать параметр paid со значением true;
длина диапазона времени, ограничивающего выборку, не должна превышать 31 день;
количество записей, попадающих в выборку, не должно превышать 10 000.

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

Параметр	Тип	Описание
orderCount	int	Количество заказов в результате. Поле заголовка ответа. Присутствует в случае успешной выборки списка заказов (`listOrders`).
shopId	long	Идентификатор магазина, который ЮKassa выдала при подключении.
articleId	long	Идентификатор товара в ЮKassa.
shopName	string, до 64 символов	Название магазина.
articleName	string, до 128 символов	Название товара.
invoiceId	long	Уникальный номер транзакции в ЮKassa.
orderNumber	string, до 64 символов	Номер заказа в системе магазина. Если ЮKassa получает от магазина номера заказов и хранит их, то данный параметр содержит номер заказа в системе магазина. Иначе это свойство содержит номер транзакции в ЮKassa.
paymentSystemOrderNumber	string, до 40 символов	Идентификатор перевода в ЮKassa Присутствует только для оплаченных заказов.
customerNumber	string, до 64 символов	Идентификатор покупателя в системе магазина (присланный в платежной форме). Это может быть уникальный логин, номер мобильного телефона, номер договора и т. п., зависит от магазина.
createdDatetime	dateTime	Момент времени регистрации заказа на стороне ЮKassa.
paid	boolean	Имеет значение `true`, если заказ оплачен, иначе `false`.
paymentDatetime	dateTime	Момент времени оплаты заказа в ЮKassa. Значение присутствует в ответе только для оплаченных заказов.
paymentAuthorizationTime	long	Номер заказа в процессинговом центре ЮKassa. Значение присутствует в ответе только для оплаченных заказов.
payerCode	YMAccount	Номер счета плательщика. Значение присутствует в ответе только для оплаченных заказов.
payerAddress	string, до 33 символов	IP-адрес плательщика, если он известен. Значение присутствует в ответе только для оплаченных заказов.
payeeCode	YMAccount	Номер счета получателя перевода при оплате заказа. Значение присутствует в ответе только для оплаченных заказов.
paymentSystemDatetime	dateTime	Момент времени регистрации оплаты заказа в процессинговом центре ЮKassa. Значение присутствует в ответе только для оплаченных заказов.
avisoReceivedDatetime	dateTime	Момент времени регистрации оплаты заказа в системе магазина. Присутствует, если магазин на момент запроса получил уведомление о данном переводе.
avisoStatus	int	Код состояния уведомления о переводе. Список кодов состояний уведомления о переводе
avisoRegistryId	long	Номер реестра принятых платежей, в котором содержится данный заказ. Может отсутствовать в ответе.
orderSumAmount	CurrencyAmount	Сумма заказа.
orderSumCurrencyPaycash	CurrencyCode	Код валюты для `orderSumAmount`.
orderSumBankPaycash	CurrencyBank	Код процессингового центра для `orderSumAmount`.
contractAmount	CurrencyAmount	Сумма к оплате в валюте счета плательщика. Может отсутствовать в ответе.
contractCurrency	CurrencyCode	Код валюты счета плательщика. Может отсутствовать в ответе.
paidSumAmount	CurrencyAmount	Сумма, уплаченная плательщиком. Значение присутствует в ответе только для оплаченных заказов.
paidSumCurrencyPaycash	CurrencyCode	Код валюты для `paidSumAmount`. Значение присутствует в ответе только для оплаченных заказов.
paidSumBankPaycash	CurrencyBank	Код процессингового центра для `paidSumAmount`. Значение присутствует в ответе только для оплаченных заказов.
shopSumAmount	CurrencyAmount	Сумма, которая зачисляется на расчетный счет магазина: сумма заказа за вычетом комиссии ЮKassa.
shopSumCurrencyPaycash	CurrencyCode	Код валюты для суммы, которая зачисляется на расчетный счет магазина.
shopSumBankPaycash	CurrencyBank	Код процессингового центра для суммы, которая зачисляется на расчетный счет магазина.
receivedSumAmount	CurrencyAmount	Сумма, которую ЮKassa получает от плательщика. Значение присутствует в ответе только для оплаченных заказов.
receivedSumCurrencyPaycash	CurrencyCode	Код валюты для `receivedSumAmount`. Значение присутствует в ответе только для оплаченных заказов.
receivedSumBankPaycash	CurrencyBank	Код процессингового центра ЮKassa для `receivedSumAmount`. Значение присутствует в ответе только для оплаченных заказов.
paymentFormParams	string	Параметры платежной формы. Значение присутствует в ответе только для магазинов, у которых установлена настройка «сохранять параметры платежной формы».
paymentType	normalizedString	Способ проведения платежа
agentId	long	Служебный параметр в сервисе ЮKassa. Может отсутствовать в ответе.
uniLabel	string	Единая метка операции в сервисе ЮKassa.
clearing	string	Статус подтверждения отложенного платежа магазином. Возможные значения: `none` — платеж не подтвержден; `sale` — платеж подтвержден; `cancel` — платеж отменен. Значение присутствует в ответе только, если магазин настроен на отложенные платежи и разрешена передача информации о таких платежах в ответе на `listOrders`.
environment	string	Статус заказа, позволяет различать настоящие и тестовые операции. Возможные значения: `Live` — настоящая операция; `Test` — тестовая операция.

Если вы хотите получать информацию об отложенных платежах в запросе списка успешных платежей, обратитесь к менеджеру ЮKassa.

Примеры

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

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="Ваш магазин"
           articleName="Шапка-ушанка"
           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="Ваш магазин"
           articleName="Шапка-ушанка"
           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>

Если значение какого-либо свойства не может быть определено (например, время перевода для неоплаченного заказа), то в ответе формата XML соответствующий атрибут будет отсутствовать.

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

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;"Ваш магазин";2;"Шапка-ушанка";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;"Ваш магазин";2;"Шапка-ушанка";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

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

XML
<listOrdersResponse
         status="3" error="111"
         processedDT="2011-07-02T20:38:01.000+04:00"
         techMessage="Неверное значение параметра requestDT"
         />

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

status=3;error=111;processedDT=2011-07-21T13:20:14.869+04:00;”techMessage=Неверное значение параметра requestDT”

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

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