Запрос на оплату с помощью Samsung Pay (samsungPay)

Для оплаты через Samsung Pay используется запрос samsungPay.

Для подключения к тестовой службе (WSDL) используйте следующий адрес:
https://3dsec.sberbank.ru/payment/webservices/merchant-ws?wsdl.

Для операций отмены, возврата и завершения платежа следует использовать стандартные запросы к платёжному шлюзу.

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

  • A<n> – последовательность латинских букв длины <n>;
  • A..<n> – последовательность латинских букв длиной, не превышающей <n>;
  • N<n> – последовательность цифр длины <n>;
  • N..<n> – последовательность цифр длиной, не превышающей <n>;
  • AN<n> – последовательность латинских букв и цифр фиксированной длины <n>;
  • AN..<n> – последовательность латинских букв и цифр длиной, не превышающей <n>;
  • ANS<n> – последовательность латинских букв, цифр и символов фиксированной длины <n>
  • ANS..<n> – последовательность латинских букв, цифр и символов длиной, не превышающей <n>;
  • UTC – дата и время, при этом: дата должна быть передана без указания часового пояса, время московское, для протокола SOAP используется стандартная кодировка xs:dateTime.

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

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

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

merchant

AN..255

Да

Логин продавца в платёжном шлюзе.

orderNumber

ANS..32

Да

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

paymentToken

Строка

Да

Содержимое параметра 3ds.data из ответа, полученного от Samsung Pay.

ip

ANS..39

Нет

IP-адрес покупателя. IPv6 поддерживается во всех запросах (до 39 символов).

amount

N..12

Нет

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

description

ANS..512

Нет

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

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

language

A2

Нет

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

feeInput

N..8

Нет

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

Параметр передается только при включении соответствующей пермиссии.

additionalParameters

Не актуально

Нет

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

Название Тип Описание

key

Строка

Имя дополнительного параметра.

value

ANS..2000

Значение дополнительного параметра - до 2000 символов.

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

<entry>
    <key>parameter_1</key>
    <value>value_1</value>
</entry>
<entry>
    <key>parameter_2</key>
    <value>value_2</value>
</entry>

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

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

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

preAuth

A..5

Нет

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

  • true (истина) - параметр включён, производится двухстадийная оплата;
  • false (ложь) - параметр выключен, производится одностадийная оплата (средства списываются сразу).

Если параметр не указан в запросе, происходит одностадийная оплата.

clientId

ANS..255

Нет

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

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

currencyCode

N3

Нет

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

billingPayerData

См. описание

Нет

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

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

billingPayerData

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

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

billingCity

AN..50

Нет

Город, зарегистрированный по конкретной карте у Банка Эмитента

billingCountry

AN..50

Нет

billingAddressLine1

AN..50

Нет

Адрес, зарегистрированный по конкретной карте у Банка Эмитента

Строка 1.

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

billingAddressLine2

AN..50

Нет

Адрес, зарегистрированный по конкретной карте у Банка Эмитента

Строка 2.

billingAddressLine3

AN..50

Нет

Адрес, зарегистрированный по конкретной карте у Банка Эмитента

Строка 3.

billingPostalCode

AN..50

Нет

Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента.

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

billingState

AN..50

Нет

Штат, зарегистрированный по конкретной карте у Банка Эмитента (ISO 3166-2)

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

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

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

success

A..5

Да

Указывает на успешность запроса. Доступны следующие значения:

  • true (истина) - запрос обработан успешно;
  • false (ложь) - запрос не прошёл.
Блок data (возвращается, только если запрос прошёл успешно)

orderId

ANS36

Да

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

Блок error (возвращается, только если запрос завершился с ошибкой)

code

N..2

Да

Код ошибки.

description ANS..512 Да Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю.

message

AN..512

Да

Понятное описание ошибки - предназначено для отображения пользователю.

Коды ошибок

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

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

1

Недостаточно средств на карте.

5

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

5

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

7

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

10

Некорректное значение параметра [paymentToken].

10

Некорректное значение параметра [orderNumber].

10

Некорректное значение параметра [merchant].

10

Некорректное значение параметра [ip].

10

Некорректное значение параметра [paymentToken.header].

10

Расшифровка переданных данных неуспешна.

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

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
   <soapenv:Header/>
   <soapenv:Body>
      <mer:samsungPay>
         <arg0>
            <merchant>OurBestMerchantLogin</merchant>
            <orderNumber>UAF-203974-DE</orderNumber>
            <description>Test description</description>
            <paymentToken>ew0KICB7DQoJICAidmVyc2lvbiI6ICJSU0FfdjEiLA0KCSAgInNpZ25hdHVyZSI6ICJabUZyWlNCemFXZHVZWFIxY21VPSIsDQoJICAiaGVhZGVyIjogew0KCQkiZXBoZW1lcmFsUHVibGljS2V5IjogIk1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRW14Q2hDcGpLemY5YVh6MjZXVDZaVE4yekUzaUdYUWpjWlJZWUFkUUlURFgyUmtBTmJ0N2s5cmFoRjFoempqbWVWVHhjZ0NvZkg4MXprMkdOVFozZHRnPT0iICAgICAgIA0KCQkid3JhcHBlZEtleSI6ICJYejI2V1Q2WlROMnpFM2lHWFFqYz0iDQoJCSJwdWJsaWNLZXlIYXNoIjogIk9yV2dqUkdrcUVXamRrUmRVclhmaUxHRDBoZS96cEV1NTEyRkpXckdZRm89IiwNCgkJInRyYW5zYWN0aW9uSWQiOiAiYXBwbGUtMTIzNDU2Nzg5MEFCQ0RFRiINCgkgIH0sDQoJICAiZGF0YSI6ICIxZFhFMTNrdnpUVlA2bldFTjhEMnBoclBsZlFjR3I4VzN5ajJTSFlZai9QeWNIV1RqbnBWN3ovRXI3OGJyaT09Ig0KICB9DQp9</paymentToken>
            <language>RU</language>
            <additionalParameters>
               <entry>
                  <key>firstParamName</key>
                  <value>firstParamValue</value>
               </entry>
            </additionalParameters>
            <preAuth>true</preAuth>
            <ip>127.0.0.1</ip>
         </arg0>
      </mer:samsungPay>
   </soapenv:Body>
</soapenv:Envelope>

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

Успешная оплата

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:samsungPayResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return>
            <success>true</success>
            <data>
               <orderId>12312312123</orderId>
            </data>
            <orderStatus errorCode="0"/>
         </return>
      </ns1:samsungPayResponse>
   </soap:Body>
</soap:Envelope>

Неуспешная оплата

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:samsungPayResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return>
            <success>false</success>
            <error>
               <code>1</code>
               <description>Недостаточно средств на карте</description>
            </error>
            <orderStatus errorCode="0"/>
         </return>
      </ns1:samsungPayResponse>
   </soap:Body>
</soap:Envelope>