Инструменты страницы
Запрос возврата на частичную сумму в деньгах, передача корзины (refund.do)
Для частичного возврата средств используется запрос refund.do
с обязательным указанием корзины возвращаемых товаров. По этому запросу средства по заказу будут возвращены плательщику.
Запрос закончится ошибкой, если средства по этому заказу не были списаны. Система позволяет вернуть средства более 1 раза, но не более первоначальной суммы списания.
Для безошибочной обработки запроса достаточно передать параметры quantity
и positionId
.
В запросе на возврат Корзина указывается в блоке refundItems
.
- В случае полного возврата заказа, передача корзины товаров необязательна.
- При возврате заказа на сумму отличную от суммы списания (кроме передачи значения «0») обязательно должна передаваться корзина товаров.
- В случае проведения нескольких возвратов по заказам с корзиной все они должны осуществляться только по алгоритму возврата с корзиной.
- Сумма возврата (в деньгах) в корзине не должна превышать подтверждённую денежную сумму оригинального заказа (для запросов
autoRefund
сравниваются композитные суммы денег и баллов). - Все товарные позиции корзины должны быть выражены в одной и той же валюте (если валюта позиций указывается), совпадающей с валютой оригинального заказа. Для Сбербанк «Спасибо» валюта заказа должна быть рубли РФ (643-RUB).
- В корзине запрещены для передачи товарные позиции, отсутствующие в оригинальном заказе. Происходит проверка наличия указанного товара в корзине запроса на возврат в изначальном заказе. Необходимо совпадение элементов
positionId
,name
,itemCode
. Если хотя бы одно из значений не совпадает, считается, что данная товарная позиция отсутствует в оригинальном заказе. - Значение элемента
quantity
в корзине запроса на завершение не должно превышать значение аналогичного параметра в корзине заказа на регистрацию. - Значение элемента
itemAmount
блокаitems
не должно превышать значение аналогичного параметра в оригинальном заказе. Для запросаautoRefund
система производит сравнение значения элементаitemAmount
блокаitems
с суммой денег и баллов по аналогичной позиции в оригинальном заказе. - Все параметры корзины проверяются на соответствие требуемому формату (длине).
В случае невыполнения хотя бы одного из указанных выше условий запрос возврата заказа считается неправильно сформированным и платёжный шлюз должен вернуть ошибку.
В настоящем документе при описании параметров запросов и ответов используются следующие обозначения типов данных:
- A<n> – последовательность латинских букв длины <n>;
- A..<n> – последовательность латинских букв длиной, не превышающей <n>;
- N<n> – последовательность цифр длины <n>;
- N..<n> – последовательность цифр длиной, не превышающей <n>;
- AN<n> – последовательность латинских букв и цифр фиксированной длины <n>;
- AN..<n> – последовательность латинских букв и цифр длиной, не превышающей <n>;
- ANS<n> – последовательность латинских букв, цифр и символов фиксированной длины <n>
- ANS..<n> – последовательность латинских букв, цифр и символов длиной, не превышающей <n>;
- UTC – дата и время, при этом: дата должна быть передана без указания часового пояса, время московское, для протокола SOAP используется стандартная кодировка xs:dateTime.
Пользуясь протоколом REST, тело сообщения запроса следует отправлять с типом: 'Content-Type: application/x-www-form-urlencoded'.
Параметры запроса
Название | Тип | Обязательно | Описание | Версия ФФД | ||
---|---|---|---|---|---|---|
|
AN..30 | Да |
Логин служебной учётной записи продавца. |
Все версии. |
||
|
AN..200 | Да |
Пароль служебной учётной записи продавца. |
Все версии. |
||
|
ANS36 | Да |
Номер заказа в платежной системе. Уникален в пределах системы. Отсутствует если регистрация заказа не удалась по причине ошибки, детализированной в ErrorCode. |
Все версии. |
||
|
N..12 | Да |
Сумма возврата в валюте заказа (в минимальных единицах). Должна совпадать с общей суммой всех возвращаемых товарных позиций. |
Все версии. |
||
|
Не актуально | Да |
Тег для передачи информации о возвращаемых товарах - номер позиции товара в запросе, название, детали, единица измерения, количество, валюта, код товара, скидка, выгода агента. |
Все версии. |
||
|
A2 | Нет |
Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках магазина как язык по умолчанию. |
Все версии. |
||
|
Блок данных для передачи дополнительных параметров ОФД | Нет |
Если блок Передача этого блока возможна только при использовании следующих ОФД:
|
1.05 и более поздние версии. |
||
|
| Нет |
Дополнительные параметры запроса. Формат вида: {«Имя1»: «Значение1», «Имя2»: «Значение2»}.
При осуществлении возврата заказа здесь, в случае необходимости, можно передавать размер удержания штрафа за возврат в виде параметра
Параметр penalty игнорируется при возвратах заказа с баллами (лояльностью), возвращается ошибка:
В параметре запрещено передавать зарезервированные имена (в случае их передачи заказ может быть отклонен):
|
Все версии. |
refundItems
refundItems
состоит из следующих элементов.
Обязательность параметров указана для использования в рамках блока. Если блок необязательный и отсутствует, то и параметры в него входящие не должны передаваться.
Название | Тип | Обязательно | Описание | Версия ФФД |
---|---|---|---|---|
|
Не актуально | Нет |
Массив блоков, описывающих товарные позиции в корзине. Информация по каждой товарной позиции Корзины передаётся в отдельном блоке, входящем в состав items. Не используйте внутри этого блока сочетание символов «‘)», в противном случае это приведёт к ошибке на стороне шлюза. |
Все версии. |
items
Обязательность параметров указана для использования в рамках блока. Если блок необязательный и отсутствует, то и параметры в него входящие не должны передаваться.
Название | Тип | Обязательно | Описание | Версия ФФД |
---|---|---|---|---|
|
ANS..12 | Да |
Уникальный идентификатор товарной позиции внутри корзины заказа. |
Все версии. |
|
ANS..255 | Да |
Наименование или описание товарной позиции в свободной форме. При отправке запроса в ОФД длина наименования будет обрезана до 128 символов.
Используйте |
Все версии. |
|
Не актуально | Нет |
Дополнительный блок с параметрами описания товарной позиции. Описание его атрибутов представлено ниже. Ограничение размера поля - 1024 байт. |
Все версии. |
|
N..18 | Да |
Элемент, описывающий общее количество товарных позиций одного |
Все версии. |
|
N..12 | Да |
Сумма стоимости всех товарных позиций одного
При расчёте параметра |
Все версии. |
|
N3 | Нет |
Код валюты товарной позиции ISO 4217. Если не указан, считается равным валюте заказа. |
Все версии. |
|
ANS..100 | Да |
Номер (идентификатор) товарной позиции в системе магазина.
Во всех методах передача артикула |
Все версии. |
|
Не актуально | Нет |
Дополнительный тег с атрибутами описания налога. Описание вложенных тегов представлено ниже. |
Все версии. |
|
N..18 | Нет |
Стоимость одной товарной позиции в минимальных единицах валюты. Обязательно для продавцов с фискализацией.
|
Все версии. |
|
См. описание. | Нет |
Блок атрибутов товарной позиции. |
1.05 и более поздние версии. |
itemAttributes
Ниже представлены параметры блока itemAttributes (см. пример и таблицу ниже).
"itemAttributes":[{"name":"paymentMethod","value":"1"},{"name":"paymentObject","value":"1"}]
Название | Тип | Обязательно | Описание | Версия ФФД |
---|---|---|---|---|
|
N..2 |
Да |
Тип оплаты возможны следующие значения:
Приоритизация передачи значения происходит по следующему принципу (указано в убывающем порядке приоритета):
Для paymentMethod значением по умолчанию является 1 (полная предварительная оплата до момента передачи предмета расчета). |
1.05 и более поздние версии. |
|
N..2 |
Да |
Тип оплачиваемой позиции, возможны следующие значения:
Указанные выше значения доступны для ФФД 1.05.
Приоритизация передачи значения происходит по следующему принципу (указано в убывающем порядке приоритета):
Для paymentObject значением по умолчанию является 1 (товар). |
1.05 и более поздние версии. |
|
ANS | да (если передан markQuantity ) |
Код товарной позиции. Принимаются только первые 256 байт. Возможные форматы для передачи:
|
1.05 и более поздние версии. |
|
| Нет |
Дробное количество маркированного товара. |
1.2 и более поздние версии. |
|
ANS..64 | Нет |
Значение реквизита пользователя. Можно передавать только после согласования с ФНС. |
1.05 и более поздние версии. |
|
N..2 | Обязателен, только если передан объект agent_info . |
Тип агента, возможно одно из следующих значений:
|
1.05 и более поздние версии. |
|
|
Нет |
|
1.05 и более поздние версии. |
|
|
Нет |
|
1.05 и более поздние версии. |
|
Массив ANS..19 | Нет |
Массив телефонов оператора по приёму платежей в формате +N. |
1.05 и более поздние версии. |
|
Массив ANS..19 | Нет |
Массив телефонов оператора перевода в формате +N. |
1.05 и более поздние версии. |
|
ANS..64 | Нет |
Наименование оператора перевода. |
1.05 и более поздние версии. |
|
ANS..256 | Нет |
Адрес оператора перевода. |
1.05 и более поздние версии. |
|
N10..12 | Нет |
ИНН оператора перевода. |
1.05 и более поздние версии. |
|
Maccив ANS..19 | Нет |
Массив телефонов поставщика в формате +N. |
1.05 и более поздние версии. |
|
ANS..256 | Нет |
Наименование поставщика. |
1.05 и более поздние версии. |
|
N10..12 | Нет |
ИНН поставщика. |
1.05 и более поздние версии. |
quantity
quantity
состоит из следующих элементов.
Обязательность параметров указана для использования в рамках блока. Если блок необязательный и отсутствует, то и параметры в него входящие не должны передаваться.
Название | Тип | Обязательно | Описание | Версия ФФД |
---|---|---|---|---|
|
N..18 | Да |
Количество товарных позиций данного | |
|
ANS..20 | Да |
Мера измерения количества товарной позиции. |
Все версии. |
Если ФФД версии 1.2 и более поздней, то здесь передаются параметры:
Название | Тип | Обязательно | Описание | Версия ФФД |
---|---|---|---|---|
|
N1 | Да |
Количество товарных позиций данного positionId. Для версии ФФД 1.2+ значение всегда 1. |
1.2 и более поздние версии. |
|
N..3 | Да |
Единица измерения количества предмета расчета. При ФФД версии 1.2+ , если переданы параметры nomenclature и markQuantity, значение всегда 0. В остальных случаях принимает значения |
1.2 и более поздние версии. |
Возможные значения measure
Значение | Описание |
---|---|
0 | Применяется для предметов расчета, которые могут быть реализованы поштучно или единицами (а также в случае, если предметом расчета является товар, подлежащий обязательной маркировке средством идентификации (передан mark_code )) |
10 | Грамм |
11 | Килограмм |
12 | Тонна |
20 | Сантиметр |
21 | Дециметр |
22 | Метр |
30 | Квадратный сантиметр |
31 | Квадратный дециметр |
32 | Квадратный метр |
40 | Миллилитр |
41 | Литр |
42 | Кубический метр |
50 | Киловатт час |
51 | Гигакалория |
70 | Сутки (день) |
71 | Час |
72 | Минута |
73 | Секунда |
80 | Килобайт |
81 | Мегабайт |
82 | Гигабайт |
83 | Терабайт |
255 | Применяется при использовании иных мер измерения |
markQuantity
Параметры тэга markQuantity:
Обязательность параметров указана для использования в рамках тэга. Если тэг необязательный и в запросе отсутствует, то и входящие в него параметры не должны передаваться.
Название | Тип | Обязательно | Описание |
---|---|---|---|
|
N..12 | да |
Числитель дробной части предмета расчета. |
|
N..12 | да |
Знаменатель дробной части предмета расчета. |
itemDetails
itemDetails
состоит из следующих элементов.
Обязательность параметров указана для использования в рамках блока. Если блок необязательный и отсутствует, то и параметры в него входящие не должны передаваться.
Название | Тип | Обязательно | Описание | Версия ФФД |
---|---|---|---|---|
|
ANS..255 | Да |
Дополнительная информация по товарной позиции. Представляет собой массив блоков, в каждом из которых передаётся информация об определённой характеристике товарной позиции. |
Все версии. |
itemDetailsParams
itemDetailsParams
состоит из следующих элементов.
Название | Тип | Обязательно | Описание | Версия ФФД |
---|---|---|---|---|
|
ANS..255 | Да |
Наименование параметра описания детализации товарной позиции. |
Все версии. |
tax
tax
состоит из следующих элементов.
Обязательность параметров указана для использования в рамках блока. Если блок необязательный и отсутствует, то и параметры в него входящие не должны передаваться.
Название | Тип | Обязательно | Описание | |
---|---|---|---|---|
|
N..2 | Нет |
Ставка НДС, доступны следующие значения:
Если в запросе не передаётся корзина с данными фискализации, оператору фискальных данных передаются значения по умолчанию, указанные в настройках личного кабинета (подробнее см. инструкцию по работе с личным кабинетом). |
Все версии. |
|
N..18 | Нет |
Сумма налога, высчитанная продавцом. Указывается в минимальных единицах валюты. |
Все версии. |
additionalOfdParams
additionalOfdParams
состоит из следующих элементов.
Название | Тип | Обязательно | Описание | Версия ФФД |
---|---|---|---|---|
|
N..2 | Обязателен, только если передан объект agent_info . |
Тип агента, возможно одно из следующих значений:
|
1.05 и более поздние версии. |
|
|
Нет |
|
1.05 и более поздние версии. |
|
|
Нет |
|
1.05 и более поздние версии. |
|
Массив ANS..19 | Нет |
Массив телефонов оператора по приёму платежей в формате +N. |
1.05 и более поздние версии. |
|
ANS..256 | Нет |
Адрес оператора перевода. |
1.05 и более поздние версии. |
|
N10..12 | Нет |
ИНН оператора перевода. |
1.05 и более поздние версии. |
|
ANS..64 | Нет |
Наименование оператора перевода. |
1.05 и более поздние версии. |
|
Массив ANS..19 | Нет |
Массив телефонов оператора перевода в формате +N. |
1.05 и более поздние версии. |
|
Maccив ANS..19 | Нет |
Массив телефонов поставщика в формате +N. |
1.05 и более поздние версии. |
|
A..256 | Нет |
ФИО кассира При запросе на возврат значение этого параметра может отличаться от переданного при регистрации заказа. |
1.05 и более поздние версии. |
|
ANS..16 | Нет |
Дополнительный реквизит чека. При запросе на возврат значение этого параметра может отличаться от переданного при регистрации заказа. |
1.05 и более поздние версии. |
|
ANS..24 | Нет |
Наименование дополнительного реквизита пользователя. При запросе на возврат значение этого параметра может отличаться от переданного при регистрации заказа. |
1.05 и более поздние версии. |
|
ANS..24 | Нет |
Значение дополнительного реквизита пользователя. При запросе на возврат значение этого параметра может отличаться от переданного при регистрации заказа. |
1.05 и более поздние версии. |
|
N..12 | Нет |
ИНН кассира |
1.2 и более поздние версии. |
|
ANS..256 | Нет |
Адрес покупателя (клиента). |
1.2 и более поздние версии. |
|
NS10 | Нет |
Дата рождения покупателя (клиента) в формате «dd.mm.yyyy» |
1.2 и более поздние версии. |
|
N3 | Нет |
Числовой код страны, гражданином которой является покупатель (клиент). Код страны указывается в соответствии с Общероссийским классификатором стран мира ОКСМ. |
1.2 и более поздние версии. |
|
N2 | Нет |
Числовой код вида документа, удостоверяющего личность (например, 21 - паспорт гр. РФ). |
1.2 и более поздние версии. |
|
NS11 | Нет |
Серия и номер паспорта плательщика: |
1.2 и более поздние версии. |
|
ANS..64 | Нет |
Электронный адрес покупателя. Обязательно должно быть заполнено строго одно из полей: |
1.2 и более поздние версии. |
|
NS..19 | Нет |
Телефон покупателя. Вместе с кодом страны без пробелов и дополнительных символов, кроме символа «+» (номер «+371 2 1234567» необходимо передать как «+37121234567»). Обязательно должно быть заполнено строго одно из полей: |
1.2 и более поздние версии. |
|
N12 | Нет |
ИНН покупателя. |
1.2 и более поздние версии. |
|
ANS..256 | Нет |
Наименование покупателя (клиента). |
1.2 и более поздние версии. |
|
|
Нет |
|
1.2 и более поздние версии. |
|
|
Нет |
|
1.2 и более поздние версии. |
|
|
Нет |
|
1.2 и более поздние версии. |
|
|
Нет |
|
1.2 и более поздние версии. |
|
NS10 | Нет |
Дата нормативного акта федерального органа исполнительной власти, регламентирующего порядок заполнения реквизита «значение отраслевого реквизита», в формате: |
1.2 и более поздние версии. |
|
ANS | Нет |
Идентификатор ФОИВ. Должно принимать одно из значений справочника ФОИВ. |
1.2 и более поздние версии. |
|
N..32 | Нет |
Номер нормативного акта федерального органа исполнительной власти, регламентирующего порядок заполнения реквизита «значение отраслевого реквизита» |
1.2 и более поздние версии. |
|
ANS..256 | Нет |
Состав значений, определенных нормативным актом федерального органа исполнительной власти |
1.2 и более поздние версии. |
|
ANS..20 | Нет (см. описание) |
Номер автомата.
|
1.05 и более поздние версии. |
|
ANS..243 | Нет (см. описание) |
Адрес расчетов.
|
1.05 и более поздние версии. |
|
ANS..243 | Нет (см. описание) |
Место расчетов.
|
1.05 и более поздние версии. |
Параметры ответа
Название | Тип | Обязательно | Описание | Версия ФФД |
---|---|---|---|---|
|
N..2 | Нет |
Код ошибки. Может отсутствовать, если результат не привёл к ошибке. |
Все версии. |
|
|
Нет |
|
Все версии. |
Коды ошибок
Значение | Описание |
---|---|
0 |
Успешно. |
5 |
Доступ запрещён. |
5 |
Пользователь должен сменить свой пароль. |
5 |
|
5 |
Неверная сумма. |
6 |
Неверный номер заказа. |
7 |
Платёж должен быть в корректном состоянии. |
7 |
Сумма возврата превышает сумму списания. |
7 |
Системная ошибка. |
Примеры
Пример запроса POST
userName=username-api&password=testPwd&orderId=d296be1d-c092-773b-ab2c-68e60128092a&amount=23500&refundItems={"items":[{"positionId":1,"name":"По-аджарски \"Лодочка\" SMALL","quantity":{"value":"1","measure":"0"},"itemCode":"270_235.00","itemPrice":23500,"tax":{"taxType":0,"taxSum":0},"itemAttributes":{"attributes":[{"name":"nomenclature","value":"010463003407001221CMK45BrhN0WLf"},{"name":"paymentMethod","value":"1"},{"name":"paymentObject","value":"30"},{"name":"agent_info.type","value":"7"},{"name":"agent_info.paying.operation","value":"test operation"},{"name":"agent_info.paying.phones","value":"%2B79161234123"},{"name":"agent_info.paymentsOperator.phones","value":"%2B79161234456"},{"name":"agent_info.MTOperator.phones","value":"%2B79161234789"},{"name":"agent_info.MTOperator.name","value":"MT operator"},{"name":"agent_info.MTOperator.address","value":"Moscow"},{"name":"agent_info.MTOperator.inn","value":"8634330204"},{"name":"supplier_info.phones","value":"%2B79161234333"},{"name":"supplier_info.name","value":"Supplier"},{"name":"supplier_info.inn","value":"287381373424"},{"name":"excise","value":"10.0"},{"name":"country_code","value":"810"},{"name":"declaration_number","value":"12332234533"},{"name":"userData","value":"user data"},{"name":"markQuantity.numerator","value":"1"},{"name":"markQuantity.denominator","value":"2"},{"name":"sectoralItemProps[0].federalId","value":"001"},{"name":"sectoralItemProps[0].date","value":"10.10.2021"},{"name":"sectoralItemProps[0].number","value":"123/4567"},{"name":"sectoralItemProps[0].value","value":"value1"},{"name":"sectoralItemProps[1].federalId","value":"003"},{"name":"sectoralItemProps[1].date","value":"11.10.2021"},{"name":"sectoralItemProps[1].number","value":"321/4567"},{"name":"sectoralItemProps[1].value","value":"value2"}]}}]}
Пример запроса с передачей параметра penalty
userName=username-api&password=testPwd&amount=500000&orderId=f6d6416b-bef1-72a5-9446-9e4f00a39301&jsonParams={"penalty":"130000"}&refundItems={"items":[{"positionId":1,"name":"da","quantity":{"value":1,"measure":"qtqwt"},"itemAttributes":{"attributes":[{"name":"paymentMethod","value":"4"},{"name":"paymentObject","value":"10"}]},"itemAmount":250000,"itemCode":"50248","itemPrice":250000,"tax":{"taxType":4}}]}
Пример ответа
{"errorCode":"0","errorMessage":"Успешно"}