3‑D Secure authentication

Overview

Warning: Starting August 12, 2024, Visa Rules will be updated to expand the set of parameters mandatory for processing Visa card payments with the 3‑D Secure authentication. Parameters that will be required in such cases are listed below. (Earlier these changes were reported to come into force on February 12, 2024).

However, it is also recommended that these and a number of other parameters (with the billing address information) are specified for payments made with cards of other card schemes. According to Visa, rigorous use of these parameters can significantly increase payment acceptance rates (up to 6 %) and drastically decrease the number of operations flagged as fraudulent after they have been processed (up to 65 %).

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: This article describes how to work with the second version of the 3‑D Secure protocol, 3‑D Secure 2. Since the first version of the protocol is no longer supported by American Express, Mastercard, and Visa card schemes, it is also no longer supported in the payment platform.

3‑D Secure involves the interaction of three domains:

  • Acquirer domain: in the context of the ecommpay payment platform interoperability, it includes the merchant's web service, the payment platform and its 3DS Server.
  • Interoperability domain: it includes the Directory Servers (DS) of global card schemes.
  • Issuer domain: it includes the issuer's Access Control Servers (ACS) and the authentication page.

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

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

3‑D Secure authentication flows

3‑D Secure supports the following authentication flows:

  • Frictionless flow—authentication that does not involve interaction with the customer. As a rule, 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. 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 payment request which increases the possibility of the frictionless flow selection. The information about these parameters is provided in the sections that follow.

Tip: Most frequently used optional parameters include the customer's email (the email parameter) and billing address (parameters passed in the billing object), the customer's phone number (the phone parameter), the screen resolution of the customer's device (the screen_res parameter), and the User-Agent HTTP header received from the browser (the browser parameter). Information about these and other parameters can be found below.

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 (a.k.a. proxy) and extended, (a.k.a. native).

Basic (proxy) workflow Extended (native) workflow
  • Based on the existing 3‑D Secure 1 workflow.
  • Requires less development effort from merchants.
  • Requires multiple customer redirect operations.
  • Optimized for 3‑D Secure 2.
  • Requires more development effort from merchants.
  • Does not require any intermediate customer redirect operations.
Tip: The merchant can choose either of the workflows. However, extended workflow is preferable as it ensures better user experience and can positively impact payment acceptance rates.

You can switch from basic to extended workflow at any time; no additional coordination with the ecommpay specialists is necessary. In the payment request pass the parameters required for the extended workflow. They are listed below, in Payment request format.

User scenarios

Depending on the implemented workflow, the authentication flow selected by the issuer, and other factors, the authentication process can vary. For example, when the customer is being authenticated, they can be shown the preloader page by the web service or the platform and the ACS page by the issuer.

To illustrate, if the extended workflow is used, the user scenario may include the following steps.

Authentication workflows

Basic workflow

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

Basic authentication workflow implies that the callback communicating the need for authentication contains the acs object. To respond to such callbacks, you need to redirect the customer to the issuer's ACS page, accept the authentication result, and send the payment completion request with the result to the payment platform. Note that once the need for authentication is established, the payment platform waits for the payment completion request with the authentication result from the web service; as a rule, the waiting time is 30 minutes. If the payment platform does not receive the request with the authentication result within the waiting time, the payment is automatically declined.

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

  • Display an error message to a customer on a page and obtain their consent to re-authenticate.
  • Respond to the callback accordingly.

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

Figure: 3‑D Secure authentication: basic workflow, step-by-step description

  1. The payment platform processes the request and determines whether the 3‑D Secure authentication is required.
  2. The payment platform requests the 3DS Server to check whether the 3‑D Secure authentication is supported.
  3. 3DS Server checks whether the 3‑D Secure authentication 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.

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

Extended workflow

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

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

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

When you submit the authentication result, the payment platform continues payment processing. If the cascading payments option is enabled, your web service may need to accept one or more additional callbacks with the redirect object. If the additional callback contains the cascading_with_redirect parameter that is set to true, your web service is required to do the following:

  • Display an error message to a customer on a page and obtain their consent to re-authenticate.
  • Respond to the callback accordingly.

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

Figure: 3‑D Secure authentication: extended workflow, step-by-step description

  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.
  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 callback with 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. The issuer sends a data receipt notification to the web service.
  10. The web service sends the authentication initiation request to the URL provided by ecommpay.
  11. The payment platform receives the request.
  12. The payment platform accepts and validates the request.
  13. The payment platform sends the validity check response acknowledging the receipt of the request for further processing to the web service.
  14. The payment platform forwards the authentication request to the 3DS Server.
  15. The 3DS Server forwards the request to the Directory Server.
  16. The Directory Server forwards the request to the Access Control Server.
  17. 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

Overview

Overall, the format of the payment request does not affect the probability of whether the authentication is going to be triggered and should conform to the standard described in Interaction concepts. Similarly, the required parameters used for a certain payment should align with the parameter sets described in the articles about corresponding payment types and, in case of the extended authentication workflow, include the acs_return_url object that contains the web service URLs for redirecting the customer to the web service and for accepting acknowledgement from the issuer.

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

Required parameters

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

Parameter Description

return_url
string

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

3ds_notification_url
string

The URL the web service uses for accepting receipt acknowledgement from ACS. Mandatory if you use the extended authentication workflow.

Starting August 12, 2024, requests for Visa card payments must contain the customer object with the following parameters.

Parameters Description

ip_address
string

Customer's IP address.

screen_res
string

Screen resolution of the customer's device, in pixels, with an x character as a delimiter (for example, 360x640).

email
string

Customer's email. Required if the customer's phone number is not passed.

phone, work_phone, home_phone
string

Customer's phone numbers (mobile, work, home, must specify at least one). Required if the customer's email is not passed.

These parameters are not required in requests for payment instrument verification (account_verification payment type).

Optional parameters

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

Parameter Description tree

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, with an x character as a delimiter (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—0 days (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—0 days (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—the password was not changed or reset
  • 02—0 days (the 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—0 days (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

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 the acs object. The acs object of the callback contains the following data: the CReq message (in the pa_req parameter) to send the authentication initiation request to the issuer, the URL of the authentication page (acs_url), and the merchant data kept on file by the card scheme (md).

Figure: Example of redirection data

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

Format of the redirection request

To redirect the customer to the issuer's ACS page or the provider's page, send the request to the URL received in the callback that signals the need for authentication. Use a POST method and include the following objects and parameters

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

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

Figure: Example of data sent when the authentication has failed

pares=eyJ4aWQiOiJNREF3TURBd01EQXdNREF5TkRBd01ERXhNVFk9IiwibWRTdGF0dXMiOjAsIm1kRXJyb3JNc2ciOiJOb3QgYXV0aGVudGljYXRlZCIsImVucm9sbG1lblN0YXR1cyI6bnVsbCwiYXV0aGVudGljYXRpb25TdGF0dXMiOiJOIiwiY2F2diI6IiIsImVjaSI6IiJ9

Format of the payment completion request

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

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

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

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

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

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, you initiate the authentication by sending a HTTP POST request to the /v2/payment/card/3ds_check_iframe endpoint. The request must contain the following objects and parameters:

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

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

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=ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMiLAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ&threeDSSessionData=240000554

Figure: Example of data sent when the authentication has failed

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

Format of the payment completion request

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

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

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

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

{  
  "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...=="
}