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.
• Interoperability domain: it includes the Directory Servers (DS) of global card schemes.
• Issuer domain: it includes the issuer's Access Control Servers (ACS) and 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) and the response containing the authentication result information (Challenge Response, CRes).

Note that the information about the possibility of customer authentication and the protocol version is stored on the Access Control Server, and 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 information.

3‑D Secure authentication flows

3‑D Secure supports the following authentication flows:

• Frictionless flow—authentication that does not involve interaction with the customer. Customers are authenticated with the use of data that the issuer already has.
• Challenge flow—authentication that requires the customer to perform certain actions in order to confirm their identity. Customers can be authenticated with the use of one-time code or biometric data if this capability is supported by the issuer, for example.

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 payment request which increases the possibility of the frictionless flow selection and thereby helps increase acceptance rates and enhances customer experience. Most frequently used optional parameters include the customer's billing address (parameters passed in the billing object) and the User-Agent HTTP header received from the browser (the browser parameter). Information about these and other parameters can be found below.

Basic workflow

In the payment platform, communicating the need for the 3‑D Secure authentication to merchants 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 the acs object. To respond to such callbacks, 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 once the need for authentication is established, the payment platform 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.

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.

For more information, 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

In the payment platform, 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.

In the extended workflow, 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. Accept the acknowledgement message from the issuer's Access Control Server and send the authentication initiation request to the payment platform.
3. If the issuer decides to use the frictionless flow, the web service is required to accept a callback with the authentication result information 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.

When you submit the authentication result, the payment platform continues payment processing. If the cascading payments option is enabled, your web service may need to accept one or more additional callbacks with the redirect object. 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.

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

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.

Overview

Overall, the format of the payment request does not affect the probability of whether the authentication is going to be triggered and should conform to the standard described in Interaction concepts. Similarly, the required parameters used for a certain payment should align with the parameter sets described in the articles about corresponding payment types and should also include the screen resolution of the customer's device (screen_res), the customer's email (email) and phone number (phone). In addition, in case of the extended authentication workflow, the parameters should contain the acs_return_url object with the web service URLs for redirecting the customer to the web service and for accepting acknowledgement from the issuer.

However, it is also recommended that you pass such optional parameters as additional payment data (for example, the preferred authentication flow and selected shipping method) and information about the customer (for example, the customer's billing address) to increase the possibility of the issuer's selecting the frictionless flow that bypasses interaction with the customer altogether. The merchant web service can pass all of these parameters or only some of them. Most frequently used optional parameters include the customer's billing address (parameters passed in the billing object) and the User-Agent HTTP header received from the browser (in the browser parameter).

Required parameters

In the extended workflow, required parameters must include the acs_return_url object that contains the following data:

Optional parameters

Both in basic and extended workflows, use the following optional parameters to pass payment and customer data in the payment requests:

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 the acs object. The acs object of the callback contains the following data: the CReq 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", // CReq 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
}

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. Use a POST method and include the following objects and parameters

• action—the URL of the ACS page to redirect the customer to, sourced from the acs_url parameter of the callback.
• PaReq—a CReq 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.

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

pares=eyJ4aWQiOiJNREF3TURBd01EQXdNREF5TkRBd01ERXhNVFk9IiwibWRTdGF0dXMiOjAsIm1kRXJyb3JNc2ciOiJOb3QgYXV0aGVudGljYXRlZCIsImVucm9sbG1lblN0YXR1cyI6bnVsbCwiYXV0aGVudGljYXRpb25TdGF0dXMiOiJOIiwiY2F2diI6IiIsImVjaSI6IiJ9

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

In the extended authentication workflow, the issuer's Access Control Server sends a message with an acknowledgement of receiving the customer's device data to the web service URL provided in the initial payment request (in the 3ds_notification_url parameter. The message is arranged in the format chosen by the issuer.

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

Format of the authentication initiation request

When you use the extended authentication workflow, you initiate the authentication by sending a HTTP POST request to the /v2/payment/card/3ds_check_iframe endpoint. 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=ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMiLAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ&threeDSSessionData=240000554

cres=ewogICAiYWNzUmVmZXJlbmNlTnVtYmVyIiA6ICJBQ1NFbXUyIiwKICAgImFjc1RyYW5zSUQiIDog%0D%0AIjAwMDAwMDAwLTAwMDUtNWE1YS04MDAwLTAxNmQzZTI2ZWU2YyIsCiAgICJtZXNzYWdlVHlwZSIg%0D%0AOiAiQ1JlcyIsCiAgICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICAidGhyZWVEU1NlcnZl%0D%0AclRyYW5zSUQiIDogIjhiMjM0Y2ZmLTkzNjAtNTc5Yy04MDAwLTAwMDAwMDAwMDlhNiIsCiAgICJ0%0D%0AcmFuc1N0YXR1cyIgOiAiTiIKfQ==&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
}