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.

Tip: There are two main versions of the 3‑D Secure protocol: 3‑D Secure 1 and 3‑D Secure 2. The 3‑D Secure 2 version differs from 3‑D Secure 1 mostly by the range of available mechanisms for customer identity verification and the authentication parameters used. For example, the customer's biometric verification (with the use of fingerprints) or the customer's verification without any actions on the customer's part is available only in the second version of the protocol. The first version is no longer supported by such global card schemes as American Express, Mastercard, and Visa, but other card schemes may still support this version. The information presented in this article will allow you to work with both versions.

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

  1. The payment platform processes the request and determines whether the 3‑D Secure authentication is required.
  2. The payment platform queries the MPI Server whether the 3‑D Secure authentication is supported.
  3. The MPI Server forwards the request to the Directory Server.
  4. The Directory Server forwards the request to the Access Control Server.
  5. The Access Control Server determines whether the 3‑D Secure authentication is supported.
  6. The Access Control Server sends a message to the Directory Server notifying that the 3‑D Secure authentication is supported.
  7. The Directory Server sends the customer redirection data to theMPI Server.
  8. The MPI Server sends the customer redirection data to the payment platform.
  9. The payment platform sends a callback with the customer redirection data to the merchant web service.
  10. The web service sends a message acknowledging the receipt of the callback to the payment platform.
  11. The web service redirects the customer to the issuer's authentication page (ACS page).
  12. The authentication page is displayed to the customer who then performs the required actions.
  13. The Access Control Server authenticates the customer.
  14. The Access Control Server redirects the customer to the web service and sends a message with the authentication result.
  15. The preloader page hosted on the web service is displayed to the customer.
  16. The web service sends a request for payment completion with the authentication result to the URL of the ecommpay payment platform.
  17. The payment platform receives the request.
  18. The payment platform accepts and validates the request.
  19. 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

  1. The payment platform processes the request and determines whether the 3‑D Secure authentication is required.
  2. The payment platform requests from the 3DS Server what 3‑D Secure authentication versions are supported.
  3. 3DS Server checks what 3‑D Secure authentication version is supported.
  4. 3DS Server sends the customer redirection data to the payment platform.
  5. The payment platform sends the customer redirection data to the merchant web service.
  6. The web service sends acknowledgement message to the payment platform.
  7. The web service redirects customer to the preload page hosted on the payment platform.
  8. The preload page hosted on the payment platform is displayed to the customer.
  9. The payment platform opens the iframe.
  10. The iframe script collects customer device fingerprint data and sends the device fingerprint to issuer's Access Control Server.
  11. The Access Control Server sends to the payment platform a callback in which acknowledges receiving the data.
  12. The payment platform sends the customer authentication request to the 3DS Server.
  13. The 3DS Server sends the customer authentication request to the Directory Server.
  14. The Directory Server forwards the request to the Access Control Server.
  15. 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.
  16. The web service sends request for payment completion that contains the authentication result to the URL of the ecommpay payment platform.
  17. The payment platform accepts the request.
  18. The payment platform validates and then processes the request.
  19. 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

  1. The provider processes the request.
  2. The provider sends the message with the customer redirection data to the payment platform.
  3. The payment platform sends a callback with the customer redirection data to the merchant web service.
  4. The web service sends a message acknowledging the receipt of the callback to the payment platform.
  5. The web service redirects the customer to the issuer's authentication page via the provider service.
  6. The authentication page is displayed to the customer.
  7. The issuer authenticates the customer.
  8. The issuer redirects the customer to the web service.
  9. 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:

  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.

Figure: 3‑D Secure authentication: extended workflow

  1. The payment platform processes the request and determines whether the 3‑D Secure authentication is required.
  2. 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.
  3. The 3DS Server establishes whether 3‑D Secure is supported.
  4. The 3DS Server sends the iframe data to the payment platform.
  5. The payment platform sends the iframe data to the web service.
  6. The web service sends a message acknowledging the receipt of the callback to the payment platform.
  7. The web service opens the iframe element.
  8. The iframe script collects the data about the customer's device and sends it to issuer's Access Control Server.
  9. 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.
  10. The payment platform forwards the authentication request to the 3DS Server.
  11. The 3DS Server forwards the request to the Directory Server.
  12. The Directory Server forwards the request to the Access Control Server.
  13. 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

acs_return_url
object

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

return_url
string

The URL to redirect the customer to the web service after authentication. Mandatory if you use the extended authentication workflow. 1-11

3ds_notification_url
string

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

customer
object

Object that contains customer data. 2

accept_header
string

Value of the Accept request HTTP header as received from the customer's browser. 2-12

browser
string

Value of the User-Agent request HTTP header as received from the customer's browser. 2-22

color_depth
integer

The colour depth of the screen as supported by the customer's browser, bits per pixel. 2-32

java_enabled
boolean

Indicates whether the customer's browser supports Java. 2-42

js_enabled
boolean

Indicates whether the customer's browser supports JavaScript. 2-52

language
string

The code of the customer's browser language. 2-62

screen_res
string

Screen resolution of the customer's device in pixels (for example, 360x640). 2-72

timezone_name
string

The name of the time zone the customer's browser is set to (for example, Europe/London). 2-82

timezone_offset
string

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

address_match
boolean

Indicates whether the customer's billing address matches the address specified in the shipping object.

Possible values:
  • Y—addresses match
  • N—addresses do not match
2-102

home_phone
string

Customer's home phone number, contains between 4 and 24 digits (for example, 44991234567). 2-112

work_phone
string

Customer's work phone number, contains between 4 and 24 digits (for example, 44997654321). 2-122

account
object

Object with the customer's account information kept on file by the merchant. 2-132

additional
string

Additional information about the customer's account in free text, for example, its identifier. Can contain up to 64 characters. 2-13-12-13

activity_day
integer

Number of payment attempts in the last 24 hours, 3 characters maximum (999). 2-13-22-13

activity_year
integer

Number of payment attempts in the last 365 days, 3 characters maximum (999). 2-13-32-13

age_indicator
string

Number of days since the customer account was created. Possible values:
  • 01—guest checkout
  • 02—the account was created at the moment of making a payment
  • 03—fewer than 30 days
  • 04—between 30 and 60 days
  • 05—more than 60 days
2-13-42-13

auth_data
string

Additional login information in free text, can contain up to 255 characters. 2-13-52-13

auth_method
string

Indicates how the customer was authenticated during their most recent login to the web service. Possible values:
  • 01—no authentication
  • 02—logging in with authentication data kept on file by the merchant
  • 03—logging in with the federated identity credentials (for example, Google Account or Facebook ID)
  • 04—logging in with the use of FIDO authenticator (Fast Identity Online)
2-13-62-13

auth_time
string

Date and time of the customer's most recent account login in the DD-MM-YYYYhh:mm format. 2-13-72-13

date
string

Account creation date in the DD-MM-YYYY format. 2-13-82-13

change_date
string

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

change_indicator
string

Number of days since the most recent change to the account, except for the password change or password reset. Possible values:
  • 01—the account was updated on the day when the payment was made
  • 02—fewer than 30 days
  • 03—between 30 and 60 days
  • 04—more than 60 days
2-13-102-13

pass_change_date
string

Date of the most recent password change or reset in the DD-MM-YYYY format. 2-13-112-13

pass_change_indicator
string

Number of days since the most recent password change or reset. Possible values:
  • 01—password was not changed or reset
  • 02—password was changed or reset on the day when the payment was made
  • 03—fewer than 30 days
  • 04—between 30 and 60 days
  • 05—more than 60 days
2-13-122-13

payment_age
string

Card record creation date in the DD-MM-YYYY format. 2-13-132-13

payment_age_indicator
string

Number of days since the payment card details were saved to a customer's account. Possible values:
  • 01—guest checkout
  • 02—card details were saved on the day when the payment was made
  • 03—fewer than 30 days
  • 04—between 30 and 60 days
  • 05—more than 60 days
2-13-142-13

provision_attempts
integer

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

purchase_number
integer

Number of purchases made via the customer's account in the last 6 months, 4 characters maximum (9999). 2-13-162-13

suspicious_activity
string

Indicates the presence of suspicious activity. Possible values:
  • 01—no suspicious activity detected
  • 02—suspicious activity detected
2-13-172-13

email
string

Customer's email. 2-142

phone
string

Customer's phone number, contains between 4 and 24 digits. 2-152

billing
object

Object with information about the customer's billing address. 2-162

address
string

Street of the customer's billing address. 2-16-12-16

city
string

City of the customer's billing address. 2-16-22-16

country
string

Country of the customer's billing address in the ISO 3166-1 alpha-2 format. 2-16-32-16

postal
string

Postcode of the customer's billing address. 2-16-42-16

region_code
string

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 billing_country parameter.

2-16-52-16

shipping
object

Object with shipping details. 2-172

address
string

Shipping address, can contain up to 150 characters. 2-17-12-17

address_usage
string

Date when the specified shipping address was used for the first time, in the DD-MM-YYYY format. 2-17-22-17

address_usage_indicator
string

Number of days since the specified shipping address was used for the first time. Possible values:
  • 01—first-time use
  • 02—fewer than 30 days
  • 03—between 30 and 60 days
  • 04—more than 60 days
2-17-32-17

city
string

Shipping city, can contain up to 50 characters. 2-17-42-17

country
string

Shipping country code in the ISO 3166-1 alpha-2 format (for example, GB). 2-17-52-17

delivery_email
string

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
string

Delivery time. Possible values:
  • 01—digital same day delivery
  • 02—same day delivery
  • 03—next day delivery
  • 04—delivery more than one day after the purchase was made
2-17-72-17

name_indicator
string

Indicates whether the customer's name matches the recipient's name. Possible values:
  • 01—names match
  • 02—names do not match
2-17-82-17

postal
string

Shipping postcode, can contain up to 16 characters. 2-17-92-17

region_code
string

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 country parameter in the shipping object.

2-17-102-17

type
string

Delivery option selected by the customer. Possible values:
  • 01—delivery to the cardholder's billing address
  • 02—delivery to a different verified address
  • 03—delivery to the address that is not verified and does not match the billing address
  • 04—store delivery
  • 05—digital delivery
  • 06—no delivery needed (for example, event ticket purchase)
  • 07—other
2-17-112-17

mpi_result
object

Object that contains information about the previous authentication attempt of the customer. 2-182

acs_operation_id
string

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

authentication_flow
string

The flow used by the issuer to authenticate the cardholder when processing the previous operation. It is a value of the authentication_flow parameter returned in the callback with payment processing result.

Possible values:

  • 01—frictionless flow
  • 02—challenge flow
2-18-22-18

authentication_timestamp
string

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

payment
object

Object with payment information. 3

challenge_indicator
string

Indicates whether the challenge flow is preferred. Possible values:
  • 01—no preferences
  • 02—not using the challenge flow is preferred
  • 03—using the challenge flow is preferred
  • 04—using the challenge flow is required
  • 05—do not use the challenge flow, the merchant has performed the risk analysis
  • 06—do not use the challenge flow, use the Data Only flow
  • 07—do not use the challenge flow, Strong Customer Authentication has been applied otherwise
  • 08—do not use the challenge flow, the merchant is included in cardholder's trusted beneficiaries list
  • 09—using the challenge flow is required, prompt the cardholder to add the merchant to the trusted beneficiaries list
3-13

challenge_window
string

The dimensions of a window in which the authentication page opens. Possible values:
  • 01—250 x 400 px
  • 02—390 x 400 px
  • 03—500 x 600 px
  • 04—600 x 400 px
  • 05—full screen
3-23

preorder_date
string

The date the preordered merchandise or service will be available in the DD-MM-YYYY format. 3-33

preorder_purchase
string

Indicates whether the purchase is a preorder. Possible values:
  • 01—not a preorder
  • 02—a preorder
3-43

reorder
string

Indicates whether the customer is buying the merchandise or the service for the first time or it is a repeat purchase. Possible values:
  • 01—first-time purchase
  • 02—repeat purchase
3-53

gift_card
object

Object with information about a purchase made with a prepaid or gift card. 3-63

amount
integer

The amount of the purchase made with a prepaid or gift card in the smallest units of currency. 3-6-13-6

currency
string

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

count
integer

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

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

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 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—authentication time and date
  • cardholder_info—the message you are recommended to display when notifying the customer about the payment result
  • authentication_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":"424242******4243",
    "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...=="
}