Запрос регистрации заказа (registerOrder)

Для регистрации заказа используется запрос registerOrder.

Для подключения к тестовой службе (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..598

Нет

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

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

amount

N..12

Да

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

currency

Нет

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

language

Нет

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

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 возврата некорректен». Например:

валидные url: https://www.test.com, https://test.com, www.test.com
невалидные url: ../test.html, /test.html

failUrl

ANS..512

Нет

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

валидные url: https://www.test.com, https://test.com, www.test.com
невалидные url: ../test.html, /test.html

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

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

См. описание ниже
Скрытие pay-кнопок (Apple Pay/Google Pay/Samsung Pay)

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>

email

ANS..40

Нет

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

phone

NS..12

Нет

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

+79000000000
89000000000
9000000000
79000000000

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

billingPayerData

См. описание

Нет

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

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

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

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

billingPayerData

Параметры блока 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)

Скрытие pay-кнопок ( Apple Pay/Google Pay/Samsung Pay)

Для того, чтобы скрыть pay-кнопку (Apple Pay/Google Pay/Samsung Pay) на платежной странице, не прибегая к изменениям пермиссий Мерчанта, необходимо в params передать следующее:

скрыть кнопку Google Pay:

<params name="showGooglePay" value="false"/>

скрыть кнопку Apple Pay:

<params name="showApplePay" value="false"/>

скрыть кнопку Samsung Pay:

 <params name="showSamsungPay" value="false"/>

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

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

Название	Тип	Обязательно	Описание
`orderId`	ANS36	Нет	Номер заказа в платежной системе. Уникален в пределах системы. Отсутствует, если регистрация заказа не удалась по причине ошибки, детализированной в errorCode.
`formUrl`	AN..512	Нет	URL-адрес платёжной формы, на который нужно перенаправить браузер клиента. Не возвращается, если регистрация заказа не удалась по причине ошибки, детализированной в `errorCode`. Чтобы получить возможность принимать оплату этим способом, у вас должны быть соответствующие полномочия в системе. В случае сомнений оставить обращение и получить быстрое решение можно в личном кабинете в разделе «Поддержка».
`errorCode`	N..2	Нет	Код ошибки.
`errorMessage`	AN..512	Нет	Описание ошибки на языке, переданном в параметре `language` в запросе.

Коды ошибок

Код ошибки	Текст ошибки
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:registerOrder>
          <order merchantOrderNumber="78ds901234567890" description=" " amount="15000" currency=" " language=" " pageView="MOBILE" sessionTimeoutSecs=" " bindingId=" " expirationDate="2014-09-08T14:14:14">
             <returnUrl>https://server/applicaton_context/finish.html</returnUrl>
             <params name="param1" value="valueParam1"/>
             <params name="param2" value="valueParam2"/>
             <clientId>666</clientId>
             <merchantLogin> </merchantLogin>
             <features>
                   <feature>AUTO_PAYMENT</feature>
             </features>
          </order>
       </mer:registerOrder>
    </soapenv:Body>
 </soapenv:Envelope>

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
       <ns1:registerOrderResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
          <return orderId="05fcbc62-7ee6-4f1a-b3d5-6ca41a982283" errorCode="0" errorMessage="Успешно">
             <formUrl> https://server/application_context/mobile_payment_ru.html?mdOrder=05fcbc62-7ee6-4f1a-b3d5-6ca41a982283 </formUrl>
          </return>
       </ns1:registerOrderResponse>
    </soap:Body>
 </soap:Envelope>

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