3‑D Secure authentication

Overview

3‑D Secure (Three-Domain Secure) customer authentication is aimed to increase secure processing of online card payments. This authentication procedure is essential for processing purchases and can be carried out in a variety of ways: the customer may be required to perform certain actions to confirm their identity or their involvement can be bypassed altogether.As a rule, this authentication procedure is essential for processing purchases and can be carried out according to the following authentication flows:

Notice: This article describes how to work with the second version of the 3‑D Secure protocol, 3‑D Secure 2. The first version of the protocol is no longer supported by American Express, Mastercard, and Visa card schemes.

3‑D Secure supports the following authentication flows:

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

User scenarios

The following are the steps the customer takes when making a purchase that involves the 3‑D Secure authentication.

  1. The customer selects the option to make a purchase on the side of the merchant's web service.
  2. The payment form is displayed to the customer in accordance with the parameters passed in the request. The customer performs the required actions and confirms the purchase following which they are shown the Payment Page preloader.
  3. If the issuer selects the challenge flow, the customer is shown the authentication page (ACS). The customer completes the required steps and is shown the Payment Page preloader.
  4. The customer is shown the page with the payment result information.

The number and sequence of steps in this scenario may slightly change: for example, if the authentication involves the provider, the customer is redirected first to the provider's page and then to the ACS page.

Implementation

3‑D Secure is implemented when the ecommpay specialists add card payments to the merchant's project. Other than that, the merchant is not required to take any additional steps.

Data formats

Requests for processing card payments must contain one of the following parameters.

Parameters Description

customer_email
string

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

customer_phone
string

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

These parameters are not required in requests for payment instrument verification (Card Verify Payment Page operation mode).

To increase the possibility of the frictionless flow selection, it is recommended that you pass additional payment and customer data in the request for opening the payment form. Such data can include the indication of the preferred authentication flow, the selected shipping method, the customer's billing address and contact information. This information can be collected in whatever way is deemed most convenient, including via the payment form (using the capability of collecting additional customer data), and passed in the following parameters:

Parameter Description tree

payment_merchant_risk
string

Details of the customer's purchase and the indication of the preferred authentication flow.

A Base64 string converted from the payment JSON object with the relevant objects and parameters.

Figure 1. Example of a JSON object
{ 
  "payment":{ 
    "reorder":"01",
    "preorder_purchase":"01",
    "preorder_date":"11-10-2022",
    "challenge_indicator":"01",
    "challenge_window":"01",
    "gift_card":{ 
      "amount":12345,
      "currency":"USD",
      "count":1
    }
  }
}
Figure 2. Example of a string
eyAKICAicGF5bWVudCI6eyAKICAgICJyZW9yZGVyIjoiMDEiLAogICAgInByZW9yZGVyX3B1cmNoYXNlIjoiMDEiLAogICAgInByZW9yZGVyX2RhdGUiOiIxMS0xMC0yMDIyIiwKICAgICJjaGFsbGVuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgImNoYWxsZW5nZV93aW5kb3ciOiIwMSIsCiAgICAiZ2lmdF9jYXJkIjp7IAogICAgICAiYW1vdW50IjoxMjM0NSwKICAgICAgImN1cnJlbmN5IjoiVVNEIiwKICAgICAgImNvdW50IjoxCiAgICB9CiAgfQp9==
 2

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

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

preorder_date
string

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

preorder_purchase
string

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

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

gift_card
object

 Object with information about a purchase made with a prepaid or gift card. 2-62

amount
integer

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

currency
string

 Currency of the purchase made with a prepaid or gift card in the ISO 4217 alpha-3 format (for example, GBP). 2-6-22-6

count
integer

 Total number of prepaid or gift cards used for making a purchase. 2-6-32-6

customer_account_info
string

Customer's account details and contact information kept on file on the side of the web service.

A Base64 string converted from the customer JSON object with the relevant objects and parameters.

Figure 3. Example of a JSON object
{ 
  "customer":{ 
    "address_match":"Y",
    "home_phone":"442055526608",
    "work_phone":"442055537709",
    "account":{ 
      "additional":"gamer12345",
      "age_indicator":"01",
      "date":"01-10-2022",
      "change_indicator":"01",
      "change_date":"01-10-2022",
      "pass_change_indicator":"01",
      "pass_change_date":"01-10-2022",
      "purchase_number":12,
      "provision_attempts":16,
      "activity_day":22,
      "activity_year":222,
      "payment_age_indicator":"01",
      "payment_age":"01-10-2022",
      "suspicious_activity":"01",
      "auth_method":"01",
      "auth_time":"01-10-202213:12",
      "auth_data":"login_0102"
    }
  }
}
Figure 4. Example of a string
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAiYWRkcmVzc19tYXRjaCI6IlkiLAogICAgImhvbWVfcGhvbmUiOiI0NDIwNTU1MjY2MDgiLAogICAgIndvcmtfcGhvbmUiOiI0NDIwNTU1Mzc3MDkiLAogICAgImFjY291bnQiOnsgCiAgICAgICJhZGRpdGlvbmFsIjoiZ2FtZXIxMjM0NSIsCiAgICAgICJhZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAiZGF0ZSI6IjAxLTEwLTIwMjIiLAogICAgICAiY2hhbmdlX2luZGljYXRvciI6IjAxIiwKICAgICAgImNoYW5nZV9kYXRlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJwYXNzX2NoYW5nZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJwYXNzX2NoYW5nZV9kYXRlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJwdXJjaGFzZV9udW1iZXIiOjEyLAogICAgICAicHJvdmlzaW9uX2F0dGVtcHRzIjoxNiwKICAgICAgImFjdGl2aXR5X2RheSI6MjIsCiAgICAgICJhY3Rpdml0eV95ZWFyIjoyMjIyLAogICAgICAicGF5bWVudF9hZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAicGF5bWVudF9hZ2UiOiIwMS0xMC0yMDIyIiwKICAgICAgInN1c3BpY2lvdXNfYWN0aXZpdHkiOiIwMSIsCiAgICAgICJhdXRoX21ldGhvZCI6IjAxIiwKICAgICAgImF1dGhfdGltZSI6IjAxLTEwLTIwMjIxMzoxMiIsCiAgICAgICJhdXRoX2RhdGEiOiJsb2dpbl8wMTAyIgogICAgfQogIH0KfQ=====
 3

address_match
string

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

home_phone
string

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

work_phone
string

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

account
object

 Object with the customer's account information kept on file by the merchant. 3-43

additional
string

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

activity_day
integer

 Number of payment attempts in the last 24 hours, 3 characters maximum (999). 3-4-23-4

activity_year
integer

 Number of payment attempts in the last 365 days, 3 characters maximum (999). 3-4-33-4

age_indicator
string

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

auth_data
string

 Additional login information in free text, can contain up to 255 characters. 3-4-53-4

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)
 3-4-63-4

auth_time
string

 Date and time of the customer's most recent account login in the DD-MM-YYYYhh:mm format. 3-4-73-4

date
string

 Account creation date in the DD-MM-YYYY format. 3-4-83-4

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. 3-4-93-4

change_indicator
string

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

pass_change_date
string

 Date of the most recent password change or reset in the DD-MM-YYYY format. 3-4-113-4

pass_change_indicator
string

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

payment_age
string

 Card record creation date in the DD-MM-YYYY format. 3-4-133-4

payment_age_indicator
string

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

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). 3-4-153-4

purchase_number
integer

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

suspicious_activity
string

 Indicates the presence of suspicious activity. Possible values:
  • 01—no suspicious activity detected
  • 02—suspicious activity detected
 3-4-173-4

customer_shipping
string

Purchase shipping information.

A Base64 string converted from the customer JSON object with the relevant objects and parameters.

Figure 5. Example of a JSON object
{ 
  "customer":{ 
    "shipping":{ 
      "type":"01",
      "delivery_time":"01",
      "delivery_email":"test@gmail.com",
      "address_usage_indicator":"01",
      "address_usage":"01-10-2022",
      "city":"London",
      "country":"GB",
      "address":"Blackheath Ave",
      "postal":"SE10 8XJ",
      "region_code":"LND",
      "name_indicator":"01"
    }
  }
}
Figure 6. Example of a string
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAic2hpcHBpbmciOnsgCiAgICAgICJ0eXBlIjoiMDEiLAogICAgICAiZGVsaXZlcnlfdGltZSI6IjAxIiwKICAgICAgImRlbGl2ZXJ5X2VtYWlsIjoidGVzdEBnbWFpbC5jb20iLAogICAgICAiYWRkcmVzc191c2FnZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJhZGRyZXNzX3VzYWdlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJjaXR5IjoiTG9uZG9uIiwKICAgICAgImNvdW50cnkiOiJHQiIsCiAgICAgICJhZGRyZXNzIjoiQmxhY2toZWF0aCBBdmUiLAogICAgICAicG9zdGFsIjoiU0UxMCA4WEoiLAogICAgICAicmVnaW9uX2NvZGUiOiJMTkQiLAogICAgICAibmFtZV9pbmRpY2F0b3IiOiIwMSIKICAgIH0KICB9Cn0==
 4

shipping
object

 Object with shipping details. 4-14

address
string

 Shipping address, can contain up to 150 characters. 4-1-14-1

address_usage
string

 Date when the specified shipping address was used for the first time, in the DD-MM-YYYY format. 4-1-24-1

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
 4-1-34-1

city
string

 Shipping city, can contain up to 50 characters. 4-1-44-1

country
string

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

delivery_email
string

 The email to deliver purchased digital content to if the customer chooses email delivery. Can contain up to 255 characters. 4-1-64-1

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
 4-1-74-1

name_indicator
string

 Indicates whether the customer's name matches the recipient's name. Possible values:
  • 01—names match
  • 02—names do not match
 4-1-84-1

postal
string

 Shipping postal code, can contain up to 16 characters. 4-1-94-1

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.

 4-1-104-1

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
 4-1-114-1

customer_mpi_result
string

Information about the previous authentication attempt of the customer.

A Base64 string converted from the customer JSON object with the mpi_result object and other relevant objects and parameters.

Figure 7. Example of a JSON object
{ 
  "customer":{ 
    "mpi_result":{ 
      "acs_operation_id":"00000000-0005-5a5a-8000-016d3ea31d54",
      "authentication_flow":"01",
      "authentication_timestamp":"202210111050"
    }
  }
}
Figure 8. Example of a string
eyAKICAiY3VzdG9tZXIiOnsgCiAgICAibXBpX3Jlc3VsdCI6eyAKICAgICAgImFjc19vcGVyYXRpb25faWQiOiIwMDAwMDAwMC0wMDA1LTVhNWEtODAwMC0wMTZkM2VhMzFkNTQiLAogICAgICAiYXV0aGVudGljYXRpb25fZmxvdyI6IjAxIiwKICAgICAgImF1dGhlbnRpY2F0aW9uX3RpbWVzdGFtcCI6IjIwMjIxMDEwMTA1MCIKICAgIH0KICB9Cn0===
 5

mpi_result
object

 Object that contains information about the previous authentication attempt of the customer. 5-15

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. 5-1-15-1

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
 5-1-25-1

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. 5-1-35-1

billing_address
string

 Street of the customer's billing address. 6

billing_city
string

 City of the customer's billing address. 7

billing_country
string

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

billing_postal
string

 Postal code of the customer's billing address. 9

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

 10

customer_email
string

 Customer's email. 11

customer_phone
string

 Customer's phone number, contains between 4 and 24 digits. 12