Description of the 3DS Authentication Process

The 3D Secure (3DS) authentication in our payment gateway is an essential component designed to enhance the security of online transactions. This process focuses on verifying the cardholder's identity during transactions, adding an extra layer of fraud protection. Below is a detailed description of how the 3DS authentication is carried out on our platform.

There are two possible flows to evaluate the outcome of an authentication: the "frictionless" flow and the "challenge" flow:

Frictionless: The cardholder can complete the transaction without noticeable interruptions or additional steps that may cause friction or inconvenience.

Challenge: The cardholder is required to provide additional information or complete more advanced authentication steps.

3DS Authentication Initiation Process

1. Request
   • The merchant sends a request to the 3DS Authentication Initiation Endpoint, providing the parameters listed in the JSON below.
2. Generation of Authentication Data
   • The payment gateway uses the provided information to generate the necessary data for 3D Secure authentication.
3. Authentication Result
   • If the result of the authentication process indicates "isFrictionless: true", meaning the flow is frictionless, the necessary parameters for step 4 will be provided.
   • If the result indicates "isFrictionless: false", signaling a "challenge" flow that requires additional cardholder authentication, a URL will be returned. This URL will allow the user to complete the challenge step. Subsequently, the result will be sent to the endpoint specified in the "urlNotification" parameter.
4. Payment Processing
   • Once the authentication is complete, a response is generated indicating the outcome of the process.
   • If the authentication includes an ECI that provides liability shift for the transaction, the merchant sends the received data along with additional transaction data to the “MakePayment” endpoint.

📘

Important Notes

• It is crucial that “server-to-server” payment implementations comply with PCI DSS security standards to ensure the adequate protection of sensitive credit card information and to prevent potential security breaches.
• Transaction authentication via 3DS may incur additional costs.

The 3DS Authentication Initiation Endpoint is responsible for receiving the necessary data to initiate the 3D Secure authentication process for a specific transaction. This process is triggered in situations that require additional authentication, such as high-risk transactions or those that meet certain predefined criteria.

Request Example

Method: post
URL: http://{environment-domain}/api/v1/begin-threeds
HTTP Headers:Content-Type: application/json
Include authentication headers.

Example:

{
    "transactionType": "sale",
    "merchantId": "3ae25846-d5fe-40cc-a311-eb2de5174c29",
    "terminalId": "3ae25846-d5fe-40cc-a311-eb2de5174c29",
    "urlNotification": "https://comercio.shop/api/notificationResultd3ds",
    "order": {
        "merchantOrderId": "9a6ecf36-8265-11ee-b962-0242ac120002",
        "amount": "100.00",
        "currency": "484"
    },
    "card": {
        "cardNumber": "4111111111111111",
        "expiryMonth": "01",
        "expiryYear": "2025",
        "cvv2": "123",
        "holderName": "Clark Parker",
        "email": "[email protected]"
    },
    "aditionalDataToThreeds": {
        "ip": "192.168.0.1",
        "browserAcceptHeader": "text/html",
        "browserScreenColorDepth": "36",
        "browserJavaEnabled": false,
        "browserLanguage": "es/mx",
        "browserScreenHeight": "1920",
        "browserScreenWith": "1080",
        "browserTimezone": "60",
        "browserChallengeWindows": "4",
        "browserUserAgent": "Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)"
    }
}

Field Description

Example of a successful “frictionless” flow response and notification of the result in the “additional step” flow:

Http code 200

{
  "id": "5c51bebd-5b21-4ef3-b980-d41eb0b83568",
  "order": {
    "merchantOrderId": "9a6ecf36-8265-11ee-b962-0242ac120002",
    "amount": "100.00",
    "currency": "484"
  },
  "isFrictionless": true,
  "consumerAuthenticationInformation": {
    "acsTransactionId": "72f84fb0-9800-4961-b3b6-f9ced353deb5",
    "authenticationResult": "0",
    "authenticationStatusMsg": "Success",
    "cavv": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=",
    "indicator": "vbv",
    "eci": "05",
    "eciRaw": "05",
    "paresStatus": "Y",
    "specificationVersion": "2.2.0",
    "threeDSServerTransactionId": "60408358-4aec-4e67-bd53-3bacf7bfd8d4",
    "xid": "AAIBBYl3AgAAAMNQSEMgdQAAAAA=",
    "directoryServerTransactionId": "4890d3d3-b584-4a4d-84f0-1e820b924e7a"
    "submitTimeUtc": "2023-11-16T18:26:46Z",
    "status": "AUTHENTICATION_SUCCESSFUL",
    "clientReferenceInformation": {
      "code": "9205066"
    }
  }
} 

Field Description

Example successful response in the “additional step” flow:

Http code 200

{
  "id": "5c51bebd-5b21-4ef3-b980-d41eb0b83568",
  "order": {
    "merchantOrderId": "9a6ecf36-8265-11ee-b962-0242ac120002",
    "amount": "100.00",
    "currency": "484"
  },
  "isFrictionless": false,
  "urlRedirect": "https://{TODO domain}/threeds/1c128bb3-f8ca-4732-a91b-13a0db5a3272"
} 

Field Description