Инструменты страницы

Запрос возврата на полную сумму в деньгах, передача корзины (refundOrder)

Для запроса полного возврата средств оплаты используется запрос refundOrder. По этому запросу средства по указанному заказу будут возвращены плательщику. Запрос закончится ошибкой, если средства по этому заказу не были списаны.

Эта операция доступна пользователям, обладающим соответствующими правами в системе.

Для подключения к тестовой службе (WSDL) используйте следующий адрес:
https://3dsec.sberbank.ru/payment/webservices/merchant-ws?wsdl.


В запросе на возврат Корзина указывается в блоке 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.

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

Название Тип Обязательно Описание

orderId

ANS36

Да

Номер заказа в платежной системе. Уникален в пределах системы. Отсутствует, если регистрация заказа не удалась по причине ошибки, детализированной в errorCode.

refundAmount

N..12

Да

Сумма возврата в валюте заказа. Может быть меньше или равна остатку в заказе.

language

A2

Нет

Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках магазина как язык по умолчанию.

additionalOfdParams

Блок данных для передачи дополнительных параметров ОФД

Да

Некоторые параметры блока additionalOfdParams дублируют параметры блока cartItems.items.itemAttributes. Блок additionalOfdParams применяется ко всем позициям заказа, тогда как cartItems.items.itemAttributes применяется к индивидуальным позициям. Если в блоках additionalOfdParams и cartItems.items.itemAttributes будут переданы разные значения, то приоритетным значением будет то, которое было передано в cartItems.items.itemAttributes, то есть — для индивидуальной позиции.

Передача этого блока возможна только при использовании следующих ОФД:

  • АТОЛ;
  • Бизнес.Ру;
  • Эвотор.

(Перейти к описанию.)

params

См. столбец с описанием.

Нет

Дополнительные параметры заказа в формате объекта.

При осуществлении возврата заказа здесь, в случае необходимости, можно передавать размер удержания штрафа за возврат в виде параметра penalty:

<params name=«penalty» value=«1300»/>

В параметре запрещено передавать зарезервированные имена (в случае их передачи заказ может быть отклонен):

  • sbrf_spasibo:amount_bonus
  • sbrf_sbermiles:amount_bonus
  • loyaltyId
  • overridenClientId

additionalOfdParams

additionalOfdParams состоит из следующих элементов.

Название Тип Обязательно Описание Версия ФФД

agent_info.type

N..2

Обязателен, только если передан объект agent_info.

Тип агента, возможно одно из следующих значений:

  • 1 - банковский платёжный агент;
  • 2 - банковский платёжный субагент;
  • 3 - платёжный агент;
  • 4 - платёжный субагент;
  • 5 - поверенный;
  • 6 - комиссионер;
  • 7 - иной агент.

1.05 и более поздние версии.

agent_info.paying.operation

ANS..24

Нет

Наименование операции платёжного агента.

1.05 и более поздние версии.

agent_info.paying.phones

массив ANS..19

Нет

Массив телефонов платёжного агента в формате +N.

1.05 и более поздние версии.

agent_info.paymentsOperator.phones

Массив ANS..19

Нет

Массив телефонов оператора по приёму платежей в формате +N.

1.05 и более поздние версии.

agent_info.MTOperator.address

ANS..256

Нет

Адрес оператора перевода.

1.05 и более поздние версии.

agent_info.MTOperator.inn

N10..12

Нет

ИНН оператора перевода.

1.05 и более поздние версии.

agent_info.MTOperator.name

ANS..64

Нет

Наименование оператора перевода.

1.05 и более поздние версии.

agent_info.MTOperator.phones

Массив ANS..19

Нет

Массив телефонов оператора перевода в формате +N.

1.05 и более поздние версии.

supplier_info.phones

Maccив ANS..19

Нет

Массив телефонов поставщика в формате +N.

1.05 и более поздние версии.

cashier

A..256

Нет

ФИО кассира

При запросе на возврат значение этого параметра может отличаться от переданного при регистрации заказа.

1.05 и более поздние версии.

additional_check_props

ANS..16

Нет

Дополнительный реквизит чека.

При запросе на возврат значение этого параметра может отличаться от переданного при регистрации заказа.

1.05 и более поздние версии.

additional_user_props.name

ANS..24

Нет

Наименование дополнительного реквизита пользователя.

При запросе на возврат значение этого параметра может отличаться от переданного при регистрации заказа.

1.05 и более поздние версии.

additional_user_props.value

ANS..24

Нет

Значение дополнительного реквизита пользователя.

При запросе на возврат значение этого параметра может отличаться от переданного при регистрации заказа.

1.05 и более поздние версии.

cashier_inn

N..12

Нет

ИНН кассира

1.2 и более поздние версии.

client.address

ANS..256

Нет

Адрес покупателя (клиента).

1.2 и более поздние версии.

client.birth_date

NS10

Нет

Дата рождения покупателя (клиента) в формате «dd.mm.yyyy»

1.2 и более поздние версии.

client.citizenship

N3

Нет

Числовой код страны, гражданином которой является покупатель (клиент). Код страны указывается в соответствии с Общероссийским классификатором стран мира ОКСМ.

1.2 и более поздние версии.

client.document_code

N2

Нет

Числовой код вида документа, удостоверяющего личность (например, 21 - паспорт гр. РФ).

1.2 и более поздние версии.

client.passport_number

NS11

Нет

Серия и номер паспорта плательщика: 1111 222222

1.2 и более поздние версии.

client.email

ANS..64

Нет

Электронный адрес покупателя. Обязательно должно быть заполнено строго одно из полей: email или phone.

1.2 и более поздние версии.

client.phone

NS..19

Нет

Телефон покупателя. Вместе с кодом страны без пробелов и дополнительных символов, кроме символа «+» (номер «+371 2 1234567» необходимо передать как «+37121234567»). Обязательно должно быть заполнено строго одно из полей: email или phone.

1.2 и более поздние версии.

client.inn

N12

Нет

ИНН покупателя.

1.2 и более поздние версии.

client.name

ANS..256

Нет

Наименование покупателя (клиента).

1.2 и более поздние версии.

operatingCheckProps.name

ANS

Нет

Идентификатор операции Принимает значения «0» до определения значения реквизита ФНС России.

1.2 и более поздние версии.

operatingCheckProps.name

ANS

Нет

Идентификатор операции Принимает значения «0» до определения значения реквизита ФНС России.

1.2 и более поздние версии.

operatingCheckProps.timestamp

NS19

Нет

Дата и время операции в формате: dd.mm.yyyy HH:MM:SS

1.2 и более поздние версии.

operatingCheckProps.value

ANS..64

Нет

Данные операции.

1.2 и более поздние версии.

sectoralCheckProps.date

NS10

Нет

Дата нормативного акта федерального органа исполнительной власти, регламентирующего порядок заполнения реквизита «значение отраслевого реквизита», в формате: dd.mm.yyyy

1.2 и более поздние версии.

sectoralCheckProps.federalId

ANS

Нет

Идентификатор ФОИВ. Должно принимать одно из значений справочника ФОИВ.

1.2 и более поздние версии.

sectoralCheckProps.number

N..32

Нет

Номер нормативного акта федерального органа исполнительной власти, регламентирующего порядок заполнения реквизита «значение отраслевого реквизита»

1.2 и более поздние версии.

sectoralCheckProps.value

ANS..256

Нет

Состав значений, определенных нормативным актом федерального органа исполнительной власти

1.2 и более поздние версии.

Параметры ответа

Название Тип Обязательно Описание

errorCode

N..2

Нет

Код ошибки.

errorMessage

AN..512

Нет

Описание ошибки на языке, переданном в параметре language в запросе.

Коды ошибок

Значение Описание
0

Обработка запроса прошла без системных ошибок.

5

Доступ запрещён.

5

Пользователь должен сменить свой пароль.

5

[orderId] не указан.

5

Неверная сумма.

6

Неверный номер заказа.

7

Платёж должен быть в корректном состоянии.

7

Сумма возврата превышает сумму списания.

7

Системная ошибка.

8

Указанная сумма завершения не совпадает с полной суммой заказа. Необходима корзина для завершения на неполную сумму предавторизации.

Примеры

Пример запроса

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
   <soapenv:Header>
   <soapenv:Body>
      <mer:refundOrder>
         <order language="ru" orderId="48b6acc0-4d08-7207-a398-cb140128092a" refundAmount="23500">
           
         </order>
      </mer:refundOrder>
   </soapenv:Body>
</soapenv:Envelope>

Пример запроса с передачей параметра penalty

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
   <soapenv:Header>
    <soapenv:Body>
    <mer:refundOrder>
          <order language="ru" orderId="a5fe9c8f-0776-7f21-ab87-b2de00a39301" refundAmount="250000">
            <params name="penalty" value="140000"/>
           
       </mer:refundOrder>
    </soapenv:Body>
 </soapenv:Envelope>

Пример ответа

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:refundOrderResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return errorCode="0" errorMessage="Успешно"/>
      </ns1:refundOrderResponse>
   </soap:Body>
</soap:Envelope>