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

Для запроса регистрации заказа с предавторизацией используется метод registerPreAuth.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

AN..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..512

Нет

Описание заказа в свободной форме.

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.

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


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

sessionTimeoutSecs

N..9

Нет

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

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

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

expirationDate

ANS

Нет

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

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

bindingId

AN..255

Нет

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

features

ANS..255

Нет

Возможно использование следующих значений.

  • AUTO_PAYMENT - Платёж проводится без проверки подлинности владельца карты (без CVC и 3-D Secure). Чтобы проводить подобные платежи и продавца должны быть соответствующие разрешения.
  • VERIFY - Если указать это значение после запроса на регистрацию заказа произойдёт верификация держателя карты без списания средств с его счёта, поэтому в запросе можно передавать нулевую сумму. Верификация позволяет убедиться, что карта находится в руках владельца, и впоследствии списывать с этой карты средства, не прибегая к проверке аутентификационных данных (CVC, 3D-Secure) при совершении последующих платежей.
  • Даже если сумма платежа будет передана в запросе, она не будет списана со счёта покупателя.
  • После успешной регистрации заказ сразу переводится в статус REVERSED (отменён).
  • 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, что гарантирует успешную аутентификацию пользователя. В противном случае транзакция не пройдёт.

email

ANS..40

Нет

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

phone

NS..12

Нет

Номер телефона клиента без лидирующей «7». Параметр phone, передаваемый напрямую, не валидируется.

autocompletionDate

ANS..19

Нет

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

2017-12-29T13:02:51

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

autoReverseDate

ANS..19

Нет

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

2022-06-23T13:02:51

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

billingPayerData

См. описание Нет

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

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

billingAndShippingAddressMatchIndicator

A1

Нет

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

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

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

shippingPayerData

См. описание

Нет

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

orderPayerData

См. описание

Нет

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

preOrderPayerData

См. описание

Нет

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

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

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

Параметры блока 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 - повторный заказ.



Параметры при сценарии оплаты 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 при схеме app2app. 

{
    "orderId":"a728b310-c3a7-7c27-86fd-dc8100a20c60",
    "formUrl":"https://localhost:8989/payment/merchants/rbs/payment_ru.html?mdOrder=a728b310-c3a7-7c27-86fd-dc8100a20c60",
    "externalParams":{
        "sbolBankInvoiceId":"a728b310-c3a7-7c27-86fd-dc8100a2",
        "sbolDeepLink":"https://test.ru"
    }
}

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

{
    "orderId":"a728b310-c3a7-7c27-86fd-dc8100a20c60",
    "formUrl":"https://localhost:8989/payment/merchants/rbs/payment_ru.html?mdOrder=a728b310-c3a7-7c27-86fd-dc8100a20c60",
    "externalParams":{
        "sbolBankInvoiceId":"a728b310-c3a7-7c27-86fd-dc8100a2",
        "sbolInactive":"false"
    }
}

Параметры 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

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

4

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

4

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

5

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

5

Неправильный параметр 'Язык'.

5

Логин продавца неверен.

5

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

5

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

5

[jsonParams] неверен.

7

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

13

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

14

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

Примеры

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

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

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

{"orderId":"61351fbd-ac25-484f-b930-4d0ce4101ab7","formUrl":"https://3dsec.sberbank.ru/payment/mobile_payment_ru.html?mdOrder=61351fbd-ac25-484f-b930-4d0ce4101ab7"}