Форматы промежуточных сообщений

В зависимости от используемой схемы аутентификации при работе через 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"
      }
    }
  }
}

Рис.: Пример разметки 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="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"
  // Данные о результате аутентификации
}