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

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

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

В запросах на регистрацию заказа (с предавторизацией или без) корзина товаров передаётся в параметре orderBundle.

  • Все товарные позиции корзины должны быть выражены в одной и той же валюте (если валюта позиции указывается) и должны совпадать с валютой заказа.
  • Сумма всех товарных позиций корзины должна быть равна сумме заказа.
  • По каждой товарной позиции производится проверка переданного значения quantity. В случае если значение слишком большое или слишком маленькое, то запрос завершается ошибкой.
  • Все параметры Корзины валидируются на соответствие требуемому формату (длине).

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

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

  • 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 передавать не нужно.

Все версии.

password

AN..200

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

Пароль служебной учётной записи продавца. При передаче логина и пароля для аутентификации в платёжном шлюзе параметр token передавать не нужно.

Все версии.

token

AN..256

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

Значение, которое используется для аутентификации продавца при отправке запросов в платёжный шлюз. При передаче этого параметра параметры userName и pаssword передавать не нужно.

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

Все версии.

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

Все версии.

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

AN..255

Нет

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

Все версии.

jsonParams

Строка

Нет

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

{name1:value1,…,nameN:valueN}

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

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

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

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

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

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

При наличии пермиссий у Мерчанта Разрешена оплата ЭС и Считать ARes.Y (frictionless) как полный 3DS 2.0, здесь обязательным параметром передается:

Название Тип Описание
fes_cashboxId N18 Идентификатор НСПК кассы Мерчанта, через которую осуществляется оплата ЭС

Все версии.

sessionTimeoutSecs

N..9

Нет

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

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

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

Все версии.

expirationDate

UTC

Нет

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

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

Все версии.

bindingId

AN..255

Нет

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

Все версии.

additionalOfdParams

Блок данных для передачи дополнительных параметров ОФД

Нет

Некоторые параметры блока additionalOfdParams дублируют параметры блока cartItems.items.itemAttributes. Блок additionalOfdParams применяется ко всем позициям заказа, тогда как cartItems.items.itemAttributes применяется к индивидуальным позициям. Если в блоках additionalOfdParams и cartItems.items.itemAttributes будут переданы разные значения, то приоритетным значением будет то, которое было передано в cartItems.items.itemAttributes, то есть — для индивидуальной позиции.

Передача этого блока возможна только при использовании следующих ОФД:

  • АТОЛ;
  • Бизнес.Ру;
  • Эвотор.

orderBundle

Не актуально

Да

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

Все версии.

taxSystem

N..2

Нет

Система налогообложения, доступны следующие значения:

  • 0 - общая;
  • 1 - упрощённая, доход;
  • 2 - упрощённая, доход минус расход;
  • 3 - единый налог на вменённый доход;
  • 4 - единый сельскохозяйственный налог;
  • 5 - патентная система налогообложения.

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

Все версии.

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

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

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

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

Ограничения поддержки параметров backToShopUrl, backToShopName

При передачи параметра backToShopUrl, на платёжной странице будет отображаться кнопка возврата покупателя в магазин. backToShopName - название кнопки возврата в магазин, которая будет отображаться, если передать параметр backToShopUrl.

Существуют ограничения поддержки параметров backToShopUrl, backToShopName в определенных статиках ПС, а именно:

Статика Поддержка параметра
rbc Оба параметра не поддерживаются
sbersafe Оба параметра поддерживаются

sbersafe_sberid

  • backToShopUrl - поддерживается;
  • backToShopName - не поддерживается

orderBundle

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

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

orderCreationDate

ANS..21

Нет

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

Все версии.

customerDetails

Не актуально

Нет

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

Все версии.

cartItems

Не актуально

Да

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

Все версии.

customerDetails

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

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

email

ANS..40

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

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

Все версии.

phone

NS..12

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

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

При использовании АТОЛ фискализации параметр phone следует передавать в следующем формате:

Номер телефона необходимо передать вместе с кодом страны без пробелов и дополнительных символов кроме символа «» (номер «371 2 1234567» необходимо передать как »+37121234567«). Если номер телефона относится к России (префикс »+7«), то значение можно передавать без префикса (номер »+79251234567« можно передать как «9251234567»). Максимальная длина строки - 64 символа. В запросе должно быть обязательно заполнено одно из полей: email или phone.

Все версии.

contact

ANS..40

Нет

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

Все версии.

deliveryInfo

Не актуально

Нет

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

Все версии.

fullName

ANS..100

Нет

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

1.05 и более поздние версии.

passport

ANS..100

Нет

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

1.05 и более поздние версии.

inn

N..12

Нет

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

1.05 и более поздние версии.

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

deliveryInfo

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

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

deliveryType

ANS..20

Нет

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

Все версии.

country

A..2

Да

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

Все версии.

city

ANS..40

Да

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

Все версии.

postAddress

ANS..255

Да

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

Все версии.

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

cartItems

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

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

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

items

Не актуально

Да

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

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

Все версии.

items

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

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

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

positionId

ANS..12

Да

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

Все версии.

name

ANS..100

Да

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

Используйте \\ - для передачи \

используйте \« - для передачи »

где « означает знак кавычек

Все версии.

itemDetails

Не актуально

Нет

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

Ограничение размера поля - 1024 байт.

Все версии.

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 обязательна.

Все версии.

tax

Не актуально

Только для магазинов с настройками фискализации

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

Все версии.

itemPrice

N..18

Только для магазинов с настройками фискализации

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

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

Все версии.

itemAttributes

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

Только для магазинов с настройками фискализации

Блок атрибутов товарной позиции.

1.05 и более поздние версии.

itemAttributes

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

paymentMethod

N..2

Да

Тип оплаты возможны следующие значения:

  • 1 - полная предварительная оплата до момента передачи предмета расчёта;
  • 2 - частичная предварительная оплата до момента передачи предмета расчёта;
  • 3 - аванс;
  • 4 - полная оплата в момент передачи предмета расчёта;
  • 5 - частичная оплата предмета расчёта в момент его передачи с последующей оплатой в кредит;
  • 6 - передача предмета расчёта без его оплаты в момент его передачи с последующей оплатой в кредит;
  • 7 - оплата предмета расчёта после его передачи с оплатой в кредит.

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

  1. Корзина заказа из API-запроса.
  2. Настройки фискализации в личном кабинете.
  3. Значения по умолчанию.

Для paymentMethod значением по умолчанию является 1 (полная предварительная оплата до момента передачи предмета расчета).

1.05 и более поздние версии.

paymentObject

N..2

Да

Тип оплачиваемой позиции, возможны следующие значения:

  • 1 - товар;
  • 2 - подакцизный товар;
  • 3 - работа;
  • 4 - услуга;
  • 5 - ставка азартной игры;
  • 6 - выигрыш азартной игры;
  • 7 - лотерейный билет;
  • 8 - выигрыш лотереи;
  • 9 - предоставление РИД;
  • 10 - платёж;
  • 11 - агентское вознаграждение;
  • 12 - составной предмет расчёта;
  • 13 - иной предмет расчёта;
  • 14 - имущественное право;
  • 15 - внереализационный доход;
  • 16 - страховые взносы: о суммах расходов, уменьшающих сумму налога (авансовых платежей) в соответствии с пунктом 3.1 статьи 346.21 Налогового кодекса Российской Федерации;
  • 17 - торговый сбор: о суммах уплаченного торгового сбора;
  • 18 - курортный сбор;

Указанные выше значения доступны для ФФД 1.05.

Для ФФД 1.2 список доступных значений пополняется также следующими значениями:

  • 30 - реализуемый подакцизный товар, подлежащий маркировке средством идентификации, не имеющем кода маркировки;
  • 31 - реализуемый подакцизный товар, подлежащий маркировке средством идентификации, имеющем кода маркировки;
  • 32 - реализуемый товар, подлежащий маркировке средством идентификации, не имеющим код маркировки, за исключением подакцизного товара;
  • 33 - реализуемый товар, подлежащий маркировке средством идентификации, имеющим код маркировки, за исключением подакцизного товара.

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

  1. Корзина заказа из API-запроса.
  2. Настройки фискализации в личном кабинете.
  3. Значения по умолчанию.

Для paymentObject значением по умолчанию является 1 (товар).

1.05 и более поздние версии.

nomenclature

ANS

да (если передан markQuantity)

Код товарной позиции.

Принимаются только первые 256 байт.

Возможные форматы для передачи:

  1. В шестнадцатеричном представлении - HEX кодировке с пробелами. Здесь необходимо cоответствие с маской 1 байт - пробел - 1 байт (два символа в шестнадцатеричном виде). Также необходимо указать код товара в соответствии с требованиями Честного Знака (максимальная длина - 95 символов).
  2. В виде строки, если передача идет не в HEX кодировке.

1.05 и более поздние версии.

markQuantity

Нет

Дробное количество маркированного товара.

1.2 и более поздние версии.

userData

ANS..64

Нет

Значение реквизита пользователя. Можно передавать только после согласования с ФНС.

1.05 и более поздние версии.

agent_info.type

N..2

Обязателен, только если передан объект agent_info.

Тип агента, возможно одно из следующих значений:

  • 1 - банковский платёжный агент;
  • 2 - банковский платёжный субагент;
  • 3 - платёжный агент;
  • 4 - платёжный субагент;
  • 5 - поверенный;
  • 6 - комиссионер;
  • 7 - иной агент.

1.05 и более поздние версии.

agent_info.paying.operation

ANS..24

Нет

Наименование операции платёжного агента.

1.05 и более поздние версии.

agent_info.paying.phones

массив ANS..19

Нет

Массив телефонов платёжного агента в формате +N.

1.05 и более поздние версии.

agent_info.paymentsOperator.phones

Массив ANS..19

Нет

Массив телефонов оператора по приёму платежей в формате +N.

1.05 и более поздние версии.

agent_info.MTOperator.phones

Массив ANS..19

Нет

Массив телефонов оператора перевода в формате +N.

1.05 и более поздние версии.

agent_info.MTOperator.name

ANS..64

Нет

Наименование оператора перевода.

1.05 и более поздние версии.

agent_info.MTOperator.address

ANS..256

Нет

Адрес оператора перевода.

1.05 и более поздние версии.

agent_info.MTOperator.inn

N10..12

Нет

ИНН оператора перевода.

1.05 и более поздние версии.

supplier_info.phones

Maccив ANS..19

Нет

Массив телефонов поставщика в формате +N.

1.05 и более поздние версии.

supplier_info.name

ANS..256

Нет

Наименование поставщика.

1.05 и более поздние версии.

supplier_info.inn

N10..12

Нет

ИНН поставщика.

1.05 и более поздние версии.

supplier_info.documentId

ANS..36

Нет

Уникальный идентификатор платежного документа

1.05 и более поздние версии.

supplier_info.payerName

A..256

Нет

ФИО плательщика.

1.05 и более поздние версии.

supplier_info.payerLs

ANS..30

Нет

Лицевой счет поставщика услуги.

1.05 и более поздние версии.

supplier_info.ls

ANS..20

Нет

Единый лицевой счёт поставщика услуг.

1.05 и более поздние версии.

supplier_info.bankBic

N9

Нет

БИК Банка получателя платежа.

1.05 и более поздние версии.

supplier_info.bankName

ANS..100

Нет

Название Банка получателя платежа.

1.05 и более поздние версии.

supplier_info.kpp

N9

Нет

КПП получателя платежа.

1.05 и более поздние версии.

supplier_info.rs

N20

Нет

Расчётный счёт получателя платежа.

1.05 и более поздние версии.

supplier_info.commission

N..10

Нет

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

1.05 и более поздние версии.

quantity

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

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

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

value

N..18

Да

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

Все версии.

measure

ANS..20

Да

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

Все версии.

Если ФФД версии 1.2 и более поздней, то здесь передаются параметры:

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

value

N1

Да

Количество товарных позиций данного positionId. Для версии ФФД 1.2+ значение всегда 1.

1.2 и более поздние версии.

measure

N..3

Да

Единица измерения количества предмета расчета. При ФФД версии 1.2+ , если переданы параметры nomenclature и markQuantity, значение всегда 0. В остальных случаях принимает значения

1.2 и более поздние версии.

Возможные значения measure

Значение Описание
0 Применяется для предметов расчета, которые могут быть реализованы поштучно или единицами (а также в случае, если предметом расчета является товар, подлежащий обязательной маркировке средством идентификации (передан mark_code))
10 Грамм
11 Килограмм
12 Тонна
20 Сантиметр
21 Дециметр
22 Метр
30 Квадратный сантиметр
31 Квадратный дециметр
32 Квадратный метр
40 Миллилитр
41 Литр
42 Кубический метр
50 Киловатт час
51 Гигакалория
70 Сутки (день)
71 Час
72 Минута
73 Секунда
80 Килобайт
81 Мегабайт
82 Гигабайт
83 Терабайт
255 Применяется при использовании иных мер измерения

markQuantity

Параметры тэга markQuantity:

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

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

numerator

N..12

да

Числитель дробной части предмета расчета.

denominator

N..12

да

Знаменатель дробной части предмета расчета.

itemDetails

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

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

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

itemDetailsParams

ANS..255

Да

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

Все версии.

itemDetailsParams

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

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

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

value

ANS..255

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

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

Все версии.

name

AN..255

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

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

Все версии.

При наличии у Мерчанта пермиссий Разрешена оплата ЭС и Считать ARes.Y (frictionless) как полный 3DS 2.0, здесь передается параметр fes_TruCode.

Пример:

{«name»:«fes_truCode»,«value»:«329921120.06002020100000000643»}, где:

name ANS..255 fes_TruCode
value NS30 Код ТРУ (товара/работ/услуг). Перейти к описанию кодировки ТРУ.

Указание произвольного количества бонусов «Спасибо»

При наличии у Мерчанта соответствующих настроек лояльности здесь можно передать параметр sbrf_spasibo:item_max_bonus_amount со значением максимального количества бонусов «Спасибо», доступных для списания для каждой товарной позиции в корзине. Значение должно быть строго числом больше или равным 0.

Итоговая максимальная сумма бонусов для списания складывается из всех значений sbrf_spasibo:item_max_bonus_amount, переданных в товарной корзине.

name ANS..255 sbrf_spasibo:item_max_bonus_amount
value NS30 Максимальное количество бонусов «Спасибо» для позиции корзины.

tax

tax содержит следующие элементы.

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

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

taxType

N..2

Нет

Ставка НДС, доступны следующие значения:

  • 0 – без НДС;
  • 1 – НДС по ставке 0%;
  • 2 – НДС чека по ставке 10%;
  • 4 – НДС чека по расчетной ставке 10/110;
  • 6 – НДС чека по ставке 20%;
  • 7 – НДС чека по расчётной ставке 20/120;
  • 10 – НДС чека по ставке 5%;
  • 11 – НДС чека по расчетной ставке 5/105;
  • 12 – НДС чека по ставке 7%;
  • 13 – НДС чека по расчетной ставке 7/107.

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

Все версии.

taxSum

N..18

Нет

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

Все версии.

additionalOfdParams

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

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

agent_info.type

N..2

Обязателен, только если передан объект agent_info.

Тип агента, возможно одно из следующих значений:

  • 1 - банковский платёжный агент;
  • 2 - банковский платёжный субагент;
  • 3 - платёжный агент;
  • 4 - платёжный субагент;
  • 5 - поверенный;
  • 6 - комиссионер;
  • 7 - иной агент.

1.05 и более поздние версии.

agent_info.paying.operation

ANS..24

Нет

Наименование операции платёжного агента.

1.05 и более поздние версии.

agent_info.paying.phones

массив ANS..19

Нет

Массив телефонов платёжного агента в формате +N.

1.05 и более поздние версии.

agent_info.paymentsOperator.phones

Массив ANS..19

Нет

Массив телефонов оператора по приёму платежей в формате +N.

1.05 и более поздние версии.

agent_info.MTOperator.address

ANS..256

Нет

Адрес оператора перевода.

1.05 и более поздние версии.

agent_info.MTOperator.inn

N10..12

Нет

ИНН оператора перевода.

1.05 и более поздние версии.

agent_info.MTOperator.name

ANS..64

Нет

Наименование оператора перевода.

1.05 и более поздние версии.

agent_info.MTOperator.phones

Массив ANS..19

Нет

Массив телефонов оператора перевода в формате +N.

1.05 и более поздние версии.

supplier_info.phones

Maccив ANS..19

Нет

Массив телефонов поставщика в формате +N.

1.05 и более поздние версии.

cashier

A..256

Нет

ФИО кассира.

1.05 и более поздние версии.

additional_check_props

ANS..16

Нет

Дополнительный реквизит чека.

1.05 и более поздние версии.

additional_user_props.name

ANS..24

Нет

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

1.05 и более поздние версии.

additional_user_props.value

ANS..24

Нет

Значение дополнительного реквизита пользователя.

1.05 и более поздние версии.

cashier_inn

N..12

Нет

ИНН кассира

1.2 и более поздние версии.

client.address

ANS..256

Нет

Адрес покупателя (клиента).

1.2 и более поздние версии.

client.birth_date

NS10

Нет

Дата рождения покупателя (клиента) в формате «dd.mm.yyyy»

1.2 и более поздние версии.

client.citizenship

N3

Нет

Числовой код страны, гражданином которой является покупатель (клиент). Код страны указывается в соответствии с Общероссийским классификатором стран мира ОКСМ.

1.2 и более поздние версии.

client.document_code

N2

Нет

Числовой код вида документа, удостоверяющего личность (например, 21 - паспорт гр. РФ).

1.2 и более поздние версии.

client.passport_number

NS11

Нет

Серия и номер паспорта плательщика: 1111 222222

1.2 и более поздние версии.

client.email

ANS..64

Нет

Электронный адрес покупателя. Обязательно должно быть заполнено строго одно из полей: email или phone.

1.2 и более поздние версии.

client.phone

NS..19

Нет

Телефон покупателя. Вместе с кодом страны без пробелов и дополнительных символов, кроме символа «+» (номер «+371 2 1234567» необходимо передать как «+37121234567»). Обязательно должно быть заполнено строго одно из полей: email или phone.

1.2 и более поздние версии.

client.inn

N12

Нет

ИНН покупателя.

1.2 и более поздние версии.

client.name

ANS..256

Нет

Наименование покупателя (клиента).

1.2 и более поздние версии.

operatingCheckProps.name

ANS

Нет

Идентификатор операции Принимает значения «0» до определения значения реквизита ФНС России.

1.2 и более поздние версии.

operatingCheckProps.name

ANS

Нет

Идентификатор операции Принимает значения «0» до определения значения реквизита ФНС России.

1.2 и более поздние версии.

operatingCheckProps.timestamp

NS19

Нет

Дата и время операции в формате: dd.mm.yyyy HH:MM:SS

1.2 и более поздние версии.

operatingCheckProps.value

ANS..64

Нет

Данные операции.

1.2 и более поздние версии.

sectoralCheckProps.date

NS10

Нет

Дата нормативного акта федерального органа исполнительной власти, регламентирующего порядок заполнения реквизита «значение отраслевого реквизита», в формате: dd.mm.yyyy

1.2 и более поздние версии.

sectoralCheckProps.federalId

ANS

Нет

Идентификатор ФОИВ. Должно принимать одно из значений справочника ФОИВ.

1.2 и более поздние версии.

sectoralCheckProps.number

N..32

Нет

Номер нормативного акта федерального органа исполнительной власти, регламентирующего порядок заполнения реквизита «значение отраслевого реквизита»

1.2 и более поздние версии.

sectoralCheckProps.value

ANS..256

Нет

Состав значений, определенных нормативным актом федерального органа исполнительной власти

1.2 и более поздние версии.

company.automat_number

ANS..20

Нет (см. описание)

Номер автомата.

Условия для обязательной передачи параметра:

  • ФФД 1.05 - для вендинга и транспорта;
  • ФФД 1.2 - для вендинга и транспорта.

1.05 и более поздние версии.

company.location

ANS..243

Нет (см. описание)

Адрес расчетов.

Условия для обязательной передачи параметра:

  • ФФД 1.05 - для вендинга, транспорта, курьеров;
  • ФФД 1.2 - для вендинга, транспорта, курьевров.

1.05 и более поздние версии.

company.payment_address

ANS..243

Нет (см. описание)

Место расчетов.

Условия для обязательной передачи параметра:

  • ФФД 1.05 - для вендинга, транспорта, курьеров;
  • ФФД 1.2 - для вендинга, транспорта, курьеров.

1.05 и более поздние версии.

Описание кодировки ТРУ

Код товаров/работ/услуг имеет размерность 19 знаков: 18 цифр и 1 знак разделитель: NNNNNNNNN.NNNNNNNNN

Для маркировки товаров, которые содержатся в перечне товаров/работ/услуг, ТСП должен выполнить обогащение данного кода, путем добавления значений: - кода производителя в формате YYYY; - кода модели в формате MMMM; - кода страны производителя по ОКСМ в формате ZZZ.

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

где: NNNNNNNNN (9 знаков) - код товара/услуги по ОКПД2 . - разделитель NNNNNNNNN (9 знаков) - код по классификатору Минтруда по Приказу №86Н от 13.02.2018 YYYY (4 знака) - код производителя MMMM (4 знака) - код модели ТСР (технических средств реабилитации) ZZZ (3 знака) - код страны производства по ОКСМ

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

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

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

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

userName=username-api&password=testPwd&amount=47000&language=ru&returnUrl=http://yoursite.com&orderBundle={"customerDetails":{"phone":"%2B79888888877","inn":"516974792202","passport":"4507 443564"},"cartItems":{"items":[{"positionId":1,"name":"По-аджарски \"Лодочка\" SMALL","quantity":{"value":"1","measure":"0"},"itemCode":"270_235.00","itemPrice":23500,"tax":{"taxType":0,"taxSum":0},"itemAttributes":[{"name":"nomenclature","value":"010463003407001221CMK45BrhN0WLf"},{"name":"paymentMethod","value":"1"},{"name":"paymentObject","value":"30"},{"name":"agent_info.type","value":"7"},{"name":"agent_info.paying.operation","value":"test operation"},{"name":"agent_info.paying.phones","value":"%2B79161234123"},{"name":"agent_info.paymentsOperator.phones","value":"%2B79161234456"},{"name":"agent_info.MTOperator.phones","value":"%2B79161234789"},{"name":"agent_info.MTOperator.name","value":"MT operator"},{"name":"agent_info.MTOperator.address","value":"Moscow"},{"name":"agent_info.MTOperator.inn","value":"8634330204"},{"name":"supplier_info.phones","value":"%2B79161234333"},{"name":"supplier_info.name","value":"Supplier"},{"name":"supplier_info.inn","value":"287381373424"},{"name":"excise","value":"10.0"},{"name":"country_code","value":"810"},{"name":"declaration_number","value":"12332234533"},{"name":"userData","value":"user data"},{"name":"markQuantity.numerator","value":"1"},{"name":"markQuantity.denominator","value":"2"},{"name":"sectoralItemProps[0].federalId","value":"001"},{"name":"sectoralItemProps[0].date","value":"10.10.2021"},{"name":"sectoralItemProps[0].number","value":"123/4567"},{"name":"sectoralItemProps[0].value","value":"value1"},{"name":"sectoralItemProps[1].federalId","value":"003"},{"name":"sectoralItemProps[1].date","value":"11.10.2021"},{"name":"sectoralItemProps[1].number","value":"321/4567"},{"name":"sectoralItemProps[1].value","value":"value2"}]}},{"positionId":2,"name":"Пирожок","quantity":{"value":"1","measure":"0"},"itemCode":"270_235.00","itemPrice":23500,"tax":{"taxType":0,"taxSum":0},"itemAttributes":[{"name":"nomenclature","value":"010463003407001221CMK45BrhN0WLf"},{"name":"paymentMethod","value":"1"},{"name":"paymentObject","value":"30"},{"name":"agent_info.type","value":"7"},{"name":"agent_info.paying.operation","value":"test operation"},{"name":"agent_info.paying.phones","value":"%2B79161234123"},{"name":"agent_info.paymentsOperator.phones","value":"%2B79161234456"},{"name":"agent_info.MTOperator.phones","value":"%2B79161234789"},{"name":"agent_info.MTOperator.name","value":"MT operator"},{"name":"agent_info.MTOperator.address","value":"Moscow"},{"name":"agent_info.MTOperator.inn","value":"8634330204"},{"name":"supplier_info.phones","value":"%2B79161234333"},{"name":"supplier_info.name","value":"Supplier"},{"name":"supplier_info.inn","value":"287381373424"},{"name":"excise","value":"10.0"},{"name":"country_code","value":"810"},{"name":"declaration_number","value":"12332234533"},{"name":"userData","value":"user data"},{"name":"markQuantity.numerator","value":"1"},{"name":"markQuantity.denominator","value":"2"},{"name":"sectoralItemProps[0].federalId","value":"001"},{"name":"sectoralItemProps[0].date","value":"10.10.2021"},{"name":"sectoralItemProps[0].number","value":"123/4567"},{"name":"sectoralItemProps[0].value","value":"value1"},{"name":"sectoralItemProps[1].federalId","value":"003"},{"name":"sectoralItemProps[1].date","value":"11.10.2021"},{"name":"sectoralItemProps[1].number","value":"321/4567"},{"name":"sectoralItemProps[1].value","value":"value2"}]}}]}}

Пример запроса POST при наличии пермисии "Разрешена оплата ЭС"

returnUrl:http://test.ru/
language:ru
currency:810
orderBundle:{"customerDetails":{"phone":"9888888888", "inn":"", "email":"email@mail.com"},"cartItems":{"items":[{"positionId":1,"name":"Трость опорная, регулируемая по высоте, без устройства противоскольжения","itemDetails":{"itemDetailsParams":[{"name":"fes_truCode","value":"329921120.06001010100000000643"}]},"quantity":{"value":"3.00","measure":"шт."},"itemCode":"270_235.00","itemPrice":40000,"tax":{"taxType":0,"taxSum":0}}, {"positionId":2,"name":"Трость белая тактильная цельная","itemDetails":{"itemDetailsParams":[{"name":"fes_truCode","value":"329921120.06002020100000000643"}]},"quantity":{"value":"3.00","measure":"шт."},"itemCode":"270_244.00","itemPrice":23500,"tax":{"taxType":0,"taxSum":0}}]}}
jsonParams:{"fes_cashboxId":"900000000000000004"}
amount:190500
failUrl:https://ya.ru/
userName:{{userName}}
password:{{password}}

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

{"orderId":"b089befe-127a-75e4-a68f-918c0128092a","formUrl":"https://3dsec.sberbank.ru/payment/merchants/789/payment_ru.html?mdOrder=b089befe-127a-75e4-a68f-918c0128092a"}