Аутентификация 3‑D Secure

Обзор

Аутентификация пользователей с использованием протокола 3‑D Secure (Three-Domain Secure) предназначена для безопасного проведения интернет-оплат с использованием платёжных карт. Она может выполняться с применением различных способов проверки подлинности пользователей: например, через указание пользователем одноразового проверочного кода (One Time PIN, OTP), с помощью проверки отпечатка пальца пользователя на его мобильном устройстве или без каких-либо действий со стороны пользователя, на основе имеющейся информации о платеже и пользователе. При этом в разных случаях со стороны эмитентов могут поддерживаться различные способы проверки.

В аутентификации 3‑D Secure задействуются три домена:

• Домен эквайера. В рамках работы с платёжной платформой ecommpay к нему относятся веб-сервисы мерчантов, платёжная платформа и связанный с ней 3DS-сервер.
• Домен совместимости. К нему относятся серверы каталогов (Directory Servers, DS) международных платёжных систем.
• Домен эмитента. К нему относятся серверы управления доступом (Access Control Servers, ACS) эмитентов, а также страницы аутентификации, открываемые при обращениях к этим серверам.

Между этими доменами осуществляется обмен сообщениями, необходимыми для аутентификации пользователей. К таким сообщениям могут относиться запросы на проверку возможности проведения аутентификации (Verifying Enrolment Request, VEReq) и ответы на них (Verifying Enrolment Response, VERes), а также запросы на аутентификацию пользователя (Challenge Request, CReq) и ответы с информацией о результатах аутентификации (Challenge Response, CRes).

Следует учитывать, что информация о возможности аутентификации пользователя хранится на сервере управления доступом, и эту информацию можно получить только после отправки запроса на проведение платежа. Также со стороны веб-сервиса и платёжной платформы невозможно отслеживать действия пользователей на странице аутентификации — доступно только получение информации о результате аутентификации.

Варианты аутентификации

При работе с протоколом 3‑D Secure могут применяться два варианта аутентификации:

• Аутентификация без участия пользователя (frictionless flow). В этом случае личность пользователя подтверждается исходя из информации, которой располагает эмитент.
• Аутентификация с подтверждением пользователем своей личности (challenge flow). В этом случае подтверждение личности пользователя выполняется, например, с использованием одноразового кода или биометрических данных, если такая возможность поддерживается эмитентом.

Со стороны мерчанта выбрать требуемый вариант аутентификации нельзя — можно лишь указать предпочтение по такому выбору, но итоговое решение каждый раз принимается на стороне эмитента. Также, помимо указания предпочтений, в запросах на проведение платежей можно передавать ряд других необязательных параметров, применение которых может повышать вероятность выбора варианта аутентификации frictionless flow и, как следствие, способствовать повышению проходимости и улучшению пользовательского опыта. К базовому минимуму таких параметров можно отнести платёжный адрес пользователя (в параметрах объекта billing) и HTTP-заголовок User-Agent, полученный со стороны браузера (в параметре browser). Информация об этих и других параметрах представлена далее.

Базовая схема

В платёжной платформе информирование мерчанта о необходимости аутентификации 3‑D Secure осуществляется через оповещения, при приёме которых, как обычно при работе с платформой, необходимо отправлять ответы.

В базовой схеме оповещения о необходимости аутентификации содержат объект acs, и в качестве реагирования на такие оповещения необходимо перенаправить пользователя на страницу эмитента, принять сведения о результате аутентификации и отправить эти сведения в запросе на продолжение платежа. Время ожидания в платформе такого запроса составляет, как правило, 30 минут и измеряется с момента выявления необходимости аутентификации и до получения запроса от веб-сервиса. Если время ожидания истекло и запрос не принят — платёж автоматически отклоняется.

После поступления в платёжную платформу информации о результате аутентификации проведение платежа продолжается. В случае, если подключено каскадное проведение платежей, может понадобиться принять одно или несколько дополнительных оповещений о необходимости аутентификации 3‑D Secure. Если полученное оповещение содержит параметр cascading_with_redirect со значением true, необходимо:

• Отобразить пользователю страницу с сообщением об ошибке и получить его согласие на повторную аутентификацию.
• Отреагировать на оповещение необходимым способом.

Информацию о каскадном проведении платежей можно получить в соответствующей статье или у специалистов технической поддержки ecommpay.

Информация о форматах запросов и оповещений приведена далее; общая информация о работе с API — в разделе Организация взаимодействия.

Расширенная схема

В платёжной платформе информирование о необходимости аутентификации 3‑D Secure осуществляется через оповещения, при приёме которых необходимо отправлять ответы. Такое информирование не осуществляется только в тех случаях, когда со стороны эмитента принято решение об аутентификации пользователя без предоставления дополнительных сведений. В этих случаях со стороны веб-сервиса не требуется действий, отличных от стандартных при проведении платежа, а информация о результате аутентификации передаётся в итоговом оповещении.

При использовании расширенной схемы оповещение о необходимости аутентификации содержит объект iframe (в объекте threeds2). В качестве реагирования на это оповещение необходимо:

1. Отобразить пользователю элемента iframe с использованием данных из оповещения.
2. Принять от сервера управления доступом (ACS) эмитента уведомление о приёме данных и отправить в платёжную платформу запрос на инициирование аутентификации.
3. В случае выбора эмитентом варианта аутентификации frictionless flow — принять информацию о результате аутентификации, а в случае выбора варианта аутентификации challenge flow выполнить следущие действия:
   • принять от платёжной платформы оповещение с объектом redirect (в объекте threeds2) и отправить ответ о приёме этого оповещения;
   • перенаправить пользователя на страницу аутентификации в течение 30 секунд после приёма оповещения;
   • принять от эмитента данных о результате аутентификации;
   • отправить в платформу запрос на продолжение проведение платежа с учётом результата аутентификации (3ds_result) в течение 30 минут после выявления необходимости аутентификации.

После поступления в платёжную платформу информации о результате аутентификации проведение платежа продолжается. В случае, если подключено каскадное проведение платежей, может понадобиться принять одно или несколько дополнительных оповещений с объектом redirect. Если такое оповещение содержит параметр cascading_with_redirect со значением true, необходимо:

• Отобразить пользователю страницу с сообщением об ошибке и получить его согласие на повторную аутентификацию.
• Отреагировать на оповещение необходимым способом.

Информацию о каскадном проведении платежей можно получить в соответствующей статье или у специалистов технической поддержки support@ecommpay.com.

Информация о форматах оповещений и запросов, используемых в этой схеме, приведена в разделе Форматы промежуточных сообщений для расширенной схемы; общая информация о работе с Gate API — в статье Организация взаимодействия.

Независимо от используемой схемы аутентификации (базовой или расширенной) в любых запросах на проведение платежей рекомендуется передавать ряд необязательных параметров, поскольку это может повышать вероятность выбора варианта аутентификации frictionless flow, который не требует участия пользователя. К числу таких параметров, наряду с перечисленными далее сведениями о пользователе и платеже, относятся сведения об устройстве и браузере пользователя:

• Сведения об устройстве, определяемые на клиентской стороне веб-сервиса:
  • accept_header — значение HTTP-заголовка Accept;
  • accept_language_header — значение параметра Accept-Language, которое указывает предпочтения в языке локализации;
  • browser — значение HTTP-заголовка User-Agent;
  • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа.
• Сведения об устройстве, получаемые из запроса от используемого браузера к веб-сервису:
  • color_depth — глубина цвета используемого браузера, в битах на пиксель;
  • java_enabled — индикатор поддержки сценариев Java в используемом браузере;
  • js_enabled — индикатор поддержки сценариев JavaScript в используемом браузере;
  • language — код языка, выбранного для работы в используемом браузере;
  • screen_res — разрешение экрана используемого устройства, в пикселях и с символом x в качестве разделителя (например, 360x640);
  • timezone_name — название часового пояса, который актуален для используемого браузера (например, Europe/London);
  • timezone_offset — разница между временем для используемого браузера и UTC, в минутах (например, -120).

    "customer": {
    "ip_address": "188.113.253.90",
    "browser": "Mozilla/5.0 (Linux; Android 14; SM-A155F Build/UP1A.231005.007; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/138.0.7204.67 Mobile Safari/537.36",
    "screen_res": "384x832",
    "language": "en_US",
    "accept_header": "*/*",
    "accept_language_header": "en-GB,en;q=0.8,fr;q=0.3",
    "color_depth": 24,
    "java_enabled": false,
    "js_enabled": true,
    "timezone_offset": "-110"
  }

Со стороны веб-сервиса сбор таких сведений можно организовать следующим образом.

1. Определить сведения об устройстве пользователя в клиентской части веб-сервиса.

   function collectClientData() {
       return {
           // разрешение экрана устройства
           screen_res: `${screen.width}x${screen.height}`,
            
           // код языка, выбранного в браузере
           language: navigator.language,
            
           // глубина цвета браузера
           color_depth: screen.colorDepth,
            
           // индикатор поддержки сценариев Java в браузере
           java_enabled: navigator.javaEnabled(),
            
           // индикатор поддержки сценариев JavaScript в браузере
           js_enabled: true,
            
           // разница между временем для браузера и UTC
           timezone_offset: new Date().getTimezoneOffset().toString(),
       };
   }

2. Отправить собранные сведения из клиентской в серверную часть веб-сервиса.

   async function sendClientDataToServer(endpoint = '/api/collect-client-data') {
       try {
           const clientData = collectClientData();
             
           const response = await fetch(endpoint, {
               method: 'POST',
               headers: {
                   'Content-Type': 'application/json',
                   'Accept': '*/*'
               },
               body: JSON.stringify(clientData)
           });
             
           const result = await response.json();
           return result;
       } catch (error) {
           console.error('Ошибка отправки данных:', error);
           throw error;
       }
   }

3. Дополнить эти сведения полученными из запроса от браузера пользователя к веб-сервису, а также другими необходимыми для отправки запроса параметрами в серверной части веб-сервиса, сформировать подпись и отправить запрос на рабочий URL ecommpay.

   interface CustomerData
   {
       public function getIpAddress(): ?string;
    
       public function getAcceptHeader(): ?string;
    
       public function getAcceptLanguageHeader(): ?string;
    
       public function getScreenRes(): ?string;
    
       public function getBrowser(): ?string;
    
       public function getLanguage(): ?string;
    
       public function getColorDepth(): ?int;
    
       public function getJavaEnabled(): ?bool;
    
       public function getJsEnabled(): ?bool;
    
       public function getTimezoneOffset(): ?string;
   }
    
   interface CardData
   {
       public function getPan();
    
       public function getYear();
    
       public function getMonth();
    
       public function getCardHolder();
    
       public function getCvv();
   }
    
   interface PaymentData
   {
       public function getPaymentId(): string;
    
       public function getAmount(): int;
    
       public function getCurrency(): string;
    
       public function getCardData(): CardData;
    
       public function getCustomerData(): CustomerData;
   }
    
   interface HttpClient
   {
       public function sendRequest(array $request): bool;
   }
    
   interface Signer
   {
       public function sign(array $params): string;
   }
    
   final class PaymentController
   {
       public function __construct(
           private Signer $signer,
           private HttpClient $httpClient,
           private int $projectId,
       ) {}
    
       public function processPayment(PaymentData $paymentData): void
       {
           $paymentRequest = [
               'general' => [
                   'project_id' => $this->projectId,
                   'payment_id' => $paymentData->getPaymentId(),
               ],
               'customer' => $this->prepareCustomerData($paymentData->getCustomerData()),
               'payment' => [
                   'amount' => $paymentData->getAmount(),
                   'currency' => $paymentData->getCurrency(),
               ],
               'card' => [
                   'pan' => $paymentData->getCardData()->getPan(),
                   'year' => $paymentData->getCardData()->getYear(),
                   'month' => $paymentData->getCardData()->getMonth(),
                   'card_holder' => $paymentData->getCardData()->getCardHolder(),
                   'cvv' => $paymentData->getCardData()->getCvv(),
               ],
           ];
    
           $paymentRequest['general']['signature'] = $this->signer->sign($paymentRequest);
    
           $this->httpClient->sendRequest($paymentRequest);
       }
    
       private function prepareCustomerData(CustomerData $customerData): array
       {
           return array_filter([
               'ip_address' => $customerData->getIpAddress(),
               'browser' => $customerData->getBrowser(),
               'screen_res' => $customerData->getScreenRes(),
               'language' => $customerData->getLanguage(),
               'accept_header' => $customerData->getAcceptHeader(),
               'accept_language_header' => $customerData->getAcceptLanguageHeader(),
               'color_depth' => $customerData->getColorDepth(),
               'java_enabled' => $customerData->getJavaEnabled(),
               'js_enabled' => $customerData->getJsEnabled(),
               'timezone_offset' => $customerData->getTimezoneOffset(),
           ]);
       }
   }

   package main
    
   import "encoding/json"
    
   // CustomerData interface
   type CustomerData interface {
       GetIpAddress() *string
       GetAcceptHeader() *string
       GetAcceptLanguageHeader() *string
       GetScreenRes() *string
       GetBrowser() *string
       GetLanguage() *string
       GetColorDepth() *int
       GetJavaEnabled() *bool
       GetJsEnabled() *bool
       GetTimezoneOffset() *string
   }
    
   // CardData interface
   type CardData interface {
       GetPan() interface{}
       GetYear() interface{}
       GetMonth() interface{}
       GetCardHolder() interface{}
       GetCvv() interface{}
   }
    
   // PaymentData interface
   type PaymentData interface {
       GetPaymentId() string
       GetAmount() int
       GetCurrency() string
       GetCardData() CardData
       GetCustomerData() CustomerData
   }
    
   // HttpClient interface
   type HttpClient interface {
       SendRequest(request map[string]interface{}) bool
   }
    
   // Signer interface
   type Signer interface {
       Sign(params map[string]interface{}) string
   }
    
   // PaymentController struct
   type PaymentController struct {
       signer     Signer
       httpClient HttpClient
       projectId  int
   }
    
   // NewPaymentController constructor
   func NewPaymentController(signer Signer, httpClient HttpClient, projectId int) *PaymentController {
       return &PaymentController{
           signer:     signer,
           httpClient: httpClient,
           projectId:  projectId,
       }
   }
    
   // ProcessPayment processes the payment
   func (pc *PaymentController) ProcessPayment(paymentData PaymentData) {
       cardData := paymentData.GetCardData()
    
       paymentRequest := map[string]interface{}{
           "general": map[string]interface{}{
               "project_id": pc.projectId,
               "payment_id": paymentData.GetPaymentId(),
           },
           "customer": pc.prepareCustomerData(paymentData.GetCustomerData()),
           "payment": map[string]interface{}{
               "amount":   paymentData.GetAmount(),
               "currency": paymentData.GetCurrency(),
           },
           "card": map[string]interface{}{
               "pan":         cardData.GetPan(),
               "year":        cardData.GetYear(),
               "month":       cardData.GetMonth(),
               "card_holder": cardData.GetCardHolder(),
               "cvv":         cardData.GetCvv(),
           },
       }
    
       // Add signature
       general := paymentRequest["general"].(map[string]interface{})
       general["signature"] = pc.signer.Sign(paymentRequest)
    
       // Send request
       pc.httpClient.SendRequest(paymentRequest)
   }
    
   // prepareCustomerData filters and prepares customer data
   func (pc *PaymentController) prepareCustomerData(customerData CustomerData) map[string]interface{} {
       result := make(map[string]interface{})
    
       if v := customerData.GetIpAddress(); v != nil {
           result["ip_address"] = *v
       }
       if v := customerData.GetBrowser(); v != nil {
           result["browser"] = *v
       }
       if v := customerData.GetScreenRes(); v != nil {
           result["screen_res"] = *v
       }
       if v := customerData.GetLanguage(); v != nil {
           result["language"] = *v
       }
       if v := customerData.GetAcceptHeader(); v != nil {
           result["accept_header"] = *v
       }
       if v := customerData.GetAcceptLanguageHeader(); v != nil {
           result["accept_language_header"] = *v
       }
       if v := customerData.GetColorDepth(); v != nil {
           result["color_depth"] = *v
       }
       if v := customerData.GetJavaEnabled(); v != nil {
           result["java_enabled"] = *v
       }
       if v := customerData.GetJsEnabled(); v != nil {
           result["js_enabled"] = *v
       }
       if v := customerData.GetTimezoneOffset(); v != nil {
           result["timezone_offset"] = *v
       }
    
       return result
   }

Следует учитывать, что представленные здесь примеры кода для работы со сведениями об устройстве пользователя носят информативный характер и не допускают их использования в прямом виде («как есть») без проверки и доработки на соответствие всем актуальным требованиям на стороне веб-сервиса, включая требования PCI DSS.

Общая информация

Формат запросов на проведение платежей не влияет на возможность выполнения аутентификации 3‑D Secure и должен соответствовать описанному в статье Организация взаимодействия. При этом для каждого запроса может быть актуальным свой набор параметров:

• в любом случае должны использоваться параметры, обязательные для соответствующего типа платежа (подробнее о них — в статьях о типах платежей);
• в случае применения расширенной схемы аутентификации дополнительно должны использоваться параметры, перечисленные далее как обязательные;
• в случае, когда предпочтителен вариант аутентификации frictionless flow (без участия пользователя), желательно передавать максимальное число параметров, которые перечислены далее как рекомендуемые;
• дополнительно могут использоваться любые другие параметры из числа допустимых для конкретного типа платежа.

Обязательные параметры

При использовании базовой схемы аутентификации, как и в случае с проверкой платёжных инструментов, в набор обязательных параметров входят только те параметры, которые обязательны для соответствующего типа платежа. В случае с оплатами с использованием расширенной схемы аутентификации в число обязательных дополнительно включаются следующие объекты и параметры.

Рекомендуемые параметры

Независимо от используемой схемы аутентификации (базовой или расширенной) в любых запросах на проведение платежей рекомендуется передавать ряд необязательных параметров, перечисленных далее в этом подразделе — поскольку это может повышать вероятность выбора варианта аутентификации frictionless flow, который не требует участия пользователя. Со стороны веб-сервиса можно передавать как полный, так и неполный набор таких параметров, с учётом наличия соответствующей информации. К базовому минимуму параметров, влияющих на решение эмитента о варианте аутентификации, при этом можно отнести платёжный адрес пользователя и сведения о его устройстве и браузере.

Формат оповещения о необходимости аутентификации

При использовании базовой схемы аутентификации от платёжной платформы к веб-сервису передаётся оповещение с данными для перенаправления пользователя. Оповещение передаётся в стандартном формате, описание которого представлено в разделе Работа с оповещениями.

Данные для перенаправления пользователя передаются в объекте acs. К таким данным относятся: сообщение CReq (в параметре pa_req) для направления запроса на прохождение аутентификации 3‑D Secure эмитенту, адрес страницы аутентификации (acs_url) и данные мерчанта в платёжной системе — Merchant Data (md).

"acs":{  
  "pa_req":"inLgICAiYWNzVHIDAtMDAwMDAwMDAwNHv5hu", // Сообщение CReq
  "acs_url":"https://example.com/ACS", // Адрес страницы для перенаправления
  "md":"eyJwdXJjaGFzZV9vcGVyYXRpb25faWRfaWJ9" // Данные мерчанта в платёжной системе
}

Формат запроса на перенаправление

Для перенаправления пользователя на страницу аутентификации или страницу провайдера необходимо направить запрос на адрес, полученный в оповещении о необходимости аутентификации. Это должен быть POST-запрос со следующими объектами и параметрами:

• action — адрес страницы, на которую необходимо перенаправить пользователя, полученный в параметре acs_url оповещения;
• PaReq — сообщение CReq, полученное в параметре pa_req оповещения;
• TermUrl — адрес для перенаправления пользователя к веб-сервису после аутентификации;
• MD — данные мерчанта в международной платёжной системе (Merchant Data), полученные в параметре md оповещения.

<form id="3dsform" action="https://example.com/ACS" method="post" enctype="application/
x-www-form-urlencoded">
    <input type="hidden" name="PaReq" value="inLgICAiYWNzVHIDAtMDAwMDAwMDAwNHv5hu" />
    <input type="hidden" name="TermUrl" value="http://example.com/termurl" />
    <input type="hidden" name="MD" value="eyJwdXJjaGFzZV9vcGVyYXRpb25faWRfaWJ9" />
</form>
<script type="text/javascript">
    setTimeout(function() {
        document.getElementById("3dsform").submit();
    }, 1000);
</script>

Для удобства можно воспользоваться готовым примером — Пример HTML-формы, — заменив параметры на актуальные для платежа.

Формат уведомления о результате аутентификации

Данные о результате аутентификации передаются к веб-сервису в параметре pares.

pares=eyJ4aWQiOiJNREF3TURBd01EQXdNREF5TkRBd01ERXhNVFU9IiwibWRTdGF0dXMiOjEsIm1kRXJyb3JNc2ciOiJBdXRoZW50aWNhdGVkIiwiZW5yb2xsbWVuU3RhdHVzIjpudWxsLCJhdXRoZW50aWNhdGlvblN0YXR1cyI6IlkiLCJjYXZ2IjoiUVVOVFJVMVZLMkI5UFV4MWFXRXBhMlJpTjJVPSIsImVjaSI6IjA1In0=

pares=eyJ4aWQiOiJNREF3TURBd01EQXdNREF5TkRBd01ERXhNVFk9IiwibWRTdGF0dXMiOjAsIm1kRXJyb3JNc2ciOiJOb3QgYXV0aGVudGljYXRlZCIsImVucm9sbG1lblN0YXR1cyI6bnVsbCwiYXV0aGVudGljYXRpb25TdGF0dXMiOiJOIiwiY2F2diI6IiIsImVjaSI6IiJ9

Формат запроса на продолжение платежа

Для продолжения проведения платежа с учётом результата аутентификации необходимо отправить в платёжную платформу POST-запрос к конечной точке /v2/payment/card/3ds_result. В этом запросе должны использоваться следующие объекты и параметры:

• general — объект, содержащий основные идентификационные сведения запроса:
  • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
  • payment_id — идентификатор платежа, уникальный в рамках проекта;
  • signature — подпись к данным запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
• pares — сведения о результате аутентификации 3‑D Secure, полученные в уведомлении.

Таким образом, корректный запрос на продолжение проведения платежа с учётом результата аутентификации 3‑D Secure должен содержать идентификаторы проекта и платежа, подпись и данные о результате аутентификации.

{
   "general": {
   "project_id": 42,
   "payment_id": "456789",
   "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
   },
   "pares": "ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMi
LAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlR
FNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1
N0YXR1cyIgOiAiWSIKfQ"
  // Сведения о результате аутентификации
}

Формат оповещения с данными для объекта iframe

При расширенной схеме аутентификации через Gate от платёжной платформы к веб-сервису могут передаваться оповещения с данными для формирования объекта iframe. Для этих оповещений используется стандартный формат, описание которого представлено в разделе Работа с оповещениями.

Оповещения с данными для формирования объекта iframe не передаются, если со стороны эмитента без использования данных об устройстве пользователя принято одно из следующих решений:

• Выполнить проверку пользователя с перенаправлением на страницу аутентификации (вариант challenge flow). В этом случае со стороны веб-сервиса необходимо принять и обработать оповещение с данными для перенаправления (подробнее — ниже).
• Аутентифицировать пользователя (вариант frictionless flow). В этом случае со стороны веб-сервиса необходимо принять и обработать оповещение о результате проведения платежа.

Следующий пример содержит данные для формирования объекта iframe. Эти данные необходимо использовать следующим образом: адрес из параметра url — в атрибуте action, а данные из других параметров — в тегах input.

{ 
  "threeds2":{ 
    "iframe":{ 
      "url":"https://example.com",
      "params":{
        "3DSMethodData":"eyAidGhyZWVNrkthelJSUFQwaWZYMCUzQ",
        "threeDSMethodData":"eyAidGhjNjMGQ4YWU4LTA2u0wyWmtObGRdwR"
      }
    }
  }
}

<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 от платёжной платформы к веб-сервису могут передаваться оповещения с данными для перенаправления пользователя на страницу аутентификации (ACS URL) эмитента. Оповещения передаются в стандартном формате, описание которого представлено в разделе Работа с оповещениями. Оповещения с данными для перенаправления пользователя на страницу аутентификации не передаются в случаях, если на стороне эмитента выбран вариант аутентификации frictionless flow. Вместо такого оповещения со стороны веб-сервиса необходимо принять и обработать оповещение о результате проведения платежа.

Следующий пример содержит данные для перенаправления пользователя на страницу аутентификации. Эти данные необходимо использовать следующим образом: адрес из параметра url — в атрибуте action, а данные из других параметров — в тегах input.

{ 
  "threeds2":{ 
    "redirect":{ 
      "url":"https://example.com/ACS",
      "params":{
        "creq":"ewogICAiYWNzVHJhbnNJCIDAtMDAwMDAwMDAwN2Q5Ip9",
        "threeDSSessionData":"240000549"
      }
    }
  }
}

<!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>

Формат уведомления о приёме данных об устройстве пользователя

При расширенной схеме аутентификации от сервера управления доступом (ACS) эмитента на URL веб-сервиса, указанный в запросе на проведение платежа (в параметре 3ds_notification_url), передаётся уведомление о приёме данных об устройстве пользователя. Это уведомление передаётся в формате эмитента.

threeDSServerTransID=3abd37b3-afa6-53cf-8000-000000006455

Формат запроса на инициирование аутентификации

При расширенной схеме аутентификации для инициирования аутентификации необходимо отправить в платёжную платформу POST-запрос к конечной точке /v2/payment/card/3ds_check_iframe. В запросе к этой конечной точке должны использоваться следующие объекты и параметры:

• general — объект, содержащий основные идентификационные сведения запроса:
  • project_id — идентификатор проекта, полученный от ecommpay;
  • payment_id — идентификатор платежа, уникальный в рамках проекта;
  • signature — подпись к данным запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
• threeds_completion_indicator — указатель получения уведомления о приёме данных в течение десяти секунд после открытия объекта iframe. Необходимо передать значение true при получении уведомления и значение false при его отсутствии в заданный период.

Таким образом, корректный запрос на инициирование аутентификации 3‑D Secure должен содержать идентификаторы проекта и платежа и подпись.

{ 
  "general":{ 
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
  "threeds_completion_indicator":true
}

Формат уведомления о результате аутентификации

При использовании расширенной схемы аутентификации через Gate данные о результате аутентификации передаются к веб-сервису в формате эмитента. Эти данные передаются в параметре cres уведомления.

cres=ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMiLAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ&threeDSSessionData=240000554

cres=ewogICAiYWNzUmVmZXJlbmNlTnVtYmVyIiA6ICJBQ1NFbXUyIiwKICAgImFjc1RyYW5zSUQiIDog%0D%0AIjAwMDAwMDAwLTAwMDUtNWE1YS04MDAwLTAxNmQzZTI2ZWU2YyIsCiAgICJtZXNzYWdlVHlwZSIg%0D%0AOiAiQ1JlcyIsCiAgICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICAidGhyZWVEU1NlcnZl%0D%0AclRyYW5zSUQiIDogIjhiMjM0Y2ZmLTkzNjAtNTc5Yy04MDAwLTAwMDAwMDAwMDlhNiIsCiAgICJ0%0D%0AcmFuc1N0YXR1cyIgOiAiTiIKfQ==&threeDSSessionData=240000622

Формат запроса на продолжение платежа

При базовой и расширенной схемах аутентификации через Gate для продолжения проведения платежа с учётом результата аутентификации необходимо отправить в платёжную платформу POST-запрос к конечной точке /v2/payment/card/3ds_result. В этом запросе должны использоваться следующие объекты и параметры:

• general — объект, содержащий основные идентификационные сведения запроса:
  • project_id — идентификатор проекта, полученный от ecommpay;
  • payment_id — идентификатор платежа, уникальный в рамках проекта;
  • signature — подпись к данным запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
• cres — данные о результате аутентификации 3‑D Secure, полученные в уведомлении от сервера управления доступом.

Таким образом, корректный запрос на продолжение проведения платежа с учётом результата аутентификации 3‑D Secure должен содержать идентификаторы проекта и платежа, подпись и данные о результате аутентификации.

{
   "general": {
   "project_id": 42,
   "payment_id": "456789",
   "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
   },
   "cres": "ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMi
LAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlR
FNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1
N0YXR1cyIgOiAiWSIKfQ"
  // Данные о результате аутентификации
}