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

Запрос возврата по устаревшему заказу сроком более двух лет (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>