3‑D Secure authentication
Overview
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.
Authentication workflows
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 theredirectData
object).
For more information about additional callbacks, see Cascade payment processing or contact the technical support specialists at support@ecommpay.com.
Figure: 3‑D Secure 1 authentication: basic workflow without provider involvement
- The payment platform processes the request and determines whether the 3‑D Secure authentication is required.
- The payment platform queries the MPI Server whether the 3‑D Secure authentication is supported.
- The MPI Server forwards the request to the Directory Server.
- The Directory Server forwards the request to the Access Control Server.
- The Access Control Server determines whether the 3‑D Secure authentication is supported.
- The Access Control Server sends a message to the Directory Server notifying that the 3‑D Secure authentication is supported.
- The Directory Server sends the customer redirection data to theMPI Server.
- The MPI Server sends the customer redirection data to the payment platform.
- The payment platform sends a callback with the customer redirection data to the merchant web service.
- The web service sends a message acknowledging the receipt of the callback to the payment platform.
- The web service redirects the customer to the issuer's authentication page (ACS page).
- The authentication page is displayed to the customer who then performs the required actions.
- The Access Control Server authenticates the customer.
- The Access Control Server redirects the customer to the web service and sends a message with the authentication result.
- The preloader page hosted on the web service is displayed to the customer.
- The web service sends a request for payment completion with the authentication result to the URL of the ecommpay payment platform.
- The payment platform receives the request.
- The payment platform accepts and validates the request.
- The payment platform sends the validity check response acknowledging the receipt of the request for further processing.
Figure: 3‑D Secure 2 authentication: basic workflow without provider involvement
- The payment platform processes the request and determines whether the 3‑D Secure authentication is required.
- The payment platform requests from the 3DS Server what 3‑D Secure authentication versions are supported.
- 3DS Server checks what 3‑D Secure authentication version is supported.
- 3DS Server sends the customer redirection data to the payment platform.
- The payment platform sends the customer redirection data to the merchant web service.
- The web service sends acknowledgement message to the payment platform.
- The web service redirects customer to the preload page hosted on the payment platform.
- The preload page hosted on the payment platform is displayed to the customer.
- The payment platform opens the iframe.
- The iframe script collects customer device fingerprint data and sends the device fingerprint to issuer's Access Control Server.
- The Access Control Server sends to the payment platform a callback in which acknowledges receiving the data.
- The payment platform sends the customer authentication request to the 3DS Server.
- The 3DS Server sends the customer authentication request to the Directory Server.
- The Directory Server forwards the request to the Access Control Server.
- The issuer authenticates the customer. If the issuer chooses the frictionless flow, the Access Control Server sends a message with the authentication results to the payment platform (the message is forwarded through the Directory Server and the 3DS Server) and the customer is redirected to the web service. If the issuer chooses the challenge flow, the authentication follows these steps:
- The Access Control Server sends a message with the URL for redirecting customer to the authentication page to the payment platform through the Directory Server and the 3DS Server.
- The customer is redirected to the authentication page.
- The customer is presented with the authentication page and enters all the information required for the authentication.
- The issuer authenticates the customer.
- The Access Control Server sends a message with the authentication results to the 3DS Server through the Directory Server.
- The 3DS Server sends the message acknowledgement to the Access Control Server through the Directory Server.
- The customer is redirected to the preload page hosted on the payment platform.
- The preload page hosted on the payment platform is displayed to the customer.
- Customer is redirected to the web service along with the authentication result.
- The preload page hosted on the web service is displayed to the customer.
- The web service sends request for payment completion that contains the authentication result to the URL of the ecommpay payment platform.
- The payment platform accepts the request.
- The payment platform validates and then processes the request.
- The payment platform sends the response with the validity check result and the request receipt acknowledgement.
Figure: 3‑D Secure authentication: basic workflow with provider involvement
- The provider processes the request.
- The provider sends the message with the customer redirection data to the payment platform.
- The payment platform sends a callback with the customer redirection data to the merchant web service.
- The web service sends a message acknowledging the receipt of the callback to the payment platform.
- The web service redirects the customer to the issuer's authentication page via the provider service.
- The authentication page is displayed to the customer.
- The issuer authenticates the customer.
- The issuer redirects the customer to the web service.
- The customer returns to the web service.
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:
- Using the data received in the callback, display the iframe element to the customer.
- 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 the3ds_notification_url
parameter has not been passed, this step is skipped. - 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 thethreeds2
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.
- Accept a callback from the payment platform with the
Figure: 3‑D Secure authentication: extended workflow
- The payment platform processes the request and determines whether the 3‑D Secure authentication is required.
- The payment platform queries the 3DS Server whether the 3‑D Secure authentication is supported and what version of 3‑D Secure (1 or 2) is used.
- The 3DS Server establishes whether 3‑D Secure is supported.
- The 3DS Server sends the iframe data to the payment platform.
- The payment platform sends the iframe data to the web service.
- The web service sends a message acknowledging the receipt of the callback to the payment platform.
- The web service opens the iframe element.
- The iframe script collects the data about the customer's device and sends it to issuer's Access Control Server.
- If the initial payment request contains the
3ds_notification_url
parameter, the Access Control Server sends a callback confirming that the data was received to the web service. Otherwise, the Access Control Server sends a callback to the payment platform. In the former case, the authentication procedure is carried out as follows:- The web service sends the authentication initiation request to the URL provided by ecommpay.
- The payment platform receives the request.
- The payment platform accepts and validates the request.
- The payment platform sends the validity check response acknowledging the receipt of the request for further processing.
- The payment platform forwards the authentication request to the 3DS Server.
- The 3DS Server forwards the request to the Directory Server.
- The Directory Server forwards the request to the Access Control Server.
- The issuer authenticates the customer. If the issuer selects the frictionless flow, the Access Control Server sends a message with the authentication results to the payment platform (the message is forwarded through the Directory Server and the 3DS Server). If the issuer selects the challenge flow, the authentication procedure includes the following steps:
- The Access Control Server sends a message with the URL for redirecting the customer to the authentication page to the payment platform through the Directory Server and the 3DS Server.
- The payment platform sends the customer redirection data to the web service.
- The customer is redirected to the authentication page.
- The authentication page is displayed to the customer who then performs the actions required for authentication.
- The issuer authenticates the customer.
- The Access Control Server sends a message with the authentication result to the 3DS Server through the Directory Server.
- The 3DS Server sends the message acknowledgement to the Access Control Server through the Directory Server.
- The Access Control Server redirects the customer to the web service, and the authentication result is sent to the web service.
- The preloader page hosted on the web service is displayed to the customer.
- The web service sends the payment completion request that contains the authentication result to the URL provided by ecommpay.
- The payment platform receives the request.
- The payment platform accepts and validates the request.
- The payment platform sends the validity check response acknowledging the receipt of the request for further processing.
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.
Payment request format
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 sets described in the articles about corresponding payment types and, in case of the extended authentication workflow, include the web service URL to redirect the customer to.
However, it is also recommended that you pass such optional parameters as additional payment data (such as the preferred authentication flow and selected shipping method) and information about the customer (for example, the customer's billing address and contact information) to increase the possibility of the issuer's selecting the frictionless flow that bypasses interaction with the customer altogether.
Use the following parameters to pass additional payment and customer data as well as the web service URLs:
Parameter | Description | tree |
---|---|---|
|
Object that contains the data required for redirecting the customer to the web service after their authentication is complete and for accepting data receipt acknowledgement from the Access Control Server when the extended authentication workflow is used. | 1 |
|
The URL to redirect the customer to the web service after authentication. Mandatory if you use the extended authentication workflow. | 1-11 |
|
The URL the web service uses for accepting receipt acknowledgement from ACS. Mandatory if you need to accept the receipt acknowledgement when using the extended authentication workflow. | 1-21 |
|
Object that contains customer data. | 2 |
|
Value of the Accept request HTTP header as received from the customer's browser. | 2-12 |
|
Value of the User-Agent request HTTP header as received from the customer's browser. | 2-22 |
|
The colour depth of the screen as supported by the customer's browser, bits per pixel. | 2-32 |
|
Indicates whether the customer's browser supports Java. | 2-42 |
|
Indicates whether the customer's browser supports JavaScript. | 2-52 |
|
The code of the customer's browser language. | 2-62 |
|
Screen resolution of the customer's device in pixels (for example, 360x640 ). |
2-72 |
|
The name of the time zone the customer's browser is set to (for example, Europe/London ). |
2-82 |
|
The difference between a date as evaluated in the UTC time zone and the same date as evaluated in the browser time zone, specified in minutes, (for example, -120 . |
2-92 |
|
Indicates whether the customer's billing address matches the address specified in the Possible values:
|
2-102 |
|
Customer's home phone number, contains between 4 and 24 digits (for example, 44991234567 ). |
2-112 |
|
Customer's work phone number, contains between 4 and 24 digits (for example, 44997654321 ). |
2-122 |
|
Object with the customer's account information kept on file by the merchant. | 2-132 |
|
Additional information about the customer's account in free text, for example, its identifier. Can contain up to 64 characters. | 2-13-12-13 |
|
Number of payment attempts in the last 24 hours, 3 characters maximum (999 ). |
2-13-22-13 |
|
Number of payment attempts in the last 365 days, 3 characters maximum (999 ). |
2-13-32-13 |
|
Number of days since the customer account was created. Possible values:
|
2-13-42-13 |
|
Additional login information in free text, can contain up to 255 characters. | 2-13-52-13 |
|
Indicates how the customer was authenticated during their most recent login to the web service. Possible values:
|
2-13-62-13 |
|
Date and time of the customer's most recent account login in the DD-MM-YYYYhh:mm format. |
2-13-72-13 |
|
Account creation date in the DD-MM-YYYY format. |
2-13-82-13 |
|
Date of the most recent change to the account, except for the password change or password reset, in the DD-MM-YYYY format. |
2-13-92-13 |
|
Number of days since the most recent change to the account, except for the password change or password reset. Possible values:
|
2-13-102-13 |
|
Date of the most recent password change or reset in the DD-MM-YYYY format. |
2-13-112-13 |
|
Number of days since the most recent password change or reset. Possible values:
|
2-13-122-13 |
|
Card record creation date in the DD-MM-YYYY format. |
2-13-132-13 |
|
Number of days since the payment card details were saved to a customer's account. Possible values:
|
2-13-142-13 |
|
Number of attempts to save new card details to a customer's account in the last 24 hours, 3 characters maximum (999 ). |
2-13-152-13 |
|
Number of purchases made via the customer's account in the last 6 months, 4 characters maximum (9999 ). |
2-13-162-13 |
|
Indicates the presence of suspicious activity. Possible values:
|
2-13-172-13 |
|
Customer's email. | 2-142 |
|
Customer's phone number, contains between 4 and 24 digits. | 2-152 |
|
Object with information about the customer's billing address. | 2-162 |
|
Street of the customer's billing address. | 2-16-12-16 |
|
City of the customer's billing address. | 2-16-22-16 |
|
Country of the customer's billing address in the ISO 3166-1 alpha-2 format. | 2-16-32-16 |
|
Postcode of the customer's billing address. | 2-16-42-16 |
|
State, province, or region code in the ISO 3166-2 format, for example, DEV for Devon.If you specify this parameter, you also need to specify and populate the |
2-16-52-16 |
|
Object with shipping details. | 2-172 |
|
Shipping address, can contain up to 150 characters. | 2-17-12-17 |
|
Date when the specified shipping address was used for the first time, in the DD-MM-YYYY format. |
2-17-22-17 |
|
Number of days since the specified shipping address was used for the first time. Possible values:
|
2-17-32-17 |
|
Shipping city, can contain up to 50 characters. | 2-17-42-17 |
|
Shipping country code in the ISO 3166-1 alpha-2 format (for example, GB). | 2-17-52-17 |
|
The email to deliver purchased digital content to if the customer chooses email delivery. Can contain up to 255 characters. | 2-17-62-17 |
|
Delivery time. Possible values:
|
2-17-72-17 |
|
Indicates whether the customer's name matches the recipient's name. Possible values:
|
2-17-82-17 |
|
Shipping postcode, can contain up to 16 characters. | 2-17-92-17 |
|
State, province, or region code in the ISO 3166-2 format, for example, DOR for Dorset.If you specify this parameter, you also need to specify and populate the |
2-17-102-17 |
|
Delivery option selected by the customer. Possible values:
|
2-17-112-17 |
|
Object that contains information about the previous authentication attempt of the customer. | 2-182 |
|
The identifier that the issuer assigned to the previous operation of the customer and returned in the acs_operation_id parameter of the callback with payment processing result. Can contain up to 36 characters. |
2-18-12-18 |
|
The flow used by the issuer to authenticate the cardholder when processing the previous operation. It is a value of the Possible values:
|
2-18-22-18 |
|
Date and time of the previous successful customer authentication as returned in the mpi_timestamp parameter of the callback with payment processing result. |
2-18-32-18 |
|
Object with payment information. | 3 |
|
Indicates whether the challenge flow is preferred. Possible values:
|
3-13 |
|
The dimensions of a window in which the authentication page opens. Possible values:
|
3-23 |
|
The date the preordered merchandise or service will be available in the DD-MM-YYYY format. |
3-33 |
|
Indicates whether the purchase is a preorder. Possible values:
|
3-43 |
|
Indicates whether the customer is buying the merchandise or the service for the first time or it is a repeat purchase. Possible values:
|
3-53 |
|
Object with information about a purchase made with a prepaid or gift card. | 3-63 |
|
The amount of the purchase made with a prepaid or gift card in the smallest units of currency. | 3-6-13-6 |
|
Currency of the purchase made with a prepaid or gift card in the ISO 4217 alpha-3 format (for example, GBP). | 3-6-23-6 |
|
Number of prepaid or gift cards used for making the purchase. | 3-6-33-6 |
The merchant web service can pass all of these parameters or only some of them.
Format of intermediate messages for basic workflow
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
).
Figure: Example of redirection data in the acs object
"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
).
Figure: Example of redirection data in the redirectData object
"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 theacs_url
parameter of the callback.PaReq
—a PAReq message sourced from thepa_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 themd
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 theurl
parameter of the callback.method
—the HTTP method of the request.body
—the body of the request if it was received in the callback.
Figure: Example of the HTML page code with the data sourced from the acs object
<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.
Figure: Example of data sent when the customer is authenticated successfully
pares=eyJ4aWQiOiJNREF3TURBd01EQXdNREF5TkRBd01ERXhNVFU9IiwibWRTdGF0dXMiOjEsIm1kRXJyb3JNc2ciOiJBdXRoZW5
0aWNhdGVkIiwiZW5yb2xsbWVuU3RhdHVzIjpudWxsLCJhdXRoZW50aWNhdGlvblN0YXR1cyI6IlkiLCJjYXZ2I
joiUVVOVFJVMVZLMkI5UFV4MWFXRXBhMlJpTjJVPSIsImVjaSI6IjA1In0=
Figure: Example of data sent when the authentication has failed
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.
Figure: Example of data in the payment completion request
{ "general": { "project_id": 42, "payment_id": "456789", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "pares": "ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMi LAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlR FNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1 N0YXR1cyIgOiAiWSIKfQ" // Authentication result information }
Format of intermediate messages for extended workflow
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.
Figure: Example of data for creating an iframe
{ "threeds2":{ "iframe":{ "url":"https://example.com", "params":{ "3DSMethodData":"eyAidGhyZWVNrkthelJSUFQwaWZYMCUzQ", "threeDSMethodData":"eyAidGhjNjMGQ4YWU4LTA2u0wyWmtObGRdwR" } } } }
Figure: Example of the HTML page code with the iframe data
<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.
Figure: Example of customer redirection data
{ "threeds2":{ "redirect":{ "url":"https://example.com/ACS", "params":{ "creq":"ewogICAiYWNzVHJhbnNJCIDAtMDAwMDAwMDAwN2Q5Ip9", "threeDSSessionData":"240000549" } } } }
Figure: Example of the HTML page code with redirection data
<!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.
Figure: Example of the operation ID on the 3DS Server side
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, passtrue
; if not, passfalse
.
Thus, a correct request for the 3‑D Secure authentication initiation contains a project identifier, a payment identifier, and a signature.
Figure: Example of data in the authentication initiation request
{ "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.
Figure: Example of data sent when the customer is authenticated successfully
cres=ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMiLAogICJtZXNzYWdlVHl
wZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFu
c0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1N0YXR1cyIgO
iAiWSIKfQ&threeDSSessionData=240000554
Figure: Example of data sent when the authentication has failed
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.
Figure: Example of data in the payment completion request
{ "general": { "project_id": 42, "payment_id": "456789", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "cres": "ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMi LAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlR FNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1 N0YXR1cyIgOiAiWSIKfQ" // Authentication result data }
Format of callbacks with payment results
To communicate the payment result, the payment platform sends a callback to the web service. The callback is arranged in a standard format described in Callbacks.
If payment processing involves the 3‑D Secure 2 authentication, callbacks may contain the mpi_result
object with the following parameters:
mpi_operation_id
—operation identifier on the 3DS Server sideds_operation_id
—operation identifier on the Directory Server side of the global card schemeacs_operation_id
—operation identifier on the issuer's Access Control Server sidempi_timestamp
—authentication time and datecardholder_info
—the message you are recommended to display when notifying the customer about the payment resultauthentication_flow
—authentication flow indicator:01
for the frictionless flow,02
for the challenge flow.
These parameters are not passed by default. To add them to the callbacks you receive, contact the technical support at support@ecommpay.com.
Figure: Example of callback containing the result of the payment performed with the use of 3‑D Secure 2
{ "account":{ "number":"431422******0056", "token":"f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654", "type":"visa", "card_holder":"JOHN SMITH", "id":45678, "expiry_month":"08", "expiry_year":"2025" }, "customer":{ "id":"customer_12", "phone":"44991234567" }, "payment":{ "date":"2019-01-11T13:02:42+0000", "id":"456789", "method":"card", "status":"success", "sum":{ "amount":400000, "currency":"USD" }, "type":"purchase", "description":"" }, "project_id":42, "operation":{ "id":969000002636, "type":"sale", "status":"success", "date":"2019-01-11T13:02:42+0000", "created_date":"2019-01-11T13:01:45+0000", "request_id":"c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c", "sum_initial":{ "amount":400000, "currency":"USD" }, "sum_converted":{ "amount":400000, "currency":"USD" }, "provider":{ "id":408, "payment_id":"330157196", "date":"2019-01-11T13:02:32+0000", "auth_code":"", "endpoint_id":"612266625" }, "mpi_result":{ "mpi_operation_id":"", // Operation identifier on the 3DS Server side "ds_operation_id":"", // Operation identifier on the Directory Server side of the global card scheme "acs_operation_id":"", // Operation identifier on the issuer's Access Control Server side "mpi_timestamp":"YYYYMMDDHHMM", // Authentication time and date "cardholder_info":"Additional authentication is needed for this transaction", // Information about authentication that you are recommended to display to the customer "authentication_flow":"02" // Authentication flow indicator }, "code":"0", "message":"Success", "eci":"07" }, "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }