Запрос регистрации заказа с предавторизацией (registerOrderPreAuth)

Для запроса регистрации заказа с предавторизацией используется метод registerOrderPreAuth.

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

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

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

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

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

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

merchantOrderNumber

ANS..32

См. описание

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

description

ANS..512

Нет

Описание заказа в свободной форме. В процессинг «Сбербанка» для включения в финансовую отчётность продавца передаются только первые 24 символа этого поля.

Чтобы получить возможность отправлять это поле в процессинг, обратитесь в техническую поддержку.

amount

N..12

Да

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

currency

N3

Нет

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

language

A2

Нет

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

feeInput

N..8

Нет

Сумма комиссии в минимальных единицах валюты.

Параметр передается только при включении соответствующей пермиссии.

pageView

ANS..20

Нет

По значению данного параметра определяется, какие страницы платёжного интерфейса должны загружаться для клиента. Возможны следующие значения.

  • DESKTOP – для загрузки страниц, вёрстка которых предназначена для отображения на экранах ПК (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с названиями payment_<locale>.html и errors_<locale>.html).
  • MOBILE – для загрузки страниц, вёрстка которых предназначена для отображения на экранах мобильных устройств (в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с названиями mobile_payment_<locale>.html и mobile_errors_<locale>.html).
  • Если магазин создал страницы платёжного интерфейса, добавив в название файлов страниц произвольные префиксы, передайте значение нужного префикса в параметре pageView для загрузки соответствующей страницы. Например, при передаче значения iphone в архиве страниц платёжного интерфейса будет осуществляться поиск страниц с названиями iphone_payment_<locale>.html и iphone_error_<locale>.html.

Где:

  • locale – язык страницы в кодировке ISO 639-1. Например, ru для русского или en для английского.

Если параметр отсутствует, либо не соответствует формату, то по умолчанию считается pageView=DESKTOP.

sessionTimeoutSecs

N..9

Нет

Продолжительность жизни заказа в секундах.

В случае если параметр не задан, будет использовано значение, указанное в настройках мерчанта или время по умолчанию (1200 секунд = 20 минут).

Если в запросе присутствует параметр expirationDate, то значение параметра sessionTimeoutSecs не учитывается.

bindingId

AN..255

Нет

Идентификатор созданной ранее связки. Может использоваться, только если у продавца есть разрешение на работу со связками. Если этот параметр передаётся в данном запросе, то это означает:
1. Данный заказ может быть оплачен только с помощью связки;
2. Плательщик будет перенаправлен на платёжную страницу, где требуется только ввод CVC.

expirationDate

ANS

Нет

Дата и время окончания жизни заказа. Формат: yyyy-MM-ddTHH:mm:ss.

Если этот параметр не передаётся в запросе, то для определения времени окончания жизни заказа используется sessionTimeoutSecs.

returnUrl

ANS..512

Да

Адрес, на который требуется перенаправить пользователя в случае успешной оплаты, а также в случае неуспешной оплаты (при отсутствии переданного параметра failUrl). Адрес должен быть указан полностью, включая используемый протокол (например, https://test.ru вместо test.ru). В противном случае пользователь будет перенаправлен по адресу следующего вида: http://<адрес_платёжного_шлюза>/<адрес_продавца>.

Адрес нельзя указывать относительным путем, т.е. они не должны начинаться на «.» и «/». В противном случае вернется ошибка 4: «URL возврата некорректен». Например:

failUrl

ANS..512

Нет

Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://test.ru вместо test.ru). В противном случае пользователь будет перенаправлен по адресу следующего вида: http://<адрес_платёжного_шлюза>/<адрес_продавца>.

Адрес нельзя указывать относительным путем, т.е. они не должны начинаться на «.» и «/». В противном случае вернется ошибка 4: «URL возврата некорректен». Например:

Параметр необязательный. В таком случае при неуспешной оплате, так же как и при успешной оплате, будет происходить переход на returnUrl.

dynamicCallbackUrl

ANS..512

Нет

Параметр позволяет воспользоваться функциональность динамической отправки callback-уведомлений. В нем можно передать адрес, на который будут отправляться все «платежные» callback-уведомления, активированные для продавца. Под платежными понимаются callback-уведомления о следующих событиях: успешный холд, платеж отклонен по таймауту,  платеж cardpresent отклонен, успешное списание, возврат, отмена. При этом активированные для мерчанта callback-уведомления, не относящиеся к платежам (включение/выключение связки, создание связки), будут отправляться на статический адрес для callback-ов.

Для использования функциональности динамической отправки callback-уведомлений необходимо, чтобы у мерчанта была выставлена соответствующая настройка: Тип callback-а: Динамический (CALLBACK_TYPE = DYNAMIC).

Чтобы мерчант мог получать callback-уведомления, для него необходима активация пермиссии: Разрешено выполнять callback операции.

params

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

Нет

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

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

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

name

ANS..255

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

value

ANS..2000

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

При сценарии оплаты app2app, back2app и mWeb2App, а также при проведении первоначального платежа рекуррентных платежей, передаются также следующие параметры.

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

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


См. описание ниже
Передача признака изменения средства оплаты SberPay

clientId

ANS..255

Нет

Номер (идентификатор) клиента в системе магазина. Используется для реализации функционала связок. Может присутствовать, если магазину разрешено создание связок.

Указание этого параметра при платежах по связке необходимо - в противном случае платёж будет неуспешен.

merchantLogin

ANS..255

Нет

Чтобы зарегистрировать заказ от имени дочернего продавца, укажите его логин в этом параметре.

features

AN..255

Нет

Контейнер для параметра feature, в котором возможно передать следующие значения.

  • VERIFY - Если указать это значение после запроса на регистрацию заказа произойдёт верификация держателя карты без списания средств с его счёта, поэтому в запросе можно передавать нулевую сумму. Верификация позволяет убедиться, что карта находится в руках владельца, и впоследствии списывать с этой карты средства, не прибегая к проверке аутентификационных данных (CVC, 3D-Secure) при совершении последующих платежей.
  • Даже если сумма платежа будет передана в запросе, она не будет списана со счёта покупателя.
  • После успешной регистрации заказ сразу переводится в статус REVERSED (отменён).
  • AUTO_PAYMENT - Если запрос на регистрацию заказа инициирует проведение автоплатежей.
  • FORCE_TDS - Принудительное проведение платежа с использованием проверки на вовлеченность в 3-D Secure. Если карта не вовлечена в 3-D Secure, то оплата пройдет с ECI = 01/06.
  • FORCE_SSL - Принудительное проведение платежа через SSL (без использования 3-D Secure).
  • FORCE_FULL_TDS - После проведения аутентификации с помощью 3-D Secure статус PaRes должен быть только Y, что гарантирует успешную аутентификацию пользователя. В противном случае транзакция не пройдёт.
  • WITHOUT_FROM_CARD - В случае, если p2p заказ был зарегистрированный с такой feature, то при попытке выполнить peform с TransferType.STANDARD будет отклонена. С сообщением, о том, что заказ зарегистрирован с фичей WITHOUT_FROM_CARD
  • WITHOUT_TO_CARD - В случае, если p2p заказ был зарегистрированный с такой feature, то при попытке выполнить peform с TransferType.STANDARD будет отклонена. С сообщением, о том, что заказ зарегистрирован с фичей WITHOUT_TO_CARD

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

<features>
      <feature>AUTO_PAYMENT</feature>
</features>

autocompletionDate

ANS..19

Нет

Дата и время автозавершения двухстадийного платежа в следующем формате

2017-12-29T13:02:51

Чтобы подключить эту функциональность, обратитесь в службу технической поддержки.

autoReverseDate

ANS..19

Нет

Дата и время автоотмены авторизации (двухстадийного платежа) в следующем формате

2022-06-23T13:02:51

Чтобы подключить эту функциональность, обратитесь в службу технической поддержки.

email

ANS..40

Нет

Адрес электронной почты покупателя.

phone

NS..12

Нет

Номер телефона клиента. Примеры:

  • +79000000000
  • 89000000000
  • 9000000000
  • 79000000000

В случае передачи номера в отдельном параметре и в дополнительных параметрах, в качестве основного использоваться будет номер, указанный в настоящем параметре phone.

billingPayerData

См. описание

Нет

Блок c регистрационными данными клиента (адрес, почтовый индекс), необходимыми для прохождения проверки адреса в рамках сервисов AVS/AVV.

Обязателен, если активна соответствующая пермиссия для мерчанта («Разрешено использование AVS/AVV»).

По умолчанию в процессинг банка передаются поля:

  • orderNumber – номер заказа в системе магазина;
  • description – описание заказа (не более 24 символов, запрещены к использованию %, +, конец строки \r и перенос строки \n).

Параметры блока billingPayerData

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

billingCity

AN..50

Нет

Город, зарегистрированный по конкретной карте у Банка Эмитента

billingCountry

AN..50

Нет

billingAddressLine1

AN..50

Нет

Адрес, зарегистрированный по конкретной карте у Банка Эмитента

Строка 1.

Обязательно, если у Мерчанта активирована пермиссия «Разрешено использование AVS/AVV».

billingAddressLine2

AN..50

Нет

Адрес, зарегистрированный по конкретной карте у Банка Эмитента

Строка 2.

billingAddressLine3

AN..50

Нет

Адрес, зарегистрированный по конкретной карте у Банка Эмитента

Строка 3.

billingPostalCode

AN..50

Нет

Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента.

Обязательно, если у Мерчанта активирована пермиссия «Разрешено использование AVS/AVV».

billingState

AN..50

Нет

Штат, зарегистрированный по конкретной карте у Банка Эмитента (ISO 3166-2)



Параметры при сценарии оплаты app2app

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

app2app

Булевое значение

Нет

Атрибут, указывающий на способ оплаты через приложение СБОЛ (app2app). Возможны следующие значения:

  • true (истина);
  • false (ложь).

Для использования этого параметра у мерчанта должна быть включена соответствующая пермиссия.

app.osType

ANS..32

См. описание

Тип ОС. Возможные значения:

  • ios;
  • android.

Обязательно, только если app2app=true.

app.deepLink

ANS..255

См. описание

Ссылка на приложение мерчанта для возврата с успешной оплатой.

Обязательно, только если app2app=true.



Параметры при сценарии оплаты back2app

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

back2app

булевое значение

Нет

Атрибут, указывающий на способ оплаты по сценарию back2app

Параметры при сценарии оплаты mWeb2App

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

sberpay.backurl

ANS..255

Нет

Данные для возврата в мобильное приложение Мерчанта, при успешной оплате mWeb2App. При сценарии оплаты «mWeb2App» необходимо передавать: 

{"sberpay.backurl":"https://test.ru","mWeb2App":"true"}

Передача признака изменения средства оплаты SberPay

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

Параметр Тип Обязательно Описание
sberpay.paymentSourceChange boolean Нет Признак, позволяющий мерчанту указать на то, что происходит изменение средства оплаты SberPay, а не создание новой связки. Возможные значения: true/false.

Параметры рекуррентных платежей

В первоначальном платеже рекуррентных платежей передаются параметры, указанные ниже.

  • recurringFrequency – период рекуррентных платежей в днях (натуральное число в пределах от 1 до 28).
  • recurringExpiry – дата прекращения действия рекуррентных платежей (формат YYYYMMDD).

Если в запросе будет присутствовать только один параметр или хотя бы один параметр не будет соответствовать формату, выполнение запроса завершится ошибкой.

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

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

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

orderId

ANS36

Нет

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

formUrl

AN..512

Нет

URL-адрес платёжной формы, на который нужно перенаправить браузер клиента. Не возвращается, если регистрация заказа не удалась по причине ошибки, детализированной в errorCode.

Чтобы получить возможность принимать оплату этим способом, у вас должны быть соответствующие полномочия в системе. В случае сомнений оставить обращение и получить быстрое решение можно в личном кабинете в разделе «Поддержка».

errorCode

N..2

Нет

Код ошибки.

errorMessage

AN..512

Нет

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

externalParams

См. описание

Нет

Блок пар key (ключ) - value (значение), который возвращается при оплате по схемам app2app и back2app. Допустимо использовать следующие параметры (см. таблицу ниже).

Ниже представлен пример ответа с блоком externalParams. 

<ns1:registerOrderResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
    <return orderId="79cdbadf-4ec9-78e0-8c22-62f700a20c60" errorCode="0" errorMessage="Успешно">
        <formUrl>https://host/payment/merchants/rbs/payment_ru.html?mdOrder=79cdbadf-4ec9-78e0-8c22-62f700a20c60</formUrl>
        <externalParams>
            <entry>
                <key>sbolBankInvoiceId</key>
                <value>79cdbadf-4ec9-78e0-8c22-62f700a2</value>
            </entry>
            <entry>
                <key>sbolDeepLink</key>
                <value>https://test.ru</value>
            </entry>
        </externalParams>
    </return>
</ns1:registerOrderResponse>

Параметры externalParams при сценарии оплаты app2app

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

sbolDeepLink

ANS..1024

Нет

Ссылка на приложение Банка для завершения оплаты.

sbolBankInvoiceId

ANS..1024

Нет

Уникальный идентификатор заказа, сгенерированный Банком.

sbolInactive

Булевое значение

Нет

Атрибут, информирующий о проходящих регламентных работах. Значение true - если проводятся регламентные работы.

Значение false - если не проводятся регламентные работы.

Параметр может возникать, если у мерчанта включена соответствующая пермиссия, и app2app = true.

Параметры externalParams при сценарии оплаты back2app

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

sbolInactive

Булевое значение

Нет

Атрибут, информирующий о проходящих регламентных работах

Значение true - если проводятся регламентные работы

Значение false - если не проводятся регламентные работы

sbolBankInvoiceId

ANS..1024

Нет

Уникальный идентификатор заказа, сгенерированный Банком.

Коды ошибок

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

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

1

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

1

Заказ с таким номером уже обработан.

3

Неизвестная валюта.

4

Отсутствует сумма.

4

Номер заказа не может быть пуст.

4

URL возврата не может быть пуст.

5

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

5

Неверно указано значение одного из параметров.

5

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

5

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

7

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

13

Мерчант не имеет привилегии выполнять проверочные платежи.

14

Features указаны некорректно.

Примеры

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

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
    <soapenv:Header/>
    <soapenv:Body>
       <mer:registerOrderPreAuth>
          <order merchantOrderNumber="asuaakdfadsfasdfasdd5" description=" " amount="10000" currency=" " language="ru" pageView="DESKTOP" sessionTimeoutSecs=" " bindingId=" " expirationDate="2014-09-08T14:14:14">
             <returnUrl>https://server/applicaton_context/finish.html</returnUrl>
             <params name="param1" value="paramValue1"/>
             <params name="param2" value="paramValue2"/>
             <clientId>7777</clientId>
             <merchantLogin> </merchantLogin>
             <features>
                   <feature>AUTO_PAYMENT</feature>
             </features>
          </order>
       </mer:registerOrderPreAuth>
    </soapenv:Body>
 </soapenv:Envelope>

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
       <ns1:registerOrderPreAuthResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
          <return orderId="5e5dc6bd-dee3-4c96-849a-09f3f575f4b6" errorCode="0" errorMessage="Успешно">
             <formUrl> https://server/merchants/rbs/payment_ru.html?mdOrder=5e5dc6bd-dee3-4c96-849a-09f3f575f4b6 </formUrl>
          </return>
       </ns1:registerOrderPreAuthResponse>
    </soap:Body>
 </soap:Envelope>