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.
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 (
recurringpayment type) as well as operations to change the authorised amount (incrementaloperation 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 |
|
|
| challenge flow |
|
|
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.
- 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).
- 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.
- The 3DS Server establishes whether 3‑D Secure is supported and whether collecting additional data is necessary.
- 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.
- 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:
- The payment platform sends the callback with the data for the iframe element to collect the customer's device characteristics to the web service.
- The web service sends a synchronous response acknowledging the receipt of the callback to the payment platform.
- The web service opens the iframe element to collect the customer's device characteristics.
- The iframe script collects the data about the customer's device and sends it to issuer's Access Control Server.
- The issuer sends a data receipt notification to the web service.
- The web service sends the authentication initiation request to the URL provided by Ecommpay.
- The payment platform receives the request.
- The payment platform accepts and validates the request.
- The payment platform sends the response acknowledging the receipt of the request and containing the result of the validity check to the web service.
- The payment platform forwards the authentication request to the 3DS Server.
- The 3DS Server forwards the request to the Directory Server.
- The Directory Server forwards the request to the Access Control Server.
- The issuer authenticates the customer. If the issuer selects the frictionless flow, the Access Control Server sends a message with the authentication 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:
- 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.
- The payment platform sends the customer redirection data to the web service.
- The web service redirects the customer 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 acknowledging the receipt of the result to the Access Control Server through the Directory Server.
- The Access Control Server redirects the customer to the web service and sends the authentication result 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 with 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 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:
- Check the integrity of data in the callback by verifying the signature.
- Confirm accepting and validating the callback by sending a
200 OKsynchronous response to the platform. - Open the iframe element to collect the customer's device characteristics using the data received in the callback (details).
- Accept the message acknowledging receipt of data from the issuer's Access Control Server.
- Send the authentication initiation request to the payment platform.
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:
- Check the integrity of data in the callback by verifying the signature.
- Confirm accepting and validating the callback by sending a
200 OKsynchronous response to the platform. - Redirect the customer to the authentication page using the data received in the callback (details) within 30 seconds after the callback was received.
- Accept the authentication result from the issuer.
- Send a payment completion request with the authentication result within 30 minutes after the callback that indicates the need for redirection was received.
- If the cascading payments option is enabled (details) and your web service receives an additional callback containing the
cascading_with_redirectparameter (set totrue), your web service is required to do the following:- Repeat step 1-2 of this procedure, accepting and validating the callback.
- Display an authentication attempt error message to the customer.
- Receive the customer's consent for retrying authentication.
- Repeat steps 3-5 of this procedure.
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 headeraccept_language_header—value of the Accept-Language HTTP request header that specifies the preferred localisation languagebrowser—value of the HTTP User-Agent request headerip_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 pixeljava_enabled—indicator that specifies whether the customer's browser supports Javajs_enabled—indicator that specifies whether the customer's browser supports JavaScriptlanguage—code of the customer's browser languagescreen_res—screen resolution of the customer's device, in pixels, with anxcharacter 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)
"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.
- 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(), }; } - 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; } }
- 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 }
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 | |
|---|---|---|
|
|
Object that contains the web service URLs used for authentication. | 1 |
|
|
The URL to redirect the customer to the web service after authentication. | 1-11 |
|
|
The URL the web service uses for accepting data receipt acknowledgement from ACS. | 1-21 |
|
|
Object that contains customer data. | 2 |
|
|
Customer's IP address. | 2-12 |
|
|
Screen resolution of the customer's device, in pixels, with an x character as a delimiter (for example, 1920x1080). |
2-22 |
|
|
Customer's email. | 2-32 |
|
|
Customer's phone number, contains between 4 and 24 digits. | 2-42 |
|
|
Object that contains the customer's card details. | 3 |
|
|
The name of the cardholder, spelled as specified on the card. | 3-13 |
{
"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 |
|---|---|---|
|
|
Object that contains customer data. | 2 |
|
|
Value of the HTTP Accept request header as received from the customer's browser. | 2-12 |
|
|
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 |
|
|
Value of the HTTP User-Agent request header as received from the customer's browser. | 2-22 |
|
|
The colour depth of the screen as supported by the customer's device, bits per pixel. | 2-32 |
|
|
Indicates whether the customer's browser supports Java. | 2-42 |
|
|
Indicates whether the customer's browser supports JavaScript. | 2-52 |
|
|
The code of the customer's browser language. | 2-62 |
|
|
The name of the time zone the customer's browser is set to (for example, Australia/Adelaide). |
2-82 |
|
|
The difference between a date as evaluated in the UTC time zone and the same date as evaluated in the browser time zone, specified in minutes, (for example, 570). |
2-92 |
|
|
Indicates whether the customer's billing address matches the address specified in the Possible values:
|
2-102 |
|
|
Customer's home phone number, contains between 4 and 24 digits (for example, 44991234567). |
2-112 |
|
|
Customer's work phone number, contains between 4 and 24 digits (for example, 44997654321). |
2-122 |
|
|
Object with the customer's account information kept on file by the merchant. | 2-132 |
|
|
Additional information about the customer's account in free text, for example, its identifier. Can contain up to 64 characters. | 2-13-12-13 |
|
|
Number of payment attempts in the last 24 hours, 3 characters maximum (999). |
2-13-22-13 |
|
|
Number of payment attempts in the last 365 days, 3 characters maximum (999). |
2-13-32-13 |
|
|
Number of days since the customer account was created. Possible values:
|
2-13-42-13 |
|
|
Additional login information in free text, can contain up to 255 characters. | 2-13-52-13 |
|
|
Indicates how the customer was authenticated during their most recent login to the web service. Possible values:
|
2-13-62-13 |
|
|
Date and time of the customer's most recent account login in the DD-MM-YYYYhh:mm format. |
2-13-72-13 |
|
|
Account creation date in the DD-MM-YYYY format. |
2-13-82-13 |
|
|
Date of the most recent change to the account, except for the password change or password reset, in the DD-MM-YYYY format. |
2-13-92-13 |
|
|
Number of days since the most recent change to the account, except for the password change or password reset. Possible values:
|
2-13-102-13 |
|
|
Date of the most recent password change or reset in the DD-MM-YYYY format. |
2-13-112-13 |
|
|
Number of days since the most recent password change or reset. Possible values:
|
2-13-122-13 |
|
|
Card record creation date in the DD-MM-YYYY format. |
2-13-132-13 |
|
|
Number of days since the payment card details were saved to a customer's account. Possible values:
|
2-13-142-13 |
|
|
Number of attempts to save new card details to a customer's account in the last 24 hours, 3 characters maximum (999). |
2-13-152-13 |
|
|
Number of purchases made via the customer's account in the last 6 months, 4 characters maximum (9999). |
2-13-162-13 |
|
|
Indicates the presence of suspicious activity. Possible values:
|
2-13-172-13 |
|
|
Object with information about the customer's billing address. | 2-162 |
|
|
Street of the customer's billing address. | 2-16-12-16 |
|
|
City of the customer's billing address. | 2-16-22-16 |
|
|
Country of the customer's billing address in the ISO 3166-1 alpha-2 format. | 2-16-32-16 |
|
|
Postal code of the customer's billing address. | 2-16-42-16 |
|
|
State, province, or region code in the ISO 3166-2 format, for example, DEV for Devon.If you specify this parameter, you also need to specify and populate the |
2-16-52-16 |
|
|
Object with shipping details. | 2-172 |
|
|
Shipping address, can contain up to 150 characters. | 2-17-12-17 |
|
|
Date when the specified shipping address was used for the first time, in the DD-MM-YYYY format. |
2-17-22-17 |
|
|
Number of days since the specified shipping address was used for the first time. Possible values:
|
2-17-32-17 |
|
|
Shipping city, can contain up to 50 characters. | 2-17-42-17 |
|
|
Shipping country code in the ISO 3166-1 alpha-2 format (for example, GB). | 2-17-52-17 |
|
|
The email to deliver purchased digital content to if the customer chooses email delivery. Can contain up to 255 characters. | 2-17-62-17 |
|
|
Delivery time. Possible values:
|
2-17-72-17 |
|
|
Indicates whether the customer's name matches the recipient's name. Possible values:
|
2-17-82-17 |
|
|
Shipping postal code, can contain up to 16 characters. | 2-17-92-17 |
|
|
State, province, or region code in the ISO 3166-2 format, for example, DOR for Dorset.If you specify this parameter, you also need to specify and populate the |
2-17-102-17 |
|
|
Delivery option selected by the customer. Possible values:
|
2-17-112-17 |
|
|
Object that contains information about the previous authentication attempt of the customer. | 2-182 |
|
|
The identifier that the issuer assigned to the previous operation of the customer and returned in the acs_operation_id parameter of the callback with payment processing result. Can contain up to 36 characters. |
2-18-12-18 |
|
|
The flow used by the issuer to authenticate the cardholder when processing the previous operation. It is a value of the Possible values:
|
2-18-22-18 |
|
|
Date and time of the previous successful customer authentication as returned in the mpi_timestamp parameter of the callback with payment processing result. |
2-18-32-18 |
|
|
Object with payment information. | 3 |
|
|
Indicates whether the challenge flow is preferred. Possible values:
|
3-13 |
|
|
The dimensions of a window in which the authentication page opens. Possible values:
|
3-23 |
|
|
The date the preordered merchandise or service will be available in the DD-MM-YYYY format. |
3-33 |
|
|
Indicates whether the purchase is a preorder. Possible values:
|
3-43 |
|
|
Indicates whether the customer is buying the merchandise or the service for the first time or it is a repeat purchase. Possible values:
|
3-53 |
|
|
Object with information about a purchase made with a prepaid or gift card. | 3-63 |
|
|
The amount of the purchase made with a prepaid or gift card in the smallest units of currency. | 3-6-13-6 |
|
|
Currency of the purchase made with a prepaid or gift card in the ISO 4217 alpha-3 format (for example, GBP). | 3-6-23-6 |
|
|
Number of prepaid or gift cards used for making the purchase. | 3-6-33-6 |
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.
{
"threeds2":{
"iframe":{
"url":"https://example.com",
"params":{
"3DSMethodData":"eyAidGhyZWVNrkthelJSUFQwaWZYMCUzQ",
"threeDSMethodData":"eyAidGhjNjMGQ4YWU4LTA2u0wyWmtObGRdwR"
}
}
}
}
<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.
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, passtrue; if not, passfalse.
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.
{
"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.
{
"threeds2":{
"redirect":{
"url":"https://example.com/ACS",
"params":{
"creq":"ewogICAiYWNzVHJhbnNJCIDAtMDAwMDAwMDAwN2Q5Ip9",
"threeDSSessionData":"240000549"
}
}
}
}
<!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.
cres=ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMiLAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ&threeDSSessionData=240000554
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.
{
"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 sideds_operation_id—operation identifier on the Directory Server side of the global card networkacs_operation_id—operation identifier on the issuer's Access Control Server sidempi_timestamp—authentication time and datecardholder_info—the message you are recommended to display when notifying the customer about the payment resultauthentication_flow—authentication flow indicator:01for the frictionless flow,02for 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.
{
"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...=="
}