3‑D Secure authentication

General information

3‑D Secure (Three-Domain Secure) customer authentication is aimed to increase secure processing of online card payments. This authentication procedure can be carried out in a variety of ways: the customer may be required to provide a one-time PIN (OTP) code to confirm their identity, the customer's fingerprint may be verified on their device, or the customer's involvement may be bypassed altogether based on the payment and customer data. The choice of the authentication mechanism is decided on a case-by-case basis.

3‑D Secure involves the interaction of three domains:

• Acquirer domain: in the context of the ecommpay payment platform interoperability, it includes the merchant's web service, the payment platform and its 3DS Server (or the Merchant Plug-In (MPI) Server), as well as the provider if it is involved in the authentication process.
• Interoperability domain: it includes the Directory Servers (DS) of global card schemes.
• Issuer domain: it includes the issuer's Access Control Servers (ACS) and, consequently, the authentication page.

The domains exchange messages that are required to authenticate the customer. These messages include the request to determine whether a certain cardholder can be authenticated (Verifying Enrolment Request, VEReq) and the corresponding response (Verifying Enrolment Response, VERes) as well as the customer authentication request (Challenge Request, CReq, or Payer Authentication Request, PAReq) and the response containing the authentication result (Challenge Response, CRes, or Payer Authentication Response, PARes).

Note that the information about the possibility of customer authentication and the protocol version is stored on the Access Control Server, and therefore this information can be obtained only after a payment request has been sent. Moreover, the web service and the payment platform do not have control over customer actions on the authentication page; they can only receive the authentication result.

3‑D Secure authentication flows

3‑D Secure supports the following authentication flows:

• Frictionless flow—authentication that does not involve interaction with the customer. This flow is supported only in the second version of the protocol. Frictionless authentication helps increase acceptance rates and enhances customer experience.
• Challenge flow—authentication that requires the customer to perform certain actions in order to confirm their identity. While this flow is supported in both versions of the protocol, the term challenge flow was coined specifically for 3‑D Secure 2. However, the mechanism of this flow corresponds to the traditional 3‑D Secure 1 authentication flow with minor variations. Customers can be authenticated with the use of one-time code or biometric data if this capability is supported by the issuer.

The merchant cannot select the authentication flow. While the merchant can indicate which flow selection is preferable, the final decision is made by the issuer. In addition to specifying the preferred flow, the merchant can pass a range of optional parameters in the request for opening the payment form which increases the possibility of the frictionless flow selection. The information about these parameters is provided in the sections that follow.

Authentication workflows in the payment platform

In the ecommpay payment platform, the 3‑D Secure authentication is implemented in the processing of one-step and two-step purchases made with cards and card verification requests. Along with that, two authentication workflows are available: basic, used by default, and extended, implemented upon the merchant's request. The latter is supported only for 3‑D Secure 2 and can be relevant when monitoring each step of the authentication procedure is necessary for the merchant's operation.

This article provides a detailed description of the authentication workflows mentioned above.

Basic workflow

Communicating the need for the 3‑D Secure authentication is carried out via callbacks. Your web service is expected to respond to these callbacks the same way it responds to any other callbacks received from the payment platform.

Basic authentication workflow implies that the callback communicating the need for authentication contains either the acs object (if the provider is not involved in the authentication process), or the redirectData object (if the provider is involved). Responding to such callbacks requires the following:

• In the basic workflow without provider involvement, you need to redirect the customer to the issuer's ACS page, accept the authentication result, and send the payment completion request with the result to the payment platform. Note that after the payment platform establishes the need for authentication, it waits for the payment completion request with the authentication result from the web service; as a rule, the waiting time is 30 minutes. If the payment platform does not receive the request with the authentication result within the waiting time, the payment is automatically declined.
• In the basic workflow with provider involvement, you need to redirect the customer to the page hosted by the provider. After that, your web service is not required to perform any other actions. For more information about this kind of authentication, refer to your ecommpay account manager.

When you submit the authentication result, the payment platform continues payment processing. If the cascading payments option is enabled, the platform may request the 3‑D Secure authentication in one or more additional callbacks. If the additional callback contains the cascading_with_redirect parameter that is set to true, your web service is required to do the following:

• Display an error message to a customer on a page and obtain their consent to re-authenticate.
• Respond to the callback accordingly (depends on whether the callback contains the acs or the redirectData object).

For more information about additional callbacks, see Cascade payment processing or contact the technical support specialists at support@ecommpay.com.

Information about the format of requests and callbacks is provided in the sections that follow. General information about using the Gate API can be found in Interaction concepts.

Extended workflow

Similar to the basic workflow, the extended workflow implies that communicating the need for the 3‑D Secure authentication is carried out via callbacks. Your web service is expected to respond to these callbacks the same way it responds to any other callbacks received from the payment platform. However, there is no authentication-specific communication when the issuer makes the decision not to request any additional data while implementing the frictionless flow. In this case, the web service is not required to perform any actions other than those implied by the standard payment processing workflow while the authentication result is passed in the final callback.

The callback communicating the need for authentication contains the iframe object (in the threeds2 object). Responding to such callbacks requires your web service to do the following:

1. Using the data received in the callback, display the iframe element to the customer.
2. If the initial payment request contains the 3ds_notification_url parameter, the web service is required to accept the acknowledgement message from the issuer's Access Control Server and send the authentication initiation request to the payment platform. If the 3ds_notification_url parameter has not been passed, this step is skipped.
3. If the issuer decides to use the frictionless flow, the web service is required to accept a callback with the authentication result from the payment platform. If the issuer selects the challenge flow, the web service is required to complete the following steps:
   • Accept a callback from the payment platform with the redirect object (in the threeds2 object) and respond with the callback acknowledgement.
   • Redirect the customer to the authentication page within 30 seconds after the callback was received.
   • Accept the authentication result from the issuer.
   • Send a payment completion request with the authentication result in the 3ds_result parameter to the payment platform within 30 minutes after the need for authentication was determined.

Information about the format of callbacks and requests used in the extended workflow can be found in Format of intermediate messages for extended workflow. General information about using the Gate API is provided in Interaction concepts.

Callback format when authentication is needed

When the basic authentication flow is used, the callback containing the data for redirecting the customer is sent from the payment platform to the web service. These callbacks are arranged in a standard format described in greater detail in the following article. The redirection data is passed in one of the two objects: acs (if the provider is not involved in the authentication process) or redirectData (if the provider is involved).

The acs object of the callback contains the following data: the PAReq message (in the pa_req parameter) to send the authentication initiation request to the issuer, the URL of the authentication page (acs_url), and the merchant data kept on file by the card scheme (md).

"acs":{  
  "pa_req":"inLgICAiYWNzVHIDAtMDAwMDAwMDAwNHv5hu", // PAReq message
  "acs_url":"https://example.com/ACS", // ACS page URL to redirect the customer to
  "md":"eyJwdXJjaGFzZV9vcGVyYXRpb25faWRfaWJ9" // Merchant data kept on file by the card scheme
}

The redirectData object of the callback contains the following data: the body of the request (body), the HTTP method of the request (method), and the URL of the provider (url).

"redirectData":{
  "method":"GET", // HTTP method of the request
  "body":[  ], // Request body (can be empty)
  "encrypted": [  ],
  "url":"https://example.com/..."
}

Format of the redirection request

To redirect the customer to the issuer's ACS page or the provider's page, send the request to the URL received in the callback that signals the need for authentication. Depending on what is included in the redirection data, use a POST or GET method and include the following objects and parameters:

• If the received callback contains the acs object:
  • action—the URL of the ACS page to redirect the customer to, sourced from the acs_url parameter of the callback.
  • PaReq—a PAReq message sourced from the pa_req parameter of the callback.
  • TermUrl—the URL of the web service to redirect the customer to after the authentication procedure has been completed.
  • MD—information about the merchant kept on file by the global card scheme, sourced from the md parameter of the callback.

  Use the POST HTTP method.

• If the received callback contains the redirectData object:
  • action—the URL of the provider, sourced from the url parameter of the callback.
  • method—the HTTP method of the request.
  • body—the body of the request if it was received in the callback.

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

For your convenience, here is a ready-made HTML file that you can use by replacing the sample code with the actual payment parameters.

Format of the message with the authentication result

The message with the authentication result is sent to the web service in the pares parameter.

pares=eyJ4aWQiOiJNREF3TURBd01EQXdNREF5TkRBd01ERXhNVFU9IiwibWRTdGF0dXMiOjEsIm1kRXJyb3JNc2ciOiJBdXRoZW5
            0aWNhdGVkIiwiZW5yb2xsbWVuU3RhdHVzIjpudWxsLCJhdXRoZW50aWNhdGlvblN0YXR1cyI6IlkiLCJjYXZ2I
            joiUVVOVFJVMVZLMkI5UFV4MWFXRXBhMlJpTjJVPSIsImVjaSI6IjA1In0=

pares=eyJ4aWQiOiJNREF3TURBd01EQXdNREF5TkRBd01ERXhNVFk9IiwibWRTdGF0dXMiOjAsIm1kRXJyb3JNc2ciOiJOb3QgYXV
            0aGVudGljYXRlZCIsImVucm9sbG1lblN0YXR1cyI6bnVsbCwiYXV0aGVudGljYXRpb25TdGF0dXMiOiJOIiwiY
            2F2diI6IiIsImVjaSI6IiJ9

Format of the payment completion request

To resume processing of the payment once the authentication procedure has been completed, send a request to the /v2/payment/card/3ds_result endpoint using the POST HTTP method. The request must contain the following objects and parameters:

• general—the object containing the general identification information of the request:
  • project_id—the project identifier obtained from ecommpay.
  • payment_id—the payment identifier unique within the merchant project.
  • signature—the request signature generated after all required parameters have been specified. For more information about signature generation, see Signature generation and verification.
• pares—the parameter containing the customer's 3‑D Secure authentication result sourced from the PARes message.

Thus, a correct request for payment completion following the 3‑D Secure authentication contains project and payment identifiers, the signature, and the authentication result.

{
   "general": {
   "project_id": 42,
   "payment_id": "456789",
   "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
   },
   "pares": "ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMi
LAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlR
FNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1
N0YXR1cyIgOiAiWSIKfQ"  // Authentication result information
}

Format of the callback with iframe data

When the extended authentication flow via Gate is used, the callback containing the data for an iframe element is sent from the payment platform to the web service. These callbacks are arranged in a standard format described in greater detail in the following article.

The payment platform does not send callbacks with iframe data when the issuer decides to use either of the following options without factoring in the customer's device information:

• the challenge flow: the customer is redirected to the authentication page for verification. In this case, your web service is required to accept and process the callback with the redirection data. For more information, see below.
• the frictionless flow: the issuer authenticates the customer. In this case, your web service is required to accept and process the callback with the payment result.

The following example contains data for creating an iframe element. Use the value of the url parameter from the iframe data as the value of the action attribute and specify the values of other parameters inside the corresponding input tags of the iframe code.

{ 
  "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>

Callback format when authentication is needed

When the extended authentication flow via Gate is used, the callback containing the data for redirecting the customer to the issuer's ACS page is sent from the payment platform to the web service. These callbacks are arranged in a standard format described in greater detail in the following article. If the issuer decides to use the frictionless flow, the payment platform does not send callbacks with the customer redirection data. In this case, your web service is required to accept and process the callback with the payment result.

The following example contains data for redirecting the customer to the authentication page. Use the value of the url parameter as the value of the action attribute, and specify the values of other parameters inside the corresponding input tags of the HTML code.

{ 
  "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>

Format of the message acknowledging the receipt of the customer's device information

If the initial payment request contains the 3ds_notification_url parameter, in the extended authentication workflow via Gate, the issuer's Access Control Server sends a message with an acknowledgement of receiving the customer's device data (arranged in the format chosen by the issuer). Otherwise, the ACS sends this message to the payment platform.

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

Format of the authentication initiation request

When you use the extended authentication workflow via Gate and specify the 3ds_notification_url parameter in the initial payment request, you initiate the authentication by sending a HTTP POST request to the /v2/payment/card/3ds_check_iframe endpoint. If you do not specify the parameter, the payment platform initiates the authentication. The request must contain the following objects and parameters:

• general—the object containing the general identification information of the request:
  • project_id—the project identifier obtained from ecommpay.
  • payment_id—the payment identifier unique within the merchant project.
  • signature—the request signature generated after all required parameters have been specified. For more information about signature generation, see Signature generation and verification.
• threeds_completion_indicator—the parameter that indicates whether the message acknowledging the receipt of the customer's device information was received within 10 seconds after the iframe element was closed. If the acknowledgement was received within 10 seconds, pass true; if not, pass false.

Thus, a correct request for the 3‑D Secure authentication initiation contains a project identifier, a payment identifier, and a signature.

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

Format of the message with the authentication result

When the extended authentication flow via Gate is used, the authentication result is sent to the web service in the format chosen by the issuer. This information is passed in the cres parameter contained in the message.

cres=ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMiLAogICJtZXNzYWdlVHl
             wZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFu
             c0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1N0YXR1cyIgO
             iAiWSIKfQ&threeDSSessionData=240000554

cres=ewogICAiYWNzUmVmZXJlbmNlTnVtYmVyIiA6ICJBQ1NFbXUyIiwKICAgImFjc1RyYW5zSUQiIDog%0D%0AIjAwMDAwMDA
             wLTAwMDUtNWE1YS04MDAwLTAxNmQzZTI2ZWU2YyIsCiAgICJtZXNzYWdlVHlwZSIg%0D%0AOiAiQ1JlcyIsCi
             AgICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICAidGhyZWVEU1NlcnZl%0D%0AclRyYW5zSUQiIDogI
             jhiMjM0Y2ZmLTkzNjAtNTc5Yy04MDAwLTAwMDAwMDAwMDlhNiIsCiAgICJ0%0D%0AcmFuc1N0YXR1cyIgOiAi
             TiIKfQ==&threeDSSessionData=240000622

Format of the payment completion request

Both the basic and the extended authentication flows via Gate imply that to resume processing of the payment once the authentication procedure has been completed, you have to send a request to the /v2/payment/card/3ds_result endpoint using the POST HTTP method. The request must contain the following objects and parameters:

• general—the object containing the general identification information of the request:
  • project_id—the project identifier obtained from ecommpay .
  • payment_id—the payment identifier unique within the merchant project.
  • signature—the request signature generated after all required parameters have been specified. For more information about signature generation, see Signature generation and verification.
• cres—the parameter containing the customer's 3‑D Secure authentication result sent in the message from the Access Control Server.

Thus, a correct request for payment completion following the 3‑D Secure authentication contains project and payment identifiers, the signature, and the authentication result.

{
   "general": {
   "project_id": 42,
   "payment_id": "456789",
   "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
   },
   "cres": "ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMi
LAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlR
FNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1
N0YXR1cyIgOiAiWSIKfQ"  // Authentication result data
}