Форматы промежуточных сообщений
В зависимости от используемой схемы аутентификации при работе через Gate могут быть актуальны промежуточные сообщения, описания форматов которых представлены далее.
Формат оповещения с данными для объекта iframe
При расширенной схеме аутентификации через Gate от платёжной платформы к веб-сервису могут передаваться оповещения с данными для формирования объекта iframe. Для этих оповещений используется стандартный формат, описание которого представлено в разделе Оповещения.
Оповещения с данными для формирования объекта iframe не передаются, если со стороны эмитента без использования данных об устройстве пользователя принято одно из следующих решений:
- Выполнить проверку пользователя с перенаправлением на страницу аутентификации (вариант challenge flow). В этом случае со стороны веб-сервиса необходимо принять и обработать оповещение с данными для перенаправления (подробнее — ниже).
- Аутентифицировать пользователя (вариант frictionless flow). В этом случае со стороны веб-сервиса необходимо принять и обработать оповещение о результате проведения платежа.
Следующий пример содержит данные для формирования объекта iframe. Эти данные необходимо использовать следующим образом: адрес из параметра url
— в атрибуте action
, а данные из других параметров — в тегах input
.
Рис.: Пример данных для формирования объекта iframe
{ "threeds2":{ "iframe":{ "url":"https://example.com", "params":{ "3DSMethodData":"eyAidGhyZWVNrkthelJSUFQwaWZYMCUzQ", "threeDSMethodData":"eyAidGhjNjMGQ4YWU4LTA2u0wyWmtObGRdwR" } } } }
Рис.: Пример разметки HTML-страницы для объекта iframe
<iframe id="tdsMmethodTgtFrame" name="tdsMmethodTgtFrame" style="width: 1px; height: 1px; display: none;" src="javascript:false;" xmlns="http://example.com/xhtml"> <!--.--> </iframe> <form id="tdsMmethodForm" name="tdsMmethodForm" action="https://example.com" method="post" target="tdsMmethodTgtFrame" xmlns="http://example.com/xhtml"> <input type="hidden" name="3DSMethodData" value="eyAidGhyZWVNrkthelJSUFQwaWZYMCUzQ" /> <input type="hidden" name="threeDSMethodData" value="eyAidGhjNjMGQ4YWU4LTA2u0wyWmtObGRdwR" /> </form> <script type="text/javascript" xmlns="http://example.com/xhtml"> document.getElementById("tdsMmethodForm").submit(); </script>
Форматы оповещений с данными для перенаправления
Формат оповещения для аутентификации по базовой схеме
При использовании базовой схемы аутентификации через Gate от платёжной платформы к веб-сервису передаётся оповещение с данными для перенаправления пользователя. Оповещение передаётся в стандартном формате, описание которого представлено в разделе Оповещения.
В следующем примере данные из оповещения свидетельствуют о том, что для платёжной карты № 424242******4243
пользователя customer_12
поддерживается аутентификация 3‑D Secure 2 и необходимо перенаправить пользователя на страницу ожидания платёжной платформы. Оповещение содержит объект acs
с необходимыми для этого данными: сообщением PAReq, адресом страницы ожидания платёжной платформы и данными мерчанта в платёжной системе.
Рис.: Пример данных для перенаправления
{ "project_id":42, "customer":{ "id":"customer_12" }, "payment":{ "id":"456789", "type":"purchase", "status":"awaiting 3ds result", "date":"2019-07-19T06:21:40+0000", "method":"card", "sum":{ "amount":10000, "currency":"EUR" }, "description":"" }, "account":{ "number":"424242******4243", "type":"visa", "card_holder":"JOHN JONSON", "expiry_month":"08", "expiry_year":"2025" }, "operation":{ "id":13002103, "type":"auth", "status":"awaiting 3ds result", "date":"2019-07-19T06:21:40+0000", "created_date":"2019-07-19T06:21:37+0000", "request_id":"e2fd233d27c064fbe01af291039e6478341a0489-3...9", "sum_initial":{ "amount":10000, "currency":"EUR" }, "sum_converted":{ "amount":10000, "currency":"EUR" }, "provider":{ "id":414, "payment_id":"", "result_code":"0", "result_message":"", "endpoint_id":414 }, "code":"9999", "message":"Awaiting processing", "description":"", "eci":"07" }, "acs":{ "pa_req":"inLgICAiYWNzVHIDAtMDAwMDAwMDAwNHv5hu", // Сообщение PAReq "acs_url":"https://example.com/ACS", // Адрес страницы ожидания платёжной платформы "md":"eyJwdXJjaGFzZV9vcGVyYXRpb25faWRfaWJ9" // Данные мерчанта в платёжной системе }, "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }
Формат оповещений для аутентификации по расширенной схеме
При использовании расширенной схемы аутентификации через Gate от платёжной платформы к веб-сервису могут передаваться оповещения с данными для перенаправления пользователя на страницу аутентификации (ACS URL) эмитента. Оповещения передаются в стандартном формате, описание которого представлено в разделе Оповещения. Оповещения с данными для перенаправления пользователя на страницу аутентификации не передаются в случаях, если на стороне эмитента выбран вариант аутентификации frictionless flow. Вместо такого оповещения со стороны веб-сервиса необходимо принять и обработать оповещение о результате проведения платежа.
Следующий пример содержит данные для перенаправления пользователя на страницу аутентификации. Эти данные необходимо использовать следующим образом: адрес из параметра url
— в атрибуте action
, а данные из других параметров — в тегах input
.
Рис.: Пример данных для перенаправления пользователя
{ "threeds2":{ "redirect":{ "url":"https://example.com/ACS", "params":{ "creq":"ewogICAiYWNzVHJhbnNJCIDAtMDAwMDAwMDAwN2Q5Ip9", "threeDSSessionData":"240000549", "TermUrl":"http://example.com/termurl" } } } }
Рис.: Пример разметки HTML-страницы для перенаправления пользователя
<!DOCTYPE html SYSTEM "about:legacy-compat"> <html class="no-js" lang="en" xmlns="http://example.com/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta charset="utf-8" /> <title>3D Secure Processing</title> <link href="https://example.com/mpi.css" rel="stylesheet" type="text/css" /> </head> <body> <div id="main"> <div id="content"> <div id="order"> <h2>3D Secure Processing</h2> <img src="https://example.com/preloader.gif" alt="Please wait.." /> <img src="https:// example.com/verifiedbyvisa.png" alt="Verified by VISA" /> <div id="formdiv"> <script type="text/javascript"> function hideAndSubmitTimed(formid) { timer=setTimeout("hideAndSubmit('"+formid+"');", 100);} function hideAndSubmit(formid) { var formx=document.getElementById(formid); tif (formx!=null) { formx.style.visibility="hidden"; formx.submit(); } } </script> <div> <form id="webform0" name="red2ACSv2" method="POST" action="https:// example.com/ACS" accept_charset="UTF-8"> <input type="hidden" name="_charset_" value="UTF-8" /> <input type="hidden" name="creq" value="ewogICAiYWNzVHJhbnNJCIDAtMDAwMDAwMDAwN2Q5Ip9" /> <input type="hidden" name="threeDSSessionData" value="240000476" /> <input type="hidden" name="TermUrl" value="http://example.com/termurl" /> <input type="submit" name="submitBtn" value="Please click here to continue" /> </form> </div> </div> <script type="text/javascript"> thideAndSubmitTimed('webform0'); </script> <noscript> <div align="center"> <b>Javascript is turned off or not supported!</b> <br/> </div> </noscript> </div> </div> </div> </body> </html>
Формат уведомления о приёме данных об устройстве пользователя
Если в запросе на проведение платежа передан параметр 3ds_notification_url
, то при расширенной схеме аутентификации через Gate от сервера управления доступом (ACS) эмитента к веб-сервису передаётся уведомление о приёме данных об устройстве пользователя (в формате эмитента), если нет — это уведомление передаётся к платёжной платформе.
Рис.: Пример идентификатора операции на стороне 3DS-сервера
threeDSServerTransID=3abd37b3-afa6-53cf-8000-000000006455
Формат запроса на инициирование аутентификации
Если в запросе на проведение платежа передан параметр 3ds_notification_url
, при расширенной схеме аутентификации через Gate для инициирования аутентификации необходимо отправить в платёжную платформу POST-запрос к конечной точке /v2/payment/card/3ds_check_iframe, если нет — инициирование аутентификации выполняется на стороне платформы. В запросе к этой конечной точке должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ECommPay при интеграции;payment_id
— идентификатор платежа, уникальный в рамках проекта;signature
— подпись к данным запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
threeds_completion_indicator
— указатель получения уведомления о приёме данных в течение десяти секунд после открытия объекта iframe. Необходимо передать значениеtrue
при получении уведомления и значениеfalse
при его отсутствии в заданный период.
Таким образом, корректный запрос на инициирование аутентификации 3‑D Secure 2 должен содержать идентификаторы проекта и платежа и подпись.
Рис.: Пример набора данных в запросе на инициирование аутентификации
{ "general":{ "project_id":42, "payment_id":"456789", "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "threeds_completion_indicator":true }
Формат уведомления о результате аутентификации
Формат уведомления для аутентификации по базовой схеме
При использовании базовой схемы аутентификации через Gate данные о результате аутентификации передаются к веб-сервису в формате платёжной платформы. Как и при аутентификации 3‑D Secure 1, данные о результате аутентификации передаются в параметре pares
, однако для 3‑D Secure 2 используется другой формат этих данных.
Рис.: Пример данных об успешном прохождении аутентификации по базовой схеме
pares=eyJ4aWQiOiJNREF3TURBd01EQXdNREF5TkRBd01ERXhNVFU9IiwibWRTdGF0dXMiOjEsIm1kRXJyb3JNc2ciOiJBdXRoZW5
0aWNhdGVkIiwiZW5yb2xsbWVuU3RhdHVzIjpudWxsLCJhdXRoZW50aWNhdGlvblN0YXR1cyI6IlkiLCJjYXZ2I
joiUVVOVFJVMVZLMkI5UFV4MWFXRXBhMlJpTjJVPSIsImVjaSI6IjA1In0=
Рис.: Пример данных об ошибке при прохождении аутентификации по базовой схеме
pares=eyJ4aWQiOiJNREF3TURBd01EQXdNREF5TkRBd01ERXhNVFk9IiwibWRTdGF0dXMiOjAsIm1kRXJyb3JNc2ciOiJOb3QgYXV 0aGVudGljYXRlZCIsImVucm9sbG1lblN0YXR1cyI6bnVsbCwiYXV0aGVudGljYXRpb25TdGF0dXMiOiJOIiwiY 2F2diI6IiIsImVjaSI6IiJ9
Формат уведомления для аутентификации по расширенной схеме
При использовании расширенной схемы аутентификации через Gate данные о результате аутентификации передаются к веб-сервису в формате эмитента. Эти данные передаются в параметре cres
уведомления.
Рис.: Пример данных об успешном прохождении аутентификации по расширенной схеме
cres=ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMiLAogICJtZXNzYWdlVHl
wZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFu
c0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1N0YXR1cyIgO
iAiWSIKfQ&threeDSSessionData=240000554
Рис.: Пример данных об ошибке при прохождении аутентификации по расширенной схеме
cres=ewogICAiYWNzUmVmZXJlbmNlTnVtYmVyIiA6ICJBQ1NFbXUyIiwKICAgImFjc1RyYW5zSUQiIDog%0D%0AIjAwMDAwMDA wLTAwMDUtNWE1YS04MDAwLTAxNmQzZTI2ZWU2YyIsCiAgICJtZXNzYWdlVHlwZSIg%0D%0AOiAiQ1JlcyIsCi AgICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICAidGhyZWVEU1NlcnZl%0D%0AclRyYW5zSUQiIDogI jhiMjM0Y2ZmLTkzNjAtNTc5Yy04MDAwLTAwMDAwMDAwMDlhNiIsCiAgICJ0%0D%0AcmFuc1N0YXR1cyIgOiAi TiIKfQ==&threeDSSessionData=240000622
Формат запроса на продолжение проведения платежа
При базовой и расширенной схемах аутентификации через Gate для продолжения проведения платежа с учётом результата аутентификации необходимо отправить в платёжную платформу POST-запрос к конечной точке /v2/payment/card/3ds_result. В этом запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ECommPay при интеграции;payment_id
— идентификатор платежа, уникальный в рамках проекта;signature
— подпись к данным запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
- При базовой схеме: параметр
pares
с данными о результате аутентификации 3‑D Secure 2, полученными в уведомлении от платёжной платформы. - При расширенной схеме: параметр
cres
с данными о результате аутентификации 3‑D Secure 2, полученными в уведомлении от сервера управления доступом.
Таким образом, корректный запрос на продолжение проведения платежа с учётом результата аутентификации 3‑D Secure 2 должен содержать идентификаторы проекта и платежа, подпись и данные о результате аутентификации.
Рис.: Пример набора данных в запросе на продолжение проведения платежа
{ "general": { "project_id": 42, "payment_id": "456789", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "cres": "ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMi LAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlR FNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1 N0YXR1cyIgOiAiWSIKfQ" // Данные о результате аутентификации }