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

Для регистрации заказа с предавторизацией в схеме приёма платежа на стороне платёжной системы используется запрос registerPreAuth.do. Товарная корзина передаётся в параметре orderBundle. Запрос на регистрацию должен соответствовать требованиям, представленным ниже.

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

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

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



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

userName

AN..30

Да

Логин служебной учётной записи продавца.

password

AN..200

Да

Пароль служебной учётной записи продавца.

orderNumber

ANS..32

Да

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

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

amount

N..12

Да

Сумма платежа в минимальных единицах валюты (копейки, центы и т. п.). Должна совпадать с общей суммой по всем товарным позициям в корзине.

Перед суммированием всех товарных позиций для каждой товарной позиции произведение количества (quantity) и стоимости (price) округляется до целого числа. Т. е., если после десятичной запятой стоит 5 и более, то округление происходит в большую сторону. Ниже приведены примеры округления.

  1. Если quantity = 0,111, а price = 5500, то результат: 611 (округлённое 610,5).
  2. Если quantity = 1,455, а price = 6900, то результат: 10040 (округлённое 10039,5).
  3. Если quantity = 1,211, а price = 6988, то результат: 8462 (округлённое 8462,468).

Таким образом, параметр amount должен быть равен сумме округлённых товарных позиций.



Минимальная сумма кредита, 3000 рублей, поэтому минимальное значение amount:

  • 3000 рублей, в случае оформления кредита,
  • 3000 рублей + скидка партнера по рассрочке, в случае оформления рассрочки.

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

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

description

ANS..512

Нет

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

ANS..255

Нет

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

jsonParams

Строка

Нет

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

{name1:value1,…,nameN:valueN}

Эти поля могут быть переданы в процессинг банка для последующего отображения в реестрах.

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

Если для продавца настроена отправка уведомлений покупателю, адрес электронной почты покупателя должен передаваться в этом блоке в параметре с именем email. При указании «showLoyalty»:«false» взаимодействие с сервисом лояльности осуществляться не будет.

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

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

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

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

sessionTimeoutSecs

N..10

Нет

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

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

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

expirationDate

UTC

Нет

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

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

dummy

N4

Нет

Атрибут для управления скидкой по рассрочке на «заглушке» тестовой среды.
При передаче:

  • dummy=true – на «заглушке» тестовой среды применяется скидка по рассрочке в размере 5%, вне зависимости от выбранного срока;
  • dummy=false – на «заглушке» тестовой среды не применяется скидка по рассрочке.


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

autocompletionDate

ANS..19

Нет

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

2017-12-29T13:02:51

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

autoReverseDate

ANS..19

Нет

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

2022-06-23T13:02:51

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

bindingId

AN..255

Нет

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

orderBundle

Не актуально

Да

Блок, содержащий корзину товаров заказа. Описание его атрибутов представлено ниже.

(Перейти к описанию.)

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

orderBundle

orderBundle состоит из следующих элементов.

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

orderCreationDate

ANS..21

Нет

Дата создания заказа в формате YYYY-MM-DDTHH:mm:ss.

customerDetails

Не актуально

Нет

Блок с атрибутами данных о покупателе. Описание его атрибутов представлено ниже.

(Перейти к описанию.)

cartItems

Не актуально

Да

Блок с атрибутами товарных позиции корзины товаров. Описание его атрибутов представлено ниже.

(Перейти к описанию.)

installments

Не акутально

Условно
Обязательно при предоставлении покупателю возможности интернет-кредитования

Блок, в котором указаны параметры типа интернет-кредитования. Описание представлено ниже.

(Перейти к описанию.)

installments

Параметры блока installments.

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

productType

A..11

Да

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

  • CREDIT - кредит;
  • INSTALLMENT - рассрочка.

productId

Строка

Да

Для функциональности интернет-кредитования укажите значение 10.

rightTerms

ANS…255

Да

Желаемый срок кредитования в месяцах. Возможна передача нескольких значений через запятую. Атрибут передается, если выбран productType = INSTALLMENT.

  • Если параметр заполнен, то клиенту будут доступны только указанные в параметре сроки оплаты. Например, если "rightTerms":[3,6,9], то клиенту будут доступны для выбора сроки 3, 6 или 9 месяцев.
  • Если параметр не заполнен, то клиенту будут доступны все ранее утвержденные с банком сроки.

customerDetails

customerDetails состоит из следующих элементов.

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

email

ANS..40

См. примечание ниже.

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

phone

NS..12

См. примечание ниже.

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

  • +79000000000
  • 89000000000
  • 9000000000
  • 79000000000

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

contact

ANS..40

Нет

Способ связи с покупателем.

fullName

ANS..100

Нет

Фамилия, имя и отчество плательщика. Параметр возвращается только в том, случае если был передан партнером при регистрации.

passport

ANS..100

Нет

Серия и номер паспорта плательщика в следующем формате: 2222888888. Параметр возвращается только в том, случае если был передан партнером при регистрации.

inn

N..12

Нет

Идентификационный номер налогоплательщика. Допускается передавать 10 или 12 символов. Параметр возвращается только в том, случае если был передан партнером при регистрации.

deliveryInfo

Не актуально

Нет

Блок с атрибутами адреса для доставки. Описание его атрибутов представлено ниже.

(Перейти к описанию.)

Обязательно следует передать один из двух параметров: email или phone.

deliveryInfo

deliveryInfo состоит из следующих элементов.

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

deliveryType

ANS..20

Нет

Способ доставки.

country

A..2

Да

Двухбуквенный код страны доставки.

city

ANS..40

Да

Город доставки.

postAddress

ANS..255

Да

Адрес доставки.

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

cartItems

cartItems состоит из следующих элементов.

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

items

Не актуально

Да

Массив блоков, описывающих товарные позиции в корзине. Информация по каждой товарной позиции Корзины передаётся в отдельном блоке, входящем в состав items.

Не используйте внутри этого блока сочетание символов «‘)», в противном случае это приведёт к ошибке на стороне шлюза.

Действует ограничение: не более 100 товарных позиций.

(Перейти к описанию.)

items

items состоит из следующих элементов.

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

positionId

ANS..12

Да

Уникальный идентификатор товарной позиции внутри корзины заказа.

name

ANS..100

Да

Для функциональности интернет-кредитования необходимо указать описание товарной позиции в соответствии с каталогом Яндекс.Маркет с учетом следующих ограничений:

  • Не допускаются следующие слова и выражения: file, exec, insert, as, select, or, procedure, limit, order, and, or, by, asc, desc, delete, update, distinct, having, truncate, replace, handler, like, regex, tz_offset, to_timestamp_tz, bfilename, union, sql-command, abort, alter, analyze, begin, audit, checkpoint, close, cluster, comment, commit, copy, create, deallocate, declare, delete, drop, end, execute, explain, fetch, grant, insert, lock, move, noaudit, notify, prepare, reindex, rename, reset, revoke, rollback, savepoint, select, set, show, shutdown, start, truncate, unlisten, update, vacuum
  • Не допускаются следующие спецсимволы: % и \
  • Не допускаются символы кроме кириллицы и латиницы в unicode

itemDetails

Не актуально

Нет

Дополнительный блок с параметрами описания товарной позиции. Описание его атрибутов представлено ниже.

(Перейти к описанию.)

quantity

N..18

Да

Элемент, описывающий общее количество товарных позиций одного positionId и их меру измерения. Описание его атрибутов представлено ниже.

(Перейти к описанию.)

itemAmount

N..18

Условно
Обязательно при предоставлении покупателю возможности интернет-кредитования

Сумма стоимости всех товарных позиций одного positionId в минимальных единицах валюты. itemAmount обязателен к передаче, только если не был передан параметр itemPrice. В противном случае передача itemAmount не требуется. Если же в запросе передаются оба параметра: itemPrice и itemAmount, то itemAmount должен равняться itemPrice * quantity, в противном случае запрос завершится с ошибкой.

При расчёте параметра itemAmount = itemPrice*quantity результат округляется до второго знака после десятичного разделителя. Например, если результат вычислений равен 100,255, то итоговый результат будет равен 100,26.

itemCurrency

N3

Условно
Обязательно при предоставлении покупателю возможности интернет-кредитования

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

itemCode

ANS..100

Да

Номер (идентификатор) товарной позиции в системе магазина.

Во всех методах передача артикула itemcode/code обязательна.

itemPrice

N..18

Да

Стоимость одной товарной позиции в минимальных единицах валюты. Обязательно для продавцов с фискализацией.

  • itemPrice не может быть меньше 0.
  • itemPrice может передаваться как строкой, так и целочисленным типом.

quantity

quantity состоит из следующих элементов.

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

value

N..18

Да

Количество товарных позиций данного positionId. Для указания дробных чисел используйте десятичную точку.

Действует ограничение: не более 999 единиц.

measure

ANS..20

Да

Мера измерения количества товарной позиции.

itemDetails

itemDetails состоит из следующих элементов.

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

itemDetailsParams

ANS..255

Да

Дополнительная информация по товарной позиции. Представляет собой массив блоков, в каждом из которых передаётся информация об определённой характеристике товарной позиции.

(Перейти к описанию.)

itemDetailsParams

itemDetailsParams состоит из следующих элементов.

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

value

ANS..255

Условно. Обязательно при наличии параметра itemDetailsParams.

Дополнительная информация по товарной позиции.

name

AN..255

Условно. Обязательно при наличии параметра itemDetailsParams.

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

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

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

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

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

Пользователь отключён.

7

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

8

[orderBundle.cartItems.totalAmount] сумма товарных позиций в корзине не совпадает с общей суммой.

8

Доп. параметр amount_bonus запрещён, если в запросе указана корзина.

8

[orderBundle.cartItems.item.quantity.value] Слишком большое либо слишком маленькое значение.

Примеры

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

amount=24000&currency=643&language=ru&orderNumber=01a287222222299&returnUrl=https://3dsec.sberbank.ru/payment/finish.html&
jsonParams={"name1":"value1"}&orderBundle={ "orderCreationDate":1373622660000,
"customerDetails":{ "email":"1234567890123456789012345678901234567890", "phone": "79851231234",
"contact": "Mega Tester", "deliveryInfo":{ "deliveryType":"courier", "country":"RU", "city":"Moscow",
"postAddress":"Земляной Вал 50А стр.2" }},  "cartItems":  { "items": [
{ "positionId": "1", "name": "Metzeler Enduro 3 Sahara",
"itemDetails": { "itemDetailsParams": [{ "value": "Metzeler ", "name": "brand" },
{ "value": "17inch", "name": "radius" }]}, "quantity": { "value": 0.71, "measure": "штук" },
"itemAmount": 8000, "itemCurrency": "643", "itemCode": "NM-15",
{ "positionId": "2", "name": "Universal Mirror Enduro",
"itemDetails": { "itemDetailsParams": [{ "value": "Noname", "name": "brand" },
{ "value": "12mm", "name": "diameter" }]}, "quantity": { "value": 1.0, "measure": "штук" },
"itemAmount": 8000, "itemCurrency": "643", "itemCode": "NM-15",
{ "positionId": "3", "name": "Warm Grips",
"itemDetails": { "itemDetailsParams": [ { "value": "Noname", "name": "brand" }]},
"quantity": { "value": 1.0, "measure": "штук" },
"itemAmount": 8000, "itemCurrency": 643, "itemCode": "G-16"  }] } } }

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

{"operations":null,"errorCode":0,"errorMessage":null,"formUrl":"https://secure-payment-gateway.ru/sbercredit/rbs-common.html?mdOrder=b0d3767d-d67c-764d-a493-5cd404b41105&language=ru&dummy=true","orderId":"b0d3767d-d67c-764d-a493-5cd404b41105"}