3‑D Secure authentication

An article about primary workflows of authenticating customers with the use of the 3‑D Secure protocol for processing card payments via Gate, performed through the Ecommpay platform.

Overview

General information

3‑D Secure (Three-Domain Secure) customer authentication is aimed at preventing fraud in 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, the customer's identity may be verified via facial recognition, the customer's fingerprint may be verified on their device, or the customer's involvement may be bypassed altogether based on the payment, device, and customer data. The choice of the authentication mechanism is decided on a case-by-case basis by the issuer.

Notice: Global card networks such as American Express, Mastercard, and Visa as well as Ecommpay currently support the second version of the 3‑D Secure protocol, 3‑D Secure 2. The article contains the information about working with this protocol version.

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 networks.
  • Issuer domain: it includes the issuer's Access Control Servers (ACS) and the authentication page (ACS page).

The domains exchange messages that are required to authenticate the customer. These messages include the authentication request (Authentication Request Message, AReq) and the corresponding response (Authentication Response Message, ARes) 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 cardholder authentication is stored on the Access Control Server, and this information can be obtained only after a request to process a card payment 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:

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


The merchant cannot select the authentication flow. While the merchant can indicate which flow selection is preferable, the final decision is made by the issuer. In addition to specifying the preferred flow, the merchant can pass a range of optional parameters in the payment request which increases the possibility of the frictionless flow selection and thereby helps increase acceptance rates and enhances customer experience. Information about these and other parameters can be found below.

Special aspects

Out of scope payments

As a rule, the 3‑D Secure authentication is mandatory for card payments. It is dictated by the requirements of the Payment Services Directive 2 (PSD2) that includes the requirement of Strong Customer Authentication (SCA) to be applied to such payments.

Payments that do not fall under the scope of the SCA mandated by PSD2 include:

  • Payments made with cards issued in a country that is not located in the European Economic Area.
  • Payments made with anonymous prepaid cards: for example, a gift card or a prepaid virtual card.
  • MO/TO (Mail Order/Telephone Order) payments.
  • Merchant-initiated transactions (MIT). In the Ecommpay payment platform such payments include autopurchases and regular purchases (recurring payment type) as well as operations to change the authorised amount (incremental operation type).
  • Most alternative payments.

The payment platform supports the capability to identify payments that belong to any of the aforementioned categories. As a result, they are not subject to 3‑D Secure.

Exemptions

Under PSD2, there are several exemptions to SCA when the authentication is deemed not necessary by the issuer. The exempt payments can be categorised as follows:

  • Low value payments (Low value exemption)—if it is a payment for an amount below 25 GBP (within Great Britain) or 30 EUR (within the EEA). Along with that, there should be no more than five payments since the most recent successful authentication attempt, and the total amount of these payments should not exceed 85 GBP or 100 EUR respectively.
  • Low risk payments (Transaction Risk Analysis exemption)—if it is a payment processed by an acquirer with the fraud rates that fall below the thresholds defined in PSD2.
  • Payments to trusted merchants (Trusted beneficiaries exemption)—if it is a payment to a merchant that was added by the cardholder (or with the cardholder's consent) to a trusted list.
  • Secure corporate payments (Corporate payments exemption)—if it is a payment initiated by a company with the use of procedures and protocols that ensure high level of fraud protection (such as Electronic Banking Internet Communication Standard, EBICS).

The Ecommpay payment platform supports working with the SCA exemptions for Mastercard and Visa payments of the first two categories: low value and low risk.

Working with the SCA exemptions

Applying exemptions may keep the customer payment experience seamless and increase the payment acceptance rates. However, the merchant is held liable for possible fraud in case of exempt payments.

If this capability is enabled, the relevant exemptions are applied automatically with the exception of the specific payments for which the merchant indicates that the authentication is necessary. At the same time, keep in mind that should the issuer deem it necessary, the exempt payment can still be processed with the authentication. In this case, the issuer can respond with a soft decline which means the authentication is required. Following a soft decline, standard authentication without exemptions is performed, and as a rule, the challenge flow is used. Moreover, exemptions do not apply in case of the COF purchase registration for which 3‑D Secure is mandatory.

Information about applied exemptions is passed in the payment result callbacks and shown in the payment information tabs in Dashboard. If you have any questions about setting up and working with the SCA exemptions, refer to your Ecommpay account manager.

User scenarios

Depending on the 3‑D Secure authentication flow and other factors (for example, the design of the preloader page and the interface used for initiating the payment), the authentication process can vary for different customers.

To illustrate, if the challenge flow is used and the customer is redirected to the ACS page to enter the one-time code, the user scenario may include the following steps.

In case of the frictionless flow, the user scenario will not include the steps of customer redirection to the ACS page and return to the web service.

Authentication workflows

Overview

Similar to user scenarios, the 3‑D Secure workflows on the side on the web service and other parties can vary. In case of the web service, the authentication process is determined by the external decisions concerning the need for collecting additional data about the customer's device and the authentication flow. Each of such decisions can lead to the necessity to perform a specific procedure in addition to the basic steps of processing a payment.

authentication flows without collection of data with collection of data
frictionless flow
  • basic actions
  • basic actions
  • collection of data
challenge flow
  • basic actions
  • redirection
  • basic actions
  • collection of data
  • redirection

The merchant cannot select any of these authentication scenarios on their own. However, they can influence the decisions made by other participants by passing recommended parameters and specifying which authentication flow (frictionless or challenge) is preferred for specific payments.

General workflow

The following is a general workflow of processing a payment with the 3‑D Secure authentication.

Figure 6. Performing the 3‑D Secure authentication: step-by-step description
  1. The payment platform processes the initial payment request and determines whether the 3‑D Secure authentication is required (according to payment processing rules and requirements).
  2. The payment platform queries the 3DS Server whether the 3‑D Secure authentication is supported for the specified card and whether collecting the customer's device characteristics is necessary.
  3. The 3DS Server establishes whether 3‑D Secure is supported and whether collecting additional data is necessary.
  4. The 3DS Server sends the response to the payment platform indicating whether 3‑D Secure is supported and whether collecting the customer's device characteristics is necessary.
  5. The payment platform processes the response. If collecting additional data is not needed, step 6 is performed. If collecting additional data has been requested, the authentication procedure includes the following steps:
    1. The payment platform sends the callback with the data for the iframe element to collect the customer's device characteristics to the web service.
    2. The web service sends a synchronous response acknowledging the receipt of the callback to the payment platform.
    3. The web service opens the iframe element to collect the customer's device characteristics.
    4. The iframe script collects the data about the customer's device and sends it to issuer's Access Control Server.
    5. The issuer sends a data receipt notification to the web service.
    6. The web service sends the authentication initiation request to the URL provided by Ecommpay.
    7. The payment platform receives the request.
    8. The payment platform accepts and validates the request.
    9. The payment platform sends the response acknowledging the receipt of the request and containing the result of the validity check to the web service.
  6. The payment platform forwards the authentication request to the 3DS Server.
  7. The 3DS Server forwards the request to the Directory Server.
  8. The Directory Server forwards the request to the Access Control Server.
  9. The issuer authenticates the customer. If the issuer selects the frictionless flow, the Access Control Server sends a message with the authentication result 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:
    1. The Access Control Server sends a message with the customer redirection data that includes the ACS URL to the payment platform through the Directory Server and the 3DS Server.
    2. The payment platform sends the customer redirection data to the web service.
    3. The web service redirects the customer to the authentication page.
    4. The authentication page is displayed to the customer who then performs the actions required for authentication.
    5. The issuer authenticates the customer.
    6. The Access Control Server sends a message with the authentication result to the 3DS Server through the Directory Server.
    7. The 3DS Server sends the message acknowledging the receipt of the result to the Access Control Server through the Directory Server.
    8. The Access Control Server redirects the customer to the web service and sends the authentication result to the web service.
    9. The preloader page hosted on the web service is displayed to the customer.
    10. The web service sends the payment completion request with the authentication result 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 a synchronous response acknowledging the receipt of the request and containing the result of the validity check to the web service, following which the payment platform processes the authentication result and performs necessary actions to complete the payment.

Information about the format of callbacks and requests used in this workflow can be found below. General information about using the Gate API is provided in Interaction concepts. Note that this workflow can also include other procedures and steps that do not have anything to do with the process of authentication and that are described in corresponding articles of this documentation.

Collecting the customer's device characteristics

When the issuer requires collection of additional data about the customer's device characteristics, the payment platform sends an appropriate callback to the web service. If you receive this callback:

  1. Check the integrity of data in the callback by verifying the signature.
  2. Confirm accepting and validating the callback by sending a 200 OK synchronous response to the platform.
  3. Open the iframe element to collect the customer's device characteristics using the data received in the callback (details).
  4. Accept the message acknowledging receipt of data from the issuer's Access Control Server.
  5. Send the authentication initiation request to the payment platform.
Notice: You can decrease the frequency of having to use this procedure by issuer's request if you configure your web service to collect and send information about the customer's device in advance (details).

Redirecting the customer to the ACS page

If the issuer selects the challenge flow with redirection of the customer to the ACS page, the payment platform sends an appropriate callback to the web service. If you receive this callback:

  1. Check the integrity of data in the callback by verifying the signature.
  2. Confirm accepting and validating the callback by sending a 200 OK synchronous response to the platform.
  3. Redirect the customer to the authentication page using the data received in the callback (details) within 30 seconds after the callback was received.
  4. Accept the authentication result from the issuer.
  5. Send a payment completion request with the authentication result within 30 minutes after the callback that indicates the need for redirection was received.
  6. If the cascading payments option is enabled (details) and your web service receives an additional callback containing the cascading_with_redirect parameter (set to true), your web service is required to do the following:
    1. Repeat step 1-2 of this procedure, accepting and validating the callback.
    2. Display an authentication attempt error message to the customer.
    3. Receive the customer's consent for retrying authentication.
    4. Repeat steps 3-5 of this procedure.
Notice: You can decrease the frequency of having to use this procedure by issuer's request if you configure your web service to collect and send recommended data in advance (details).

Specifying the customer's device characteristics

To improve user experience and increase payment acceptance rates, strive to minimise the number of actions the customers need to perform in the process of authentication. To do so, you are recommended to pass certain optional parameters in requests for processing payments that will require 3‑D Secure. These parameters help decrease the likelihood that procedures to collect additional data about the customer's device and to redirect the customer to the ACS page will be needed. Alongside the information about the customer and the payment listed below, you should include the following information about the customer's device and browser:

  • Information about the device collected on the client side of the web service:
    • accept_header—value of the HTTP Accept request header
    • accept_language_header—value of the Accept-Language HTTP request header that specifies the preferred localisation language
    • browser—value of the HTTP User-Agent request header
    • ip_address—IP address of the customer during the payment session
  • Information about the device retrieved from the request sent from the browser to the web service:
    • color_depth—colour depth of the customer's device, bits per pixel
    • java_enabled—indicator that specifies whether the customer's browser supports Java
    • js_enabled—indicator that specifies whether the customer's browser supports JavaScript
    • language—code of the customer's browser language
    • screen_res—screen resolution of the customer's device, in pixels, with an x character as a delimiter (for example, 1920x1080)
    • timezone_name—name of the time zone the customer's browser is set to (for example, Australia/Adelaide)
    • timezone_offset—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, 570)
Figure 7. Example of specifying information about the customer's device
    "customer": {
    "ip_address": "188.113.253.90",
    "browser": "Mozilla/5.0 (Linux; Android 14; SM-A155F Build/UP1A.231005.007; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/138.0.7204.67 Mobile Safari/537.36",
    "screen_res": "1920x1080",
    "language": "en_US",
    "accept_header": "*/*",
    "accept_language_header": "en-GB,en;q=0.8,fr;q=0.3",
    "color_depth": 24,
    "java_enabled": false,
    "js_enabled": true,
    "timezone_offset": "570"
  }

To collect these data, configure your web service to perform the following steps.

  1. Determine the customer's device characteristics on the client side of the web service.
    Figure 8. Example of the JavaScript code for collecting information about the customer's device
    function collectClientData() {
        return {
            // screen resolution of the device 
            screen_res: `${screen.width}x${screen.height}`,
             
            // code of the browser language
            language: navigator.language,
             
            // colour depth of the browser
            color_depth: screen.colorDepth,
             
            // indicates whether Java is enabled in the browser
            java_enabled: navigator.javaEnabled(),
             
            // indicates whether JavaScript is enabled in the browser
            js_enabled: true,
             
            // differnce between the browser time zone and the UTC
            timezone_offset: new Date().getTimezoneOffset().toString(),
        };
    }
  2. Send the collected data from the client side to the server side of the web service.
    Figure 9. Example of the JavaScript code for sending the collected data to the web service back end
    async function sendClientDataToServer(endpoint = '/api/collect-client-data') {
        try {
            const clientData = collectClientData();
              
            const response = await fetch(endpoint, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'Accept': '*/*'
                },
                body: JSON.stringify(clientData)
            });
              
            const result = await response.json();
            return result;
        } catch (error) {
            console.error('Failed to send data:', error);
            throw error;
        }
    }
  3. On the server side of the web service, add the data collected from the request sent from the customer's browser to the web service as well as other parameters necessary for sending the request, generate the signature, and send the request to the Ecommpay URL.
    Figure 10. Example of the PHP code for generating the request (with essential parameters and information about the customer's device)
    interface CustomerData
    {
        public function getIpAddress(): ?string;
     
        public function getAcceptHeader(): ?string;
     
        public function getAcceptLanguageHeader(): ?string;
     
        public function getScreenRes(): ?string;
     
        public function getBrowser(): ?string;
     
        public function getLanguage(): ?string;
     
        public function getColorDepth(): ?int;
     
        public function getJavaEnabled(): ?bool;
     
        public function getJsEnabled(): ?bool;
     
        public function getTimezoneOffset(): ?string;
    }
     
    interface CardData
    {
        public function getPan();
     
        public function getYear();
     
        public function getMonth();
     
        public function getCardHolder();
     
        public function getCvv();
    }
     
    interface PaymentData
    {
        public function getPaymentId(): string;
     
        public function getAmount(): int;
     
        public function getCurrency(): string;
     
        public function getCardData(): CardData;
     
        public function getCustomerData(): CustomerData;
    }
     
    interface HttpClient
    {
        public function sendRequest(array $request): bool;
    }
     
    interface Signer
    {
        public function sign(array $params): string;
    }
     
    final class PaymentController
    {
        public function __construct(
            private Signer $signer,
            private HttpClient $httpClient,
            private int $projectId,
        ) {}
     
        public function processPayment(PaymentData $paymentData): void
        {
            $paymentRequest = [
                'general' => [
                    'project_id' => $this->projectId,
                    'payment_id' => $paymentData->getPaymentId(),
                ],
                'customer' => $this->prepareCustomerData($paymentData->getCustomerData()),
                'payment' => [
                    'amount' => $paymentData->getAmount(),
                    'currency' => $paymentData->getCurrency(),
                ],
                'card' => [
                    'pan' => $paymentData->getCardData()->getPan(),
                    'year' => $paymentData->getCardData()->getYear(),
                    'month' => $paymentData->getCardData()->getMonth(),
                    'card_holder' => $paymentData->getCardData()->getCardHolder(),
                    'cvv' => $paymentData->getCardData()->getCvv(),
                ],
            ];
     
            $paymentRequest['general']['signature'] = $this->signer->sign($paymentRequest);
     
            $this->httpClient->sendRequest($paymentRequest);
        }
     
        private function prepareCustomerData(CustomerData $customerData): array
        {
            return array_filter([
                'ip_address' => $customerData->getIpAddress(),
                'browser' => $customerData->getBrowser(),
                'screen_res' => $customerData->getScreenRes(),
                'language' => $customerData->getLanguage(),
                'accept_header' => $customerData->getAcceptHeader(),
                'accept_language_header' => $customerData->getAcceptLanguageHeader(),
                'color_depth' => $customerData->getColorDepth(),
                'java_enabled' => $customerData->getJavaEnabled(),
                'js_enabled' => $customerData->getJsEnabled(),
                'timezone_offset' => $customerData->getTimezoneOffset(),
            ]);
        }
    }
    Figure 11. Example of the Go code for generating the request (with essential parameters and information about the customer's device)
    package main
     
    import "encoding/json"
     
    // CustomerData interface
    type CustomerData interface {
        GetIpAddress() *string
        GetAcceptHeader() *string
        GetAcceptLanguageHeader() *string
        GetScreenRes() *string
        GetBrowser() *string
        GetLanguage() *string
        GetColorDepth() *int
        GetJavaEnabled() *bool
        GetJsEnabled() *bool
        GetTimezoneOffset() *string
    }
     
    // CardData interface
    type CardData interface {
        GetPan() interface{}
        GetYear() interface{}
        GetMonth() interface{}
        GetCardHolder() interface{}
        GetCvv() interface{}
    }
     
    // PaymentData interface
    type PaymentData interface {
        GetPaymentId() string
        GetAmount() int
        GetCurrency() string
        GetCardData() CardData
        GetCustomerData() CustomerData
    }
     
    // HttpClient interface
    type HttpClient interface {
        SendRequest(request map[string]interface{}) bool
    }
     
    // Signer interface
    type Signer interface {
        Sign(params map[string]interface{}) string
    }
     
    // PaymentController struct
    type PaymentController struct {
        signer     Signer
        httpClient HttpClient
        projectId  int
    }
     
    // NewPaymentController constructor
    func NewPaymentController(signer Signer, httpClient HttpClient, projectId int) *PaymentController {
        return &PaymentController{
            signer:     signer,
            httpClient: httpClient,
            projectId:  projectId,
        }
    }
     
    // ProcessPayment processes the payment
    func (pc *PaymentController) ProcessPayment(paymentData PaymentData) {
        cardData := paymentData.GetCardData()
     
        paymentRequest := map[string]interface{}{
            "general": map[string]interface{}{
                "project_id": pc.projectId,
                "payment_id": paymentData.GetPaymentId(),
            },
            "customer": pc.prepareCustomerData(paymentData.GetCustomerData()),
            "payment": map[string]interface{}{
                "amount":   paymentData.GetAmount(),
                "currency": paymentData.GetCurrency(),
            },
            "card": map[string]interface{}{
                "pan":         cardData.GetPan(),
                "year":        cardData.GetYear(),
                "month":       cardData.GetMonth(),
                "card_holder": cardData.GetCardHolder(),
                "cvv":         cardData.GetCvv(),
            },
        }
     
        // Add signature
        general := paymentRequest["general"].(map[string]interface{})
        general["signature"] = pc.signer.Sign(paymentRequest)
     
        // Send request
        pc.httpClient.SendRequest(paymentRequest)
    }
     
    // prepareCustomerData filters and prepares customer data
    func (pc *PaymentController) prepareCustomerData(customerData CustomerData) map[string]interface{} {
        result := make(map[string]interface{})
     
        if v := customerData.GetIpAddress(); v != nil {
            result["ip_address"] = *v
        }
        if v := customerData.GetBrowser(); v != nil {
            result["browser"] = *v
        }
        if v := customerData.GetScreenRes(); v != nil {
            result["screen_res"] = *v
        }
        if v := customerData.GetLanguage(); v != nil {
            result["language"] = *v
        }
        if v := customerData.GetAcceptHeader(); v != nil {
            result["accept_header"] = *v
        }
        if v := customerData.GetAcceptLanguageHeader(); v != nil {
            result["accept_language_header"] = *v
        }
        if v := customerData.GetColorDepth(); v != nil {
            result["color_depth"] = *v
        }
        if v := customerData.GetJavaEnabled(); v != nil {
            result["java_enabled"] = *v
        }
        if v := customerData.GetJsEnabled(); v != nil {
            result["js_enabled"] = *v
        }
        if v := customerData.GetTimezoneOffset(); v != nil {
            result["timezone_offset"] = *v
        }
     
        return result
    }
Note: Note that the code samples presented above are for information purposes only and cannot be used as is without additional review and modification to comply with the relevant requirements of the web service, including the PCI DSS compliance.

Payment request format

Overview

The format of requests for processing payments that will require 3‑D Secure must correspond to the format described in Interaction concepts. At the same time, each request may require a different parameter set as follows:

  • Without exception, you must include the parameters that are required for the payment type to be initiated (more information can be found in the articles about payment types) and the parameters listed below as required for performing 3‑D Secure.
  • If the frictionless flow is preferred, you are recommended to specify as many optional parameters listed below as possible for performing 3‑D Secure.
  • Additionally, you can use any other parameters out of the supported parameter set for the payment type to be initiated.

Required parameters

In requests for processing payments that will be subject to 3‑D Secure, pass the required parameters for the specific payment type and additionally include the following required objects and parameters.

Parameter Description

acs_return_url
object

Object that contains the web service URLs used for authentication. 1

return_url
string

The URL to redirect the customer to the web service after authentication. 1-11

3ds_notification_url
string

The URL the web service uses for accepting data receipt acknowledgement from ACS. 1-21

customer
object

Object that contains customer data. 2

ip_address
string

Customer's IP address. 2-12

screen_res
string

Screen resolution of the customer's device, in pixels, with an x character as a delimiter (for example, 1920x1080). 2-22

email
string

Customer's email. 2-32

phone
string

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

card
object

Object that contains the customer's card details. 3

card_holder
string

The name of the cardholder, spelled as specified on the card. 3-13
Figure 12. Example of data from the request for processing a one-time purchase with required parameters
{
  "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
    "customer": {   // information about the customer
      "ip_address": "248.121.176.220",   // IP address of the customer
      "id": "customer_12",
      "screen_res": "1920x1080",   // screen resolution of the customer's device
      "phone": "44991234567",   // customer's phone number
      "email": "john_smith@email.com"   // customer's email
  },
    "payment": {
      "amount": 400000,
      "currency": "USD"
  },
    "return_url": {
      "success": "https://example.com/success",
      "decline": "https://example.com/decline"
  },
    "card": {
      "pan": "4314220000000056",
      "year": 2025,
      "month": 8,
      "card_holder": "JOHN SMITH",   // name of the cardholder
      "cvv": "123"
  },
  "acs_return_url": {   // information about the web service URLs
    "return_url": "https://3DS_result_url",   // URL to redirect the customer to after authentication
    "3ds_notification_url": "https://3DS_result_url"   // URL for accepting receipt acknowledgement
  }

Recommended parameters

In requests for processing payments that will be subject to 3‑D Secure, you are recommended to specify parameters listed below because it can increase the possibility of frictionless flow selection that bypasses interaction with the customer and does not require the procedure of collecting additional data about the customer's device. The web service can pass all or some of the parameters, depending on the availability of specific data. The bare minimum of the parameters that affect the issuer's decision when selecting the 3‑D Secure flow includes the billing address of the customer and the customer's device and browser characteristics.

Parameter Description tree

customer
object

Object that contains customer data. 2

accept_header
string

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

accept_language_header
string

Value of the Accept-Language HTTP header used in the requests sent from the customer's browser to the web service. It specifies the preferred languages of the browser and contains language codes and corresponding q-values that signify the order of preference (for example, en-GB,en;q=0.8,fr;q=0.3). 2-192

browser
string

Value of the HTTP User-Agent request 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 device, 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

timezone_name
string

The name of the time zone the customer's browser is set to (for example, Australia/Adelaide). 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, 570). 2-92

address_match
boolean

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

Possible values:
  • true—addresses match
  • false—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

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

Postal code 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 postal code, 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

Callback format when collecting additional data is needed

When the issuer requires collecting additional data about the customer's device, you need to accept an intermediate callback from the payment platform and use the data included in the iframe object of the threeds2 object to generate an iframe element on the page of the web service. Such callbacks are arranged in a standard format (details), while the iframe object contains the data to be used as follows: specify 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 13. Example of data for collecting the customer's device characteristics
{ 
  "threeds2":{ 
    "iframe":{ 
      "url":"https://example.com",
      "params":{
        "3DSMethodData":"eyAidGhyZWVNrkthelJSUFQwaWZYMCUzQ",
        "threeDSMethodData":"eyAidGhjNjMGQ4YWU4LTA2u0wyWmtObGRdwR"
      }
    }
  }
}
Figure 14. Example of the HTML page code for collecting additional 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>

Format of the message acknowledging receipt of additional data

Messages that acknowledge receipt of additional data about the customer's device are arranged in the format chosen by the issuer. The issuer's Access Control Server sends a message with an acknowledgement to the web service URL provided in the initial payment request (in the 3ds_notification_url parameter). If you have questions about working with these messages, refer to the Ecommpay technical support.

Figure 15. Example of data from the message
threeDSMethodData:eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImRiNmFjM2UwLWI5ZWQtNWQ3NS04MDAwLTAwMDAwMDAwMTA0MiJ9
threeDSServerTransID=3abd37b3-afa6-53cf-8000-000000006455

Format of the authentication initiation request

To initiate the authentication, if it is necessary after collecting the customer's device characteristics, send 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.
    • payment_id—the payment identifier.
    • 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 data was received within 10 seconds after the iframe element was opened. 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, an indicator of timely receipt of the acknowledgement message, and a signature.

Figure 16. Example of data in the authentication initiation request
{ 
  "general":{ 
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
  "threeds_completion_indicator":true
}

Callback format when redirection is needed

To redirect the customer from your web service to the ACS URL, you need to accept an intermediate callback from the payment platform and use the data included in the redirect object of the threeds2 object. Such callbacks are arranged in a standard format (details), while the redirect object contains the data to be used as follows: specify 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 17. Example of customer redirection data
{ 
  "threeds2":{ 
    "redirect":{ 
      "url":"https://example.com/ACS",
      "params":{
        "creq":"ewogICAiYWNzVHJhbnNJCIDAtMDAwMDAwMDAwN2Q5Ip9",
        "threeDSSessionData":"240000549"
      }
    }
  }
}
Figure 18. 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 with the authentication result

Messages with authentication results are arranged in the format chosen by the issuer. They should contain the cres parameter that then is passed to the platform from the web service in the payment completion requests.

Figure 19. Example of data sent when the customer is authenticated successfully
cres=ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMiLAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ&threeDSSessionData=240000554
Figure 20. 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

To resume processing of the payment, once the challenge flow 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.
    • payment_id—the payment identifier.
    • 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 21. 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 result of the payment that involved the 3‑D Secure authentication, the payment platform sends a callback to the web service. The callback is arranged in a standard format described in Handling callbacks and contains 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 network
  • 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.

If the authentication was not performed due to an applied exemption, the operation object of the callback can also contain the non_3ds_reason parameter with the value tra, lve (for low risk or low value payments).

These parameters are not passed by default. To add them to the callbacks you receive, contact the Ecommpay technical support.

Figure 22. 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 network
      "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...=="
}