Запрос оплаты заказа (paymentOrder)

Для оплаты заказа используется запрос paymentOrder.

В платежном шлюзе существует возможность использования как внутреннего, так и внешнего MPI.

Валидация карточных данных происходит в соответствии с таблицей:

Название	Расшифровка	Валидация
pan	N..19	Валидация карты (проверка реальности номера карты), количество цифр в номер карты от 13 до 20
cvc	CVC код	3 цифры
year, month	Год, Месяц	Дата в настоящем или будущем. В случае, если срок действия карты до текущего года текущего месяца, оплата возможна до конца календарного месяца
cardholderName	Владелец карты	Не проверяется

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

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.

Внутренний MPI

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

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

orderId

ANS36

Да

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

pan

N12…19

Да

Номер платёжной карты.

При указании в запросе параметра seToken этот параметр не обязателен к передаче.

cvc

Да

Код CVC/CVV2 на обратной стороне карты.

При указании в запросе параметра seToken этот параметр не обязателен к передаче.

year N4 Да Год окончания действия срока карты.

month N2 Да Месяц расчётного периода в формате MM.

cardholderName

AS..26

Да

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

language

Да

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

ip

ANS..39

Нет

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

email

ANS..40

Нет

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

params

См. столбец с описанием.

Нет

Дополнительный тег с атрибутами для передачи дополнительных параметров. Поля дополнительной информации для последующего хранения. Данные поля могут быть переданы на обработку банком для последующего отображения в реестрах. По умолчанию на обработку банком передаются поля номер заказа orderNumber и его описание orderDescription (не более 99 символов, запрещены к использованию «%» (процент), «+» (плюс), «\r» (конец строки) и «\n» (перенос строки)).

Включение данного функционала возможно по согласованию с банком в период интеграции. Для передачи N параметров, в запросе должно находиться N тегов params, где атрибут name содержит название, а атрибут value содержит значение (см. ниже).

Название	Тип	Описание
`name`	ANS..255	Название дополнительного параметра.
`value`	ANS..2000	Значение дополнительного параметра - до 2000 символов.

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

sbrf_spasibo:amount_bonus
sbrf_sbermiles:amount_bonus
loyaltyId
overridenClientId

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)

* По умолчанию в процессинг банка передаются поля номер заказа orderNumber и его описание description (не более 99 символов, запрещены к использованию %, +, конец строки \r и перенос строки \n)

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

Название	Тип	Обязательно	Описание
`errorCode`	N..2	Да	Код ошибки.
`errorMessage`	AN..512	Нет	Описание ошибки на языке, переданном в параметре `language` в запросе.
`info`	ANS..*	Нет	При успешном ответе. Результат попытки оплаты. Возможные значения представлены ниже. Ваш платёж обработан, происходит переадресация… Операция отклонена. Проверьте введённые данные, достаточность средств на карте и повторите операцию. Происходит переадресация… Извините, платёж не может быть совершён. Происходит переадресация… Операция отклонена. Обратитесь в магазин. Происходит переадресация… Операция отклонена. Обратитесь в банк, выпустивший карту. Происходит переадресация… Операция невозможна. Аутентификация держателя карты завершена неуспешно. Происходит переадресация… Нет связи с банком. Повторите позже. Происходит переадресация… Истёк срок ожидания ввода данных. Происходит переадресация… Не получен ответ от банка. Повторите позже. Происходит переадресация…
`redirect`	ANS..*	Нет	При успешном ответе. В случае платежа без необходимости аутентификации на ACS – URL, на который производится переадресация после платежа. В случае 3DS-платежа – URL для возврата с ACS.
`acsUrl`	AN..512	Нет	Адрес перенаправления на адрес сервера ACS. Не используется при платежах, не требующих дополнительной аутентификации на ACS Банка-эмитента.
`paReq`	AN..512	Нет	Запрос аутентификации плательщика. Не используется при платежах, не требующих дополнительной аутентификации на ACS Банка-эмитента.

Коды ошибок

Код ошибки	Текст ошибки
0	Обработка запроса прошла без системных ошибок
5	Доступ запрещён
5	Пользователь должен изменить свой пароль
5	Исчерпаны попытки оплаты или закончилось время сессии
5	Ошибка валидации данных
7	Системная ошибка

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

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="http://engine.paymentgate.ru/webservices/merchant">
 <soapenv:Header> 
      <soapenv:Body>
       <mer:paymentOrder>
          <order orderId="09808814-eb60-4cea-86bb-ed849dbe7ae9" year="2015" month="12" pan="4111111111111111" cvc="123" cardholderName="A Moriarty" language="ru" ip="?">
             <!-Zero or more repetitions:->
             <params name="name" value="value"/>
          </order>
       </mer:paymentOrder>
    </soapenv:Body>
 </soapenv:Envelope>

Пример ответа в случае проведения платежа, не требующего дополнительной аутентификации на ACS Банка-эмитента:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:paymentOrderResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
         <return info="Ваш платёж обработан, происходит переадресация..." redirect="www.ya.ru?MDORDER=6d295b5b-84c3-44cd-adea-c0eaca122465&amp;ANSWER=%3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%0A%3CPSApiResult+primaryRC%3D%220%22+secondaryRC%3D%220%22%2F%3E&amp;STATE=payment_deposited&amp;ACTION_CODE=0&amp;AUTH_CODE=2" errorCode="0"/>
      </ns1:paymentOrderResponse>
   </soap:Body>
</soap:Envelope>

Пример ответа в случае проведения 3DS-платежа, требующего дополнительной аутентификации на ACS Банка-эмитента:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
       <ns1:paymentOrderResponse xmlns:ns1="http://engine.paymentgate.ru/webservices/merchant">
          <return errorCode="0" info="Ваш платёж обработан, происходит переадресация..." redirect="https://test.paymentgate.ru:443/testpayment/rest/finish3ds.do" acsUrl="https://test.paymentgate.ru/acs/auth/start.do" paReq="eJxVUk1zgjAQ/SsM95KEr1pnjUOLnXqgYxUvvVHYAVQ+DFDUX99EUeshM/t2N2/3vQSmh2Kn/aJo8qqc6MyguoZlXCV5mU70dfj+NNKnHMJMIPorjDuBHAJsmihFLU8metGkBtM5LLwl7jkMTFwSGSaQK5RXRJxFZcshivev809uWzazHCADhALF3OfMtGzHfR4BuWAoowJ5iE27yqoayBlCXHVlK47ctS0gVwCd2PGsbesxIX3fG2lVpTs04qoAokpA7jssOhU1kuqQJzzwvf5yZqdPf0uDcHsM/C8WnNIJENUBSdQiNykzGaWOxujYpmNqAznnISrUDtx1XUqloguCWg3xHkr/UyC9FNLqq4wrAjzUVYmyQ/p3iyHBJr4ZodWDALmBygO5K3r7UB7HrXRvnXxvhdufxGKUdH34kiUb15mZ3k+3WSrnz01qXi79Yw67DFQAiKIhw6OS4cFl9PAR/gAOWr9V"/>
       </ns1:paymentOrderResponse>
    </soap:Body>
 </soap:Envelope>

Если для проведения платежа требуется применение технологии 3-D Secure, то после получения ответа на запрос оплаты клиента необходимо перенаправить на ACS. Существует два способа перенаправления: обычный и упрощённый (см. таблицу ниже).

Способ перенаправления	Описание
Обычный	Для перенаправления на ACS, мерчант со своей стороны должен отправить клиента по адресу, указанному в параметре acsUrl с телом запроса `MD=mdorder&PaReq=pareq&TermUrl=redirect`, где: mdorder - уникальный номер заказа в системе платежного шлюза, pareq - параметр из ответа на запрос оплаты, redirect - параметр из ответа на запрос оплаты (адрес возврата с ACS) или адрес магазина, если используется схема возврата из ACS в магазин. Запрос должен быть в формате POST. В зависимости от используемой схемы подключения клиент после аутентификации на ACS будет перенаправлен в платёжный шлюз или в магазин. Процессы завершения платежа для каждого из этих случаев описаны ниже.
Упрощённый	Чтобы клиент попал на страницу ACS, продавец перенаправляет его на страницу платёжного шлюза следующего вида: <api.адрес платёжного шлюза>/acsRedirect.do?orderId=<номер заказа> где: <`адрес платёжного шлюза`> - сервер и контекст подключения платёжного шлюза; Не забудьте добавить api. перед именем домена. <`номер заказа`> - уникальный номер заказа клиента. Далее без дополнительных действий со стороны клиента платёжный шлюз перенаправляет его на страницу ACS банка эмитента, где клиент проходит аутентификацию.

В случае неверной попытки оплаты шлюз возвращает следующий ответ.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:paymentOrderResponse xmlns:ns1="http://server/webservices/merchant">
         <return info="Операция отклонена. Проверьте введенные данные, достаточность средств на карте и повторите операцию." redirect="https://yandex.ru?orderId=39f1f59f-1836-7195-8452-1f6900003ad4&amp;lang=ru" errorCode="0"/>
      </ns1:paymentOrderResponse>
   </soap:Body>
</soap:Envelope>

В качестве URL-адреса перенаправления указывается значение, переданное в параметре failUrl (или returnUrl, если failUrl отсутствует).

В случае исчерпания попыток оплаты шлюз возвращает следующий ответ.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:paymentOrderResponse xmlns:ns1="http://engine.server.ru/webservices/merchant">
         <return errorCode="5" errorMessage="Исчерпаны попытки оплаты или закончилось время сессии"/>
      </ns1:paymentOrderResponse>
   </soap:Body>
</soap:Envelope>

Возврат с ACS в шлюз. Классическая схема

ACS эмитента проводит аутентификацию держателя карты и перенаправляет клиента в платежный шлюз, передавая PARes. Платежный шлюз проводит авторизацию заказа при успешной аутентификации клиента на ACS, или отклоняет предавторизацию при неуспешной аутентификации клиента на ACS.

Возврат с ACS в магазин. Схема с использованием дополнительного метода Finish 3DS

ACS эмитента проводит аутентификацию держателя карты и перенаправляет клиента в обратно в магазин. Полученный от ACS PARes передается в магазин, после чего магазин передает его в шлюз при помощи метода finishThreeDS.

Описание метода finishThreeDS приведено ниже.

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

Название	Тип	Обязательно	Описание
`md`	AN..30	Да	Номер заказа, полученный при регистрации заказа.
`paRes`	ANS	Да	Ответ на запрос аутентификации плательщика.

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

Название	Тип	Обязательно	Описание
`returnUrl`	ANS..512	Да	Адрес, на который требуется перенаправить пользователя в случае успешной оплаты, а также в случае неуспешной оплаты (при отсутствии переданного параметра `failUrl`). Адрес должен быть указан полностью, включая используемый протокол (например, https://test.ru вместо test.ru). В противном случае пользователь будет перенаправлен по адресу следующего вида: http://<адрес_платёжного_шлюза>/<адрес_продавца>. Адрес нельзя указывать относительным путем, т.е. они не должны начинаться на «.» и «/». В противном случае вернется ошибка 4: «URL возврата некорректен». Например: валидные url: https://www.test.com, https://test.com, www.test.com невалидные url: ../test.html, /test.html
`errorCode`	N..2	Нет	Код ошибки.
`errorMessage`	AN..512	Нет	Описание ошибки на языке, переданном в параметре `language` в запросе.

Если errorCode=0 и info=«Your order is proceeded, redirecting» – оплата прошла успешно. В других случаях с ошибкой, см. сообщение об ошибке errorMessage.

Коды ошибок (поле errorCode):

Код ошибки	Текст ошибки
0	Обработка запроса прошла без системных ошибок
5	Доступ запрещён
5	Пользователь должен изменить свой пароль
7	Заказ не найден
7	Системная ошибка