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



Запрос регистрации заказа (register.do)

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

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

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

Пользуясь протоколом REST, тело сообщения запроса следует отправлять с типом: 'Content-Type: application/x-www-form-urlencoded'.

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

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

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

userName

AN..30

нет (нужно указать либо пару логин и пароль, либо токен)

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

password

AN..200

нет (нужно указать либо пару логин и пароль, либо токен)

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

token

AN..256

нет (нужно указать либо пару логин и пароль, либо токен)

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

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

orderNumber

ANS..32

Да

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

amount

N..12

Да

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

currency

N3

Нет

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

returnUrl

ANS..512

Да

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

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

failUrl

ANS..512

Нет

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

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

Параметр необязательный.

dynamicCallbackUrl

ANS..512

Нет

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

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

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

description

ANS..598

Нет

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

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

language

A2

Нет

Язык в кодировке 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.

clientId

ANS..255

Нет

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

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

merchantLogin

AN..255

Нет

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

jsonParams

Строка

Нет

Дополнительные параметры запроса. Формат вида: {«Имя1»: «Значение1», «Имя2»: «Значение2»}. При сценарии оплаты app2app, back2app и mWeb2App передаются также следующие параметры (см. таблицу ниже). При указании «showLoyalty»:«false» взаимодействие с сервисом лояльности осуществляться не будет. В качестве дополнительных параметров в том числе возможно передать следующие:

  • «email» - если передать адрес электронной почты покупателя, он будет отображён на платёжной странице;
  • «phone» (обязательное поле) - если передать номер сотового телефона покупателя, он будет отображён на платёжной странице. Имеет ограничение по длине: от 7 до 15.

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

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


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

sessionTimeoutSecs

N..10

Нет

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

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

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

expirationDate

UTC

Нет

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

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

bindingId

AN..255

Нет

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

features

ANS..255

Нет

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

  • VERIFY - Если указать это значение после запроса на регистрацию заказа произойдёт верификация держателя карты без списания средств с его счёта, поэтому в запросе можно передавать нулевую сумму. Верификация позволяет убедиться, что карта находится в руках владельца, и впоследствии списывать с этой карты средства, не прибегая к проверке аутентификационных данных (CVC, 3D-Secure) при совершении последующих платежей.

Особенности передачи значения VERIFY

1. Даже если сумма платежа будет передана в запросе, она не будет списана со счёта клиента.
2. После успешной регистрации заказ сразу переводится в статус 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, что гарантирует успешную аутентификацию пользователя. В противном случае транзакция не пройдёт.

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

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

email

ANS..40

Нет

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

phone

NS..12

Нет

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

  • +79000000000
  • 89000000000
  • 9000000000
  • 79000000000

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

billingPayerData

См. описание

Нет

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

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

billingAndShippingAddressMatchIndicator

A1

Нет

Индикатор совпадения адреса держателя карты для выставления счета и адреса доставки. Возможные значения:

  • Y - адрес держателя карты для выставления счета и адрес доставки совпадают;
  • N - адрес держателя карты для выставления счета и адрес доставки не совпадают.

Этот параметр используется для дальнейшей 3DS аутентификации клиента.

shippingPayerData

См. описание

Нет

Блок с данными доставки клиента. Используется для дальнейшей 3DS аутентификации клиента.

orderPayerData

См. описание

Нет

Блок с данными о плательщике заказа. Используется для дальнейшей 3DS аутентификации клиента.

preOrderPayerData

См. описание

Нет

Блок с данными предзаказа. Используется для дальнейшей 3DS аутентификации клиента.

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

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

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

shippingcity

ANS…50

Нет

Город клиента (из адреса доставки).

shippingCountry

ANS…50

Нет

Страна клиента.

shippingAddressLine1

ANS…50

Нет

Основной адрес клиента (из адреса доставки).

shippingAddressLine2

ANS…50

Нет

Основной адрес клиента (из адреса доставки).

shippingAddressLine3

ANS…50

Нет

Основной адрес клиента (из адреса доставки).

shippingPostalCode

ANS…16

Нет

ZIP или иной почтовый индекс клиента для доставки.

shippingState

ANS…50

Нет

Штат/регион клиента (из адреса доставки).

shippingMethodIndicator

N2

Нет

Индикатор способа доставки. Перечень возможных значений:

  • 01 - доставка на адрес держателя карты для выставления счета;
  • 02 - доставка на другой адрес, проверенный Мерчантом;
  • 03 - доставка на адрес, отличный от основного адреса держателя карты (расчетного);
  • 04 - отправка в магазин/самовывоз (адрес магазина должен быть указан в соответствующих параметрах доставки);
  • 05 - цифровая дистрибуция (включает онлайн сервисы и электронные подарочные карты);
  • 06 - путешествия и билеты на события, не подлежащие доставке;
  • 07 - иное (например, игры, цифровые товары, не подлежащие доставке, цифровые подписки и т.д.).

deliveryTimeframe

N2

Нет

Сроки доставки товара. Перечень возможных значений:

  • 01 - цифровая дистрибуция;
  • 02 - доставка в день оплаты;
  • 03 - ночная доставка;
  • 04 - доставка в интервал 2 дня после оплаты и позже.

deliveryEmail

ANS…254

Нет

Целевой адрес электронной почты для доставки цифровой дистрибуции.

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

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

homePhone

ANS…19

Нет

Домашний телефон держателя карты, с обязательным символом «+».

workPhone

ANS…19

Нет

Рабочий телефон держателя карты, c обязательным символом «+».

mobilePhone

ANS…19

Нет

Мобильный телефон держателя карты, c обязательным символом «+».

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

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

preOrderDate

ANS8

Нет

Ожидаемая дата, когда будет доступна доставка (для предварительно заказанных покупок), в формате YYYYMMDD.

preOrderPurchaseInd

N2

Нет

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

  • 01 - доставка доступна;
  • 02 - будущая доставка.

reorderItemsInd

N2

Нет

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

  • 01 - заказ оформляет впервые;
  • 02 - повторный заказ.

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

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

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

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

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

{"showGooglePay": "false"}
а также: 
 {"showSbol":"false"}

или 

{"sberpayHide":"true"}

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

{"showApplePay": "false"}
а также: 
 {"showSbol":"false"}

или 

{"sberpayHide":"true"}

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

{"showSamsungPay": "false"}
а также: 
 {"showSbol":"false"}

или 

{"sberpayHide":"true"}

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

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

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

orderId

ANS36

Нет

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

formUrl

AN..512

Нет

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

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

errorCode

N..2

Нет

Код ошибки. Может отсутствовать, если результат не привёл к ошибке.

errorMessage

AN..512

Нет

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

Коды ошибок

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

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

1

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

1

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

3

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

4

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

4

Имя продавца не может быть пустым.

4

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

4

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

4

Пароль не может быть пуст.

5

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

5

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

5

[jsonParams] неверен.

7

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

13

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

14

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

Примеры

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

amount=100&currency=643&language=ru&orderNumber=87654321&returnUrl=http://yoursite.com&jsonParams={"orderNumber":1234567890}&pageView=DESKTOP&expirationDate=2014-09-08T14:14:14&merchantLogin=merch_child&features=AUTO_PAYMENT

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

{"orderId":"70906e55-7114-41d6-8332-4609dc6590f4","formUrl":"https://3dsec.sberbank.ru/payment/merchants/test/payment_ru.html?mdOrder=70906e55-7114-41d6-8332-4609dc6590f4"}