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

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

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

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

description

ANS..512

Нет

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

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

paymentToken

AN..8192

Да

Параметр paymentToken должен содержать закодированное в Base64 значение свойства paymentData, полученного из объекта PKPaymentToken Object от системы Apple Pay (подробнее см. документацию Apple Pay). Таким образом, чтобы сделать запрос на оплату в платёжный шлюз, продавец должен:

  1. получить от системы Apple Pay объект PKPaymentToken Object, содержащий свойство paymentData;
  2. извлечь значение свойства paymentData и закодировать его в Base64;
  3. включить закодированное значение свойства paymentData в качестве значения парамера paymentToken в запросе на оплату, который продавец направит в платёжный шлюз.

language

A2

Нет

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

feeInput

N..8

Нет

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

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

clientId

ANS..255

Нет

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

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 (ложь) - параметр выключен, производится одностадийная оплата (средства списываются сразу).

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

Возможность проводить двухстадийные платежи предоставляется по отдельному запросу.

Этот параметр можно передавать как булевым значением (без кавычек), так и строкой (с кавычками).

ip

ANS..39

Нет

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

billingPayerData

См. описание

Нет

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

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

dynamicCallbackUrl

ANS..512

Нет

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

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

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

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 Да Подробное техническое объяснение ошибки - содержимое этого параметра не предназначено для отображения пользователю.
Элемент OrderStatus содержит параметры состояния заказа и возвращается, только если платёж шлюз признал все параметры запроса верными. См. список вложенных параметров ниже.

errorCode

N..2

Нет

Код ошибки.

См. описание кодов ошибок на этой странице.

orderNumber

ANS..32

Да

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

orderStatus

N1

Нет

По значению этого параметра определяется состояние заказа в платёжной системе. Отсутствует, если заказ не был найден. Возможны следующие значения:

  • 0 - заказ зарегистрирован, но не оплачен;
  • 1 - предавторизованная сумма захолдирована (для двухстадийных платежей);
  • 2 - проведена полная авторизация суммы заказа;
  • 3 - авторизация отменена;
  • 4 - по транзакции была проведена операция возврата;
  • 5 - инициирована авторизация через ACS банка-эмитента;
  • 6 - авторизация отклонена.

actionCode

ANS..6

Да

Код ответа процессинга. Полный перечень кодов ответов процессинга и расшифровки этих кодов размещены на отдельной странице.

actionCodeDescription

AN..512

Да

Расшифровка actionCode, возвращённая процессингом. Полный перечень кодов ответов процессинга и расшифровки этих кодов размещены на отдельной странице.

amount

N..12

Да

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

currency

N3

Нет

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

date

ANS

Да

Дата регистрации заказа в формате UNIX-времени (POSIX-времени).

ip

ANS..39

Да

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

Элемент merchantOrderParams

name

AN..20

Нет

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

value

ANS..2000

Нет

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

Элемент attributes

name

A7

Нет

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

value

ANS..2000

Нет

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

Элемент cardAuthInfo

pan

N12…19

Нет

Маскированный номер карты, которая использовалась для оплаты. Указан только после оплаты заказа.

В случае оплаты через Apple Pay в качестве номера карты используется DPAN: номер, привязанный к мобильному устройству покупателя и выполняющий функции номера платёжной карты в системе Apple Pay.

expiration

ANS

Нет

Срок истечения действия карты в формате ГГГГММ.

cardholderName

AS..26

Нет

Имя держателя карты латиницей, если доступно. Длина поля ограничена 26 символами (латинские буквы, точка, пробел).

approvalCode

AN6

Нет

Код авторизации международной платёжной системы. Поле фиксированной длины (6 символов), может содержать цифры и латинские буквы.

authDateTime

ANS

Нет

Дата и время авторизации в формате UNIX-времени (POSIX-времени).

terminalId

AN..10

Нет

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

authRefNum

AN..24

Нет

Учётный номер авторизации платежа, который присваивается при регистрации платежа.

Элемент paymentAmountInfo

approvedAmount

N..12

Нет

Сумма, подтверждённая к списанию.

depositedAmount

N..12

Нет

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

refundedAmount

N..12

Нет

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

paymentState

A..10

Нет

Состояние заказа, параметр может принимать следующие значения:

  • CREATED - заказ создан;
  • APPROVED - заказ подтверждён;
  • DEPOSITED - заказ завершён;
  • DECLINED - заказ отклонён;
  • REVERSED - заказ отменён;
  • REFUNDED - произведён возврат средств по заказу.

totalAmount

N..12

Нет

Сумма заказа + fee (комиссия, если она была использована в заказе).

Элемент bankInfo состоит из параметров.

bankCountryName

AN..160

Нет

Страна банка-эмитента.

Коды ошибок из параметра error

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

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

4

Некорректное значение параметра [paymentToken.signature], проверка не пройдена.

4

Авторизация неуспешна.

10

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

10

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

10

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

10

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

10

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

10

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

10

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

10

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

10

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

Коды ошибок из параметра errorCode

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

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
   <soapenv:Header/>
   <soapenv:Body>
      <mer:applePay>
         <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:applePay>
   </soapenv:Body>
</soapenv:Envelope>

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

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:applePayResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return>
            <success>true</success>
            <data>
               <orderId>4574f3e8-0d9a-418e-adcc-4b63aadee95b</orderId>
            </data>
            <orderStatus orderNumber="1478528500391" orderStatus="2" actionCode="0" actionCodeDescription="" amount="960000" currency="643" date="2016-11-07T17:24:13.573+03:00" ip="81.18.144.51" errorCode="0">
               <attributes name="mdOrder" value="4574f3e8-0d9a-418e-adcc-4b63aadee95b"/>
               <cardAuthInfo maskedPan="520424**0010" expiration="201907" cardholderName="CARD HOLDER" approvalCode="123456"/>
               <authDateTime>2016-11-07T17:24:13.890+03:00</authDateTime>
               <terminalId>12345678</terminalId>
               <authRefNum>111111111111</authRefNum>
               <paymentAmountInfo paymentState="DEPOSITED" approvedAmount="960000" depositedAmount="960000" refundedAmount="0"/>
               <bankInfo bankCountryName="&lt;Неизвестно>"/>
            </orderStatus>
         </return>
      </ns1:applePayResponse>
   </soap:Body>
</soap:Envelope>

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:applePayResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return>
            <success>false</success>
            <error>
               <code>10</code>
               <description>Отсутствует приватный ключ</description>
            </error>
            <orderStatus errorCode="0"/>
         </return>
      </ns1:applePayResponse>
   </soap:Body>
</soap:Envelope>