Запрос возврата по устаревшему заказу сроком более двух лет (instantRefund)

Для возврата средств по устаревшему заказу сроком более двух лет используется запрос instantRefund.

Данный запрос доступен мерчанту только при наличии у него пермиссии «Разрешены прямые выплаты без проверки заказов».

*В запросе передается либо карточные данные, либо bindingId, либо seToken.

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

  • 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.

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

Параметры запроса представлены в таблице ниже.

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

userName

AN..30

Да

Логин магазина, полученный при подключении. Если вместо аутентификации по логину и паролю используется открытый токен (параметр token), параметр userName передавать не нужно.

password

AN..200

Да

Пароль магазина, полученный при подключении. Если для аутентификации при регистрации вместо логина и пароля используется открытый токен (параметр token), параметр password передавать не нужно.

amount

N..12

Да

Сумма платежа в минимальных единицах валюты.

language

A2

Нет

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

currency

N3

Нет

Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию.

orderNumber

ANS..32

Нет

Номер (идентификатор) заказа в системе магазина, уникален для каждого магазина в пределах системы - до 30 символов. Если номер заказа генерируется на стороне платёжного шлюза, этот параметр передавать необязательно.

bindingId

AN..255

*Нет

Идентификатор связки созданной при оплате заказа или использованной для оплаты. Присутствует только если магазину разрешено создание связок.

seToken

AN..8192

*Нет

Параметр, содержащий шифрованное значение платёжных данных, введённых клиентом на стороне ТСП.

Комбинации валидных вариантов seToken: 

timestamp/uuid/PAN/CVV/EXPDATE
timestamp/uuid/PAN//EXPDATE
timestamp/uuid//CVV///bindingId
timestamp/uuid/////bindingId

pan

N12…19

*Нет

Номер платёжной карты.

При указании в запросе параметра seToken этот параметр не обязателен к передаче.

cvc

N3

*Нет

Этот параметр обязателен, если для продавца не выбрано разрешение Может проводить оплату без подтверждения CVC.

expiry

N6

*Нет

Год и месяц окончания срока действия карты в следующем формате:

YYYYMM.

cardHolderName

AS..26

*Нет

Имя держателя карты. Указан только после оплаты заказа. Длина поля ограничена 26 символами (латинские буквы, точка, пробел).

ip

ANS..39

Нет

IP-адрес покупателя. IPv6 поддерживается во всех запросах (до 39 символов).

params

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

Нет

Дополнительный тег с атрибутами для передачи дополнительных параметров. Поля дополнительной информации для последующего хранения. Данные поля могут быть переданы на обработку банком для последующего отображения в реестрах. По умолчанию на обработку банком передаются поля номер заказа orderNumber и его описание orderDescription (не более 99 символов, запрещены к использованию «%» (процент), «+» (плюс), «\r» (конец строки) и «\n» (перенос строки)).

Включение данного функционала возможно по согласованию с банком в период интеграции. Для передачи N параметров, в запросе должно находиться N тегов params, где атрибут name содержит название, а атрибут value содержит значение (см. ниже).

Название Тип Описание

name

ANS..255

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

value

ANS..2000

Значение дополнительного параметра - до 2000 символов.

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

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

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

Параметры ответа представлены в таблице ниже.

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

errorCode

N..2

Нет

Код ошибки.

errorMessage

AN..512

Нет

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

Коды ошибок

Код ошибки Текст ошибки
0

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

5

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

5

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

5

[orderId] не задан.

5

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

6

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

7

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

7

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

7

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

Примеры

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

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
   <soapenv:Header>
   <soapenv:Body>
 <mer:instantRefund>
 <request>
        <pan>5555555555555599</pan>
     <cvc>123</cvc>
     <expiry>202412</expiry>
     <cardHolderName>Test User</cardHolderName>
     <amount>1000</amount>
     </request>
     </mer:instantRefund>
   </soapenv:Body>
</soapenv:Envelope>

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

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