Инструменты страницы
Запрос оплаты заказа (paymentOrder)
Для оплаты заказа используется запрос paymentOrder
.
В настоящем документе при описании параметров запросов и ответов используются следующие обозначения типов данных:
- 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.
Параметры запроса:
Название | Тип | Обязательно | Описание | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
|
ANS36 | Да |
Номер заказа в платежной системе. Уникален в пределах системы. Отсутствует, если регистрация заказа не удалась по причине ошибки, детализированной в errorCode. |
|||||||||
|
N12…19 | Да |
Номер платёжной карты. При указании в запросе параметра seToken этот параметр не обязателен к передаче. |
|||||||||
|
N3 | Да |
Код CVC/CVV2 на обратной стороне карты. При указании в запросе параметра seToken этот параметр не обязателен к передаче. |
|||||||||
year | N4 | Да | Год окончания действия срока карты. | |||||||||
month | N2 | Да | Месяц расчётного периода в формате MM . |
|||||||||
|
AS..26 | Да |
Имя держателя карты латиницей, если доступно. Длина поля ограничена 26 символами (латинские буквы, точка, пробел). |
|||||||||
|
A2 | Да |
Язык в кодировке ISO 639-1. Если не указан, будет использован язык, указанный в настройках магазина как язык по умолчанию. |
|||||||||
|
ANS..39 | Нет |
IP-адрес покупателя. IPv6 поддерживается во всех запросах (до 39 символов). |
|||||||||
|
ANS..40 | Нет |
Адрес электронной почты покупателя. |
|||||||||
|
См. столбец с описанием. | Нет |
Дополнительный тег с атрибутами для передачи дополнительных параметров. Поля дополнительной информации для последующего хранения. Данные поля могут быть переданы на обработку банком для последующего отображения в реестрах. По умолчанию на обработку банком передаются поля номер заказа orderNumber и его описание orderDescription (не более 99 символов, запрещены к использованию «%» (процент), «+» (плюс), «\r» (конец строки) и «\n» (перенос строки)).
Включение данного функционала возможно по согласованию с банком в период интеграции. Для передачи N параметров, в запросе должно находиться N тегов
В параметре запрещено передавать зарезервированные имена (в случае их передачи заказ может быть отклонен):
|
|||||||||
|
См. описание | Нет |
Блок c регистрационными данными клиента (адрес, почтовый индекс), необходимыми для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязателен, если активна соответствующая пермиссия для мерчанта («Разрешено использование AVS/AVV»). |
billingPayerData
Параметры блока billingPayerData
Название | Тип | Обязательно | Описание |
---|---|---|---|
|
AN..50 | Нет |
Город, зарегистрированный по конкретной карте у Банка Эмитента |
|
AN..50 | Нет |
|
|
AN..50 | Нет |
Адрес, зарегистрированный по конкретной карте у Банка Эмитента Строка 1. Обязательно, если у Мерчанта активирована пермиссия «Разрешено использование AVS/AVV». |
|
AN..50 | Нет |
Адрес, зарегистрированный по конкретной карте у Банка Эмитента Строка 2. |
|
AN..50 | Нет |
Адрес, зарегистрированный по конкретной карте у Банка Эмитента Строка 3. |
|
AN..50 | Нет |
Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно, если у Мерчанта активирована пермиссия «Разрешено использование AVS/AVV». |
|
AN..50 | Нет |
Штат, зарегистрированный по конкретной карте у Банка Эмитента (ISO 3166-2) |
** По умолчанию в процессинг банка передаются поля номер заказа orderNumber и его описание description (не более 99 символов, запрещены к использованию %, +, конец строки \r и перенос строки \n)
При аутентификации по протоколу 3DS 2.0 также передаются следующие параметры:
Название | Тип | Обязательно | Описание |
---|---|---|---|
|
ANS..36 | См. описание |
Идентификатор транзакции созданный на сервере 3DS. Параметр используется при проведения аутентификации клиента по протоколу 3DS версии 2.0. |
|
AN..512 | Нет |
Адрес переадресации клиента после аутентификации на сервере ACS. Параметр используется при проведения аутентификации клиента по протоколу 3DS версии 2.0. |
|
AN..512 | Нет |
Адрес для отправки уведомления о прохождении проверки 3D Secure. Параметр используется при проведения аутентификации клиента по протоколу 3DS версии 2.0. |
Параметры ответа:
Название | Тип | Обязательно | Описание |
---|---|---|---|
|
N..2 | Да |
Код ошибки. |
|
|
Нет |
|
|
ANS..* | Нет |
При успешном ответе. Результат попытки оплаты. Возможные значения представлены ниже.
|
|
ANS..* | Нет |
При успешном ответе. В случае платежа без необходимости аутентификации на ACS – URL, на который производится переадресация после платежа. В случае 3DS-платежа – URL для возврата с ACS. |
|
AN..512 | Нет |
Адрес перенаправления на адрес сервера ACS. Не используется при платежах, не требующих дополнительной аутентификации на ACS Банка-эмитента. |
|
AN..512 | Нет |
Запрос аутентификации плательщика. Не используется при платежах, не требующих дополнительной аутентификации на ACS Банка-эмитента. |
При аутентификации по протоколу 3DS 2.0 при первичном запросе возвращаются следующие параметры:
Название | Тип | Обязательно | Описание |
---|---|---|---|
|
A..5 | Да |
Флаг, обозначающий то, что платёж/перевод будет проведён по протоколу 3DS версии 2.0. Доступны следующие значения:
Параметр используется при проведения аутентификации клиента по протоколу 3DS версии 2.0. |
|
ANS..36 | Да |
Идентификатор транзакции созданный на сервере 3DS. Параметр используется при проведения аутентификации клиента по протоколу 3DS версии 2.0. |
|
ANS..512 | Нет |
URL-адрес ACS для сбора данных о браузере. Параметр используется при проведения аутентификации клиента по протоколу 3DS версии 2.0. |
|
ANS..512 | Да |
URL-адрес сервера 3DS для сбора данных о браузере для включения в запрос аутентификации AReq (Authentication Request) от сервера 3DS к серверу ACS. Параметр используется при проведения аутентификации клиента по протоколу 3DS версии 2.0. |
|
ANS..1024 | Нет |
Данные CReq (Challenge Response) для отправки на сервер ACS, закодированные в Base64. Параметр используется при проведения аутентификации клиента по протоколу 3DS версии 2.0. |
|
ANS..512 | Нет |
URL-адрес на метод Параметр используется при проведения аутентификации клиента по протоколу 3DS версии 2.0. |
При аутентификации по протоколу 3DS 2.0 после повторного запроса на оплату и необходимости перенаправления клиента на ACS в ответе будут присутствовать следующие параметры.
Название | Тип | Обязательно | Описание |
---|---|---|---|
|
AN..512 | Да, в случае необходимости перенаправления на ACS |
Адрес перенаправления на адрес сервера ACS. |
|
ANS..* | Да, в случае необходимости перенаправления на ACS |
Запакованные данные challenge request. Это значение следует использовать как значение параметра |
Коды ошибок
Код ошибки | Текст ошибки |
---|---|
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>
Пример ответа на первый запрос:
<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" "is3DSVer2=true" "threeDSServerTransId="f44d6d21-1874-45a5-aeb0-1c710dd6e134" "threeDSMethodURLServer=https://test.com/3dsserver/gatherClientInfo?threeDSServerTransID=f44d6d21-1874-45a5-aeb0-1c710dd6e134"/> </ns1:paymentOrderResponse> </soap:Body> </soap:Envelope>
Пример повторного запроса:
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="?" "threeDSServerTransId=f44d6d21-1874-45a5-aeb0-1c710dd6e134" "threeDSVer2FinishUrl=https:test.com"> <!-Zero or more repetitions:-> <params name="name" value="value"/> </order> </mer:paymentOrder> </soapenv:Body> </soapenv:Envelope>
Пример ответа на повторный запрос:
<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="Ваш платёж обработан, происходит переадресация..." acsUrl"https://test.com/acs2/acs/creq" is3DSVer2=true packedCReq= "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjVmMzEyMjdlLTljZmQtNDQwYi1hNDNjLTE4NjljMzNhNGI5YiIsImFjc1RyYW5zSUQiOiI5YTQyYzQ4ZC1hNWRiLTQ3NjEtYmI4Mi05ZmY5MmM0NzZiM2QiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0="/> </ns1:paymentOrderResponse> </soap:Body> </soap:Envelope>
В случае неверной попытки оплаты шлюз возвращает следующий ответ.
<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&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>