Introduction

This document describes the step-by-step process to implement the 3DS 2.0 e-commerce authentication protocol on your website, using our javascript library, or in your mobile application, using our SDKs for iOS and Android.

This document will detail the configuration for the homologation environment. The aim of this document is to share two example projects (with and without 3DS) so that developers can get to grips with implementing this protocol in their own e-commerce, as well as demonstrating all the steps and actions required to carry out the implementation. The basic projects shared in the next topic are examples of e-commerce pages (an OC) that should be used as a reference for implementing 3DS 2.0. Naturally, each client who consumes this documentation will have their own e-commerce formats, file names, nomenclatures, methods and classes with their own names.

Target Audience

The Target Audience of the document is as follows:

• Developers from ADIQ clients who intend to implement the protocol.

About 3DS 2.0

In an effort to minimize the fraud rate without harming the conversion rate, the payment industry has developed 3DS 2.0, which is part of the payment flow that allows banks to check whether an online purchase is fraudulent.

The solution replaces 3DS 1.0, which redirected the consumer to the bank's website. As well as repelling customers due to the fragmented experience, this form of authentication was still a problem for international companies, as its adoption varied greatly between countries and banks. In order to improve security related to payments, a series of stricter rules have been created in Europe in recent years, and the 3D Secure 2.0 protocol is among them. The aim is to render the authentication process more dynamic and secure.

The 3DS is mandatory for debit transactions.

The service is available at an additional cost.

How does the 3DS work in real life?

The 3DS 2.0 eliminates redirecting the customer to the bank's website. This is how it works: the customer fills in their card information (credit or debit) and confirms the purchase. From this stage, the payment processor gathers up to 100 different pieces of information about the transaction, which can range from the card number to the IP address, and sends this data to the card-issuing bank using certified technology, guaranteeing smoother integration between websites and applications, always with the greatest possible security.

Flowchart of 3DS Explained

Below is a flowchart of a successful scenario, without challenge:

Image Detail:

1. When the customer who is going to pay for the purchase has already filled in the card details on the screen, the Authozation3ds() method must be called to start processing;
2. It is necessary to generate the “code3ds”, which is a string with a length of 36 characters (the getThreeDsCode() method returns the “code3ds”). This 3ds code is important for being informed in the Gateway API “v1/payments” and “v1/payments/validate”;

                
                
{
   "paymentAuthorization":{
      "paymentId":"010003872201241223520014983807920000000000",
      "authorizationCode":"021150",
      "orderNumber":"17836-55544",
      "expireAt":"2024-02-14T09:23:52.8778532-03:00",
      "amount":2166,
      "returnCode":"0",
      "description":"Sucesso",
      "releaseAt":"2024-01-24T09:23:52-03:00"
   },
   "threeDs":{
      "status":"Silent",
      "eci":"02",
      "threeDsVersion":"2.2.0",
      "veresEnrolled":"Y",
      "paresStatus":"Y",
      "threeDsStatus":"AUTHENTICATION_SUCCESSFUL"
   }
}
                			
            
        

3. Capture the information below from the Client Browser. This data is in the Validations topic of this documentation (This step is exclusive to javascript implementation).
   • httpBrowserLanguage
   • httpBrowserJavaEnabled
   • httpBrowserJavaScriptEnabled
   • httpBrowserColorDepth
   • httpBrowserScreenHeight
   • httpBrowserScreenWidth
   • httpBrowserTimeDifference
   • userAgentBrowserValue
4. Submit the “code3ds” and the fields about the browser mentioned in step 3 to the Backend, when necessary;
5. In the Gateway API “v1/payments”, enter this data and see how to enter it in the developer documentation (https://developers.adiq.io/manual/ecommerce) ;
6. Check in the “v1/payments” response that will return the data of the successfully executed payment.

Below is a flowchart of the success scenario:

                
                
{
   "threeDs":{
      "status":"Challenge",      
      "threeDsVersion":"2.2.0",
      "ascUrl":"https://merchantacsstag.cardinalcommerce.com/MerchantASSWeb/pareq.jsp?vaa=b&gold=AAAAA",
      "authenticationTransactionId":"WUcomZFeccuB0fjhD8z0",
      "pareq":"3232a0d7e6cf46908cede9fb453536433232a0d7e6cf46908cede9fb453536433232a0d7e6cf46908cede9fb453536433232a0d7e6cf46908cede9fb453536433232a0d7e6cf46908cede9fb453536433232a0d7e6cf46908cede9fb45353643"
   }   
}
                			
            
        

                
                
{
   "paymentAuthorization":{
      "returnCode":"0",      
      "description":"Sucesso",
      "paymentId":"02008028610304095215000006201850000000",
      "authorizationCode":"043711",
      "orderNumber":"0000000001",
      "expireAt":"2019-09-24T13:20:52.8775511-03:00",
      "amount": 1035,
      "releaseAt": "2019-09-24T13:20:52.8775511-03:00"
   }
}
                			
            
        

Debit without 3DS

All debit card transactions in Brazil must go through a 3DS 2.0 authentication to be authorized by the issuer. Exceptions to this rule include specific BINs where such authentication is not required .However, with permission from the card networks/issuers, merchants can obtain authorization for their MID to process these types of cards without needing 3DS 2.0 authentication. This allows for recurring transactions with debit cards.

Required

• Ensure that the validation that allows transacting without the 3DS is enabled in the ADIQ (Customer Service Team).
• It is essential to obtain authorization from the issuer to process transactions without 3DS, requiring registration with them.
• Do not provide 3DS data during the transaction.

JavaScript Implementation

Links and Downloads

In order to implement 3DS, please refer to the 3ds javascript links below.

Download link for the Javascript Homologation Library file “adiq-3ds-package -1.0.2- hml-min.js": https://github.com/adiqpagamentos/SDK-3DS-JS-Web/blob/main/adiq-3ds-package-hml-1.0.2-min.zip

Download link for the Production Javascript Library file “adiq-3ds-package-1.0.2-min.js”: https://github.com/adiqpagamentos/SDK-3DS-JS-Web/blob/main/adiq-3ds-package-1.0.2-min.zip

In order to use the files, it is necessary to download them and replace the files with the latest ones each time the code is updated.

NOTE: It is highly not recommended to use DNS references due to unexpected errors during updates.

Procedures

Implementation of the 3DS 2.0 Protocol

The implementation of the 3DS 2.0 protocol consists of linking a Javascript call to the button that executes a purchase. This button will presumably be on a page of the e-commerce website, specifically on the screen where the end customer makes the purchase after inserting their credit/debit card.

Requirement

• Possess a jQuery (version 3.3.1 or above).

Process Checkpoints

• Inject the JavaScript library;
• Create and update mobile code;

Step 1 - Inject Javascript Library adiq-3ds-package-hml-1.0.2-min.js.

To inject the JavaScript library into your directory where you load “jquery.min.js”, you must download

• file “adiq-3ds-package-hml-1.0.2-min.js” which is in topic 2.

This file should be placed in your directory as shown in the attached image:

Step 2 - Front-End Development

The second step is to develop the Front-End code, specifically on the e-commerce payment page where the “pay” button is available to end customers. This is the same screen where the credit/debit card is entered.

The following code fragment is an example of an “index.js” file that simulates a payment page. Pay attention only to the colored portions of this page, which are the portions referring to the 3DS implementation; the other gray portions are code expected on the e-commerce site (in this case, the example base project):

The following code fragment is an example of a “_Layout.cshtml” file that simulates where the 3ds script is placed adiq-3ds-package-hml-1.0.2-min.js, attach this file. Pay attention only to the colored parts of this page, which are the parts referring to the 3DS implementation; the other gray parts are the code expected on the e-commerce site (in this case, the example base project):

The following code fragment is an example of an “index.cshtml” file that simulates the HTML payment page. Pay attention only to the colored portions of this page, which are the portions referring to the 3DS implementation; the other gray portions are code expected on the e-commerce site (in this case, the example base project):

Capturing browser fields via JavaScript

Below is a suggestion for capturing the fields below via JavaScript:

1. httpAcceptBrowserValue;
   • Which extensions the browser can accept; Example: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8
2. httpAcceptContent
   • Which contents will be accepted; Example: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8
3. httpBrowserLanguage
   • var httpBrowserLanguage = navigator.language || navigator.userLanguage;
4. httpBrowserJavaEnabled
   • navigator.javaEnabled() == true ? "Y" : "N";
5. httpBrowserJavaScriptEnabled
   • navigator.javaEnabled() == true ? "Y" : "N";
6. httpBrowserColorDepth
   • screen.colorDepth
7. httpBrowserScreenHeight
   • window.innerHeight
8. httpBrowserScreenWidth
   • window.innerWidth
9. httpBrowserTimeDifference
   • new Date().getTimezoneOffset()
10. userAgentBrowserValue
    • navigator.userAgent

Required fields and validations in the e-commerce gateway

3DS Data

All the above fields are in the Body.

Buyer Data

All the above fields are in the Body.

All the above fields are in the Body.

                
                
{
    "Payment":
    { 
        "TransactionType": "debit", 
        "Amount":1111, 
        "CurrencyCode": "brl", 
        "ProductType": "debito", 
        "Installments": 1, 
        "CaptureType": "ac", 
        "Recurrent":false 
    }, 
    "CardInfo":
    { 
        "NumberToken":"d56109ce-6a3b-4190-beea-1c975e8cd486", 
         "CardholderName":"Luiz Silveira Neto", 
         "SecurityCode":"123", 
         "Brand": "mastercard", 
         "ExpirationMonth":"01", 
         "ExpirationYear":"29" 
    }, 
    "SellerInfo":
    { 
         "OrderNumber":"1110197548565", 
         "SoftDescriptor":"PAG*TESTE", 
         "UrlSite3DS":"empresa.ecommerce.com.br", 
         "Code3DS":"aa415dc21f4e4e7ca083a1473d5c4c58",
         "ThreeDsDataOnly":"false"
    }, 
    "Customer":
    { 
       "DocumentType": "cpf", 
       "DocumentNumber":"51115672088", 
        "FirstName":"Luiz", 
       "LastName":"Silveira Neto", 
       "Email":"luiz.silveira@teste.rafael.com", 
       "PhoneNumber":"1122542454", 
       "MobilePhoneNumber":"11987683332", 
       "Address":"Rua Luiz Vieira, 134", 
       "Complement":"apto. 34 - Vila Guarani", 
       "City":"São Paulo", 
       "State":"SP", 
       "ZipCode":"09876-098", 
       "IpAddress":"45.233.232.248", 
       "Country":"BR" 
    }, 
    "Sellers":[ 
    ], 
    "DeviceInfo":
    {        
        "HttpAcceptBrowserValue":"text/html,application/xhtml+xml,application/xml;
        q=0.9,image/webp,image/apng,*/*;q=0.8",        
        "HttpAcceptContent":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8", 
       "HttpBrowserLanguage":"pt-BR", 
       "HttpBrowserJavaEnabled":"N", 
       "HttpBrowserJavaScriptEnabled":"Y", 
       "HttpBrowserColorDepth":"24", 
       "HttpBrowserScreenHeight":"937", 
       "HttpBrowserScreenWidth":"1920", 
       "HttpBrowserTimeDifference":"180", 
       "UserAgentBrowserValue":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.102 Safari/537.36" 
    }
}
                			
            
        

                
                
{
   "paymentAuthorization":{
      "returnCode":"0",      
      "description":"Sucesso",
      "paymentId":"02008028610304095215000006201850000000",
      "authorizationCode":"043711",
      "orderNumber":"0000000001",
      "expireAt":"2019-09-24T13:20:52.8775511-03:00",
      "amount": 1035,
      "releaseAt": "2019-09-24T13:20:52.8775511-03:00"
   },
   "threeDs":{
      "status":"Silent",
      "eci":"02",
      "threeDsVersion":"2.1.0",
      "veresEnrolled":"Y",
      "paresStatus":"Y",
      "threeDsStatus":"AUTHENTICATION_SUCCESSFUL"
   }
}
                			
            
        

All the above Properties are in the Body.

Payment Validation with 3DS Challenge

In order to validate a transaction with 3DS Challenge, you need to send a request using the POST method to the “Validate” resource, as shown in the example:

Request

                
                
 { 
        "code3ds": "dbe5a61a-836d-45dd-82c1-52d0c5e3c010", 
         "validateToken": 
            "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1ZWNkNzVkNjNlMzFiYzQ3MWExZWM2MWYiLCJpYXQi
             OjE1OTQyMzI4MTcsImV4cCI6MTU5NDI0MDAxNywianRpIjoiYjFmNjEyZWEtMDRhZS00ZDY2LW
             EzM2QtY2I1MjgwOGY4M2FlIiwiQ29uc3VtZXJTZXNzaW9uSWQiOiIwX2E3MGIzMjk0LTI1MTIt
             NDc0ZS05OTcxLTZmZTk3YTllYWYzNiIsIlJlZmVyZW5jZUlkIjoiN2Y0ODc3YmVkODVhNDU2Mm
             IxYjNlZjk4MWQ2MjViY2UiLCJhdWQiOiIwMzc2NTk3ODgyMTU0NWRiOTBjN2Y1YmE1ZDNmNWU1
             NiIsIlBheWxvYWQiOiJ7XCJQYXltZW50XCI6e1wiVHlwZVwiOlwiQ0NBXCIsXCJQcm9jZXNzb3
             JUcmFuc2FjdGlvbklkXCI6XCJHc2pMM1lkczVmWk80MzBXYk1RMFwiLFwiRXh0ZW5kZWREYXRh
             XCI6e1wiQW1vdW50XCI6XCIxMTExXCIsXCJDdXJyZW5jeUNvZGVcIjpcIjk4NlwifX0sXCJFcn
             Jvck51bWJlclwiOjAsXCJFcnJvckRlc2NyaXB0aW9uXCI6XCJTdWNjZXNzXCJ9In0.9oBbxbtu
             hZyZaE_vuu6UzU-Mp5BjK2FNp5XAfoDy2uQ"         
}
                	
            
        

                
                
 { 
   "paymentAuthorization":{ 
      "returnCode":"0", 
      "description":"Sucesso", 
      "paymentId":"020006204409231653310000023790740000000000", 
      "authorizationCode":"026603", 
      "orderNumber":"3979908797721", 
      "amount":1111, 
      "releaseAt":"2020-09-23T16:53:34+00:00" 
    },
    "threeDs":{
       "status":"Challenge",
       "eci":"02",
       "threeDsVersion":"2.2.0",
       "paresStatus":"Y",
       "threeDsStatus":"AUTHENTICATION_SUCCESSFUL"
    }
} 
                	
            
        

                
                
 { 
    "FailureDetails":[ 
        { 
            "tag": "string",
            "description": "reason for failure" 
        }
    ]
} 
                	
            
        

All the above Properties are in the Body.

Domains

CyberSource Answer Domains

• consumerAuthenticationInformation.veresEnrolled
  • Y – Yes, bank has 3DS security protocol and will return AscUrl
  • N – No, bank does not have 3DS security protocol
  • U – Unavailable, 3DS or ACS unavailable for authentication at the time of the request.
  • B - Bypass, The merchant authentication rule is triggered to bypass authentication in this use case
• consumerAuthenticationInformation.paresStatus
  • Y – Authentication successful
  • N – Authentication failed / Account not verified / Transaction denied
  • U - Authentication could not be completed
  • A – Transaction attempted successfully
  • R – Authentication rejected
  • D – Challenge required, decoupled authentication confirmed
  • I – Informational only
• consumerAuthenticationInformation.eciRaw
• 02 or 05 – Success
• 01 or 06 – Attempt
• 00 or 07 – Transaction without 3DS
• consumerAuthenticationInformation.cardholderMessage
• Text message provided by the ACS/Issuer to the bearer during a Frictionless authentication process.
• status
  • AUTHENTICATION_SUCCESSFUL
  • PENDING_AUTHENTICATION
  • INVALID_REQUEST
  • AUTHENTICATION_FAILED
• errorInformation.reason
  • INVALID_MERCHANT_CONFIGURATION
  • CONSUMER_AUTHENTICATION_REQUIRED
  • CONSUMER_AUTHENTICATION_FAILED
  • AUTHENTICATION_FAILED

Android SDK implementation

Links and Downloads

In order to implement 3DS, below are some links to the Android Adiq SDK for 3DS and the Android SDK from the Cardinal company.

Download link for the SDK Android Adiq Homologation file “adiq-3ds-package-1.0.0-hml.aar": https://github.com/adiqpagamentos/SDK_3DS2.0_Android_Mobile/blob/main/adiq-3ds-package-1.0.0-hml.aar.zip

Download link for the SDK Android Adiq Production file “adiq-3ds-package-1.0.0.aar”: https://github.com/adiqpagamentos/SDK_3DS2.0_Android_Mobile/blob/main/adiq-3ds-package-1.0.0.aar.zip

Download link for the SDK Android Cardinal file “cardinalmobilesdk-2.2.7-5.aar": https://github.com/adiqpagamentos/SDK_3DS2.0_Android_Mobile/blob/main/cardinalmobilesdk-2.2.7-5.aar.zip

In order to use the files, it is necessary to download them and replace the files with the latest ones each time the code is updated.

NOTE: It is strongly not recommended to use the SDK downloaded from other unofficial sources.

Procedures

Implementation of the 3DS 2.0 Protocol

The implementation of the 3DS 2.0 protocol consists of linking a call to the Adiq Android SDK to the button that executes a purchase. This button will presumably be in a view of the ecommerce Android application, specifically in the view where the end customer makes the purchase after inserting their credit/debit card.

Requirement

• Android version 5 (Lollipop, Level 21) or above

Process Checkpoints

• Reference the SDKs Android from Adiq and Cardinal;
• Create and update front-end code;
• Update Back-End codes;

Step 1 - Reference the SDKs for Android adiq-3ds-package-1.0.0-hml.aar and cardinalmobilesdk-2.2.7-5.aar.

After clicking on the JAR/AAR Dependency item, select the directory where the SDKs were extracted.

Step 2 – Mobile Development

The SDK has a single class for use, Authorization3ds, which has 3 public methods:

• getThreeDsCode(request: ExecuteThreeDsRequestDto, timeoutToCodeThreeDsInSeconds: Int = 10): String
• initChallenge(pareq: String, transactionId: String, timeoutToChallengeInMinutes: Int = 5): ChallengeResponseDto
• cleanup()

The getThreeDsCode() method is responsible for collecting the data from the mobile device that will later be used to analyze the transaction, and from the card data and the merchant reference code, it returns the “code3ds”, which must be sent to the Gateway API “v1/payments”

Afterwards, check that the response from “v1/payments” has returned the “threeDs” property. If it returns the status “challenge”, then it must submit the challenge to the client, calling the initChallenge() method of the SDK from Adiq. This method receives the “pareq” and “authenticationTransactionId” properties returned from “v1/payments” as parameters. If the challenge is answered correctly, the “initChallenge” method will return a token named “serverJwt”.

The “serverJwt” must be sent to the Gateway API “v1/payments/validate” to process the payment. At the end of the transaction, the cleanup() method of the SDK from Adiq must be executed to undo the current instance of the 3DS service.

For more information on how to consume the APIs of the Gateway, please refer to the developers' documentation (https://developers.adiq.io/manual/ecommerce).

Required fields and validations in the e-commerce gateway

3DS Data

All the above fields are in the Body.

Buyer Data

All the above fields are in the Body.

All the above fields are in the Body.

                
                
{
    "Payment":
    { 
        "TransactionType": "debit", 
        "Amount":1111, 
        "CurrencyCode": "brl", 
        "ProductType": "debito", 
        "Installments": 1, 
        "CaptureType": "ac", 
        "Recurrent":false 
    }, 
    "CardInfo":
    { 
        "NumberToken":"d56109ce-6a3b-4190-beea-1c975e8cd486", 
         "CardholderName":"Luiz Silveira Neto", 
         "SecurityCode":"123", 
         "Brand": "mastercard", 
         "ExpirationMonth":"01", 
         "ExpirationYear":"29" 
    }, 
    "SellerInfo":
    { 
         "OrderNumber":"1110197548565", 
         "SoftDescriptor":"PAG*TESTE", 
         "UrlSite3DS":"empresa.ecommerce.com.br", 
         "Code3DS":"aa415dc21f4e4e7ca083a1473d5c4c58",
         "ThreeDsDataOnly":"false"
    }, 
    "Customer":
    { 
       "DocumentType": "cpf", 
       "DocumentNumber":"51115672088", 
        "FirstName":"Luiz", 
       "LastName":"Silveira Neto", 
       "Email":"luiz.silveira@teste.rafael.com", 
       "PhoneNumber":"1122542454", 
       "MobilePhoneNumber":"11987683332", 
       "Address":"Rua Luiz Vieira, 134", 
       "Complement":"apto. 34 - Vila Guarani", 
       "City":"São Paulo", 
       "State":"SP", 
       "ZipCode":"09876-098", 
       "IpAddress":"45.233.232.248", 
       "Country":"BR" 
    }, 
    "Sellers":[ 
    ], 
    "DeviceInfo":
    {        
       "DeviceChannel":"SDK"
    }
}
                			
            
        

                
                
{
   "paymentAuthorization":{
      "returnCode":"0",      
      "description":"Sucesso",
      "paymentId":"02008028610304095215000006201850000000",
      "authorizationCode":"043711",
      "orderNumber":"0000000001",
      "expireAt":"2019-09-24T13:20:52.8775511-03:00",
      "amount": 1035,
      "releaseAt": "2019-09-24T13:20:52.8775511-03:00"
   },
   "threeDs":{
      "status":"Silent",
      "eci":"02",
      "threeDsVersion":"2.1.0",
      "veresEnrolled":"Y",
      "paresStatus":"Y",
      "threeDsStatus":"AUTHENTICATION_SUCCESSFUL"
   }
}
                			
            
        

All the above Properties are in the Body.

Payment Validation with 3DS Challenge

In order to validate a transaction with 3DS Challenge, you need to send a request using the POST method to the “Validate” resource, as shown in the example:

Request

                
                
 { 
        "code3ds": "dbe5a61a-836d-45dd-82c1-52d0c5e3c010", 
         "validateToken": 
            "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1ZWNkNzVkNjNlMzFiYzQ3MWExZWM2MWYiLCJpYXQi
             OjE1OTQyMzI4MTcsImV4cCI6MTU5NDI0MDAxNywianRpIjoiYjFmNjEyZWEtMDRhZS00ZDY2LW
             EzM2QtY2I1MjgwOGY4M2FlIiwiQ29uc3VtZXJTZXNzaW9uSWQiOiIwX2E3MGIzMjk0LTI1MTIt
             NDc0ZS05OTcxLTZmZTk3YTllYWYzNiIsIlJlZmVyZW5jZUlkIjoiN2Y0ODc3YmVkODVhNDU2Mm
             IxYjNlZjk4MWQ2MjViY2UiLCJhdWQiOiIwMzc2NTk3ODgyMTU0NWRiOTBjN2Y1YmE1ZDNmNWU1
             NiIsIlBheWxvYWQiOiJ7XCJQYXltZW50XCI6e1wiVHlwZVwiOlwiQ0NBXCIsXCJQcm9jZXNzb3
             JUcmFuc2FjdGlvbklkXCI6XCJHc2pMM1lkczVmWk80MzBXYk1RMFwiLFwiRXh0ZW5kZWREYXRh
             XCI6e1wiQW1vdW50XCI6XCIxMTExXCIsXCJDdXJyZW5jeUNvZGVcIjpcIjk4NlwifX0sXCJFcn
             Jvck51bWJlclwiOjAsXCJFcnJvckRlc2NyaXB0aW9uXCI6XCJTdWNjZXNzXCJ9In0.9oBbxbtu
             hZyZaE_vuu6UzU-Mp5BjK2FNp5XAfoDy2uQ"         
}
                	
            
        

                
                
 { 
   "paymentAuthorization":{ 
      "returnCode":"0", 
      "description":"Sucesso", 
      "paymentId":"020006204409231653310000023790740000000000", 
      "authorizationCode":"026603", 
      "orderNumber":"3979908797721", 
      "amount":1111, 
      "releaseAt":"2020-09-23T16:53:34+00:00" 
   },
   "threeDs":{
      "status":"Challenge",
      "eci":"02",
      "threeDsVersion":"2.2.0",
      "paresStatus":"Y",
      "threeDsStatus":"AUTHENTICATION_SUCCESSFUL"
   }
} 
                	
            
        

                
                
 { 
    "FailureDetails":[ 
        { 
            "tag": "string",
            "description": "reason for failure" 
        }
    ]
} 
                	
            
        

All the above Properties are in the Body.

Domains

CyberSource Answer Domains

• consumerAuthenticationInformation.veresEnrolled
  • Y – Yes, bank has 3DS security protocol and will return AscUrl
  • N – No, bank does not have 3DS security protocol
  • U – Unavailable, 3DS or ACS unavailable for authentication at the time of the request.
  • B - Bypass, The merchant authentication rule is triggered to bypass authentication in this use case
• consumerAuthenticationInformation.paresStatus
  • Y – Authentication successful
  • N – Authentication failed / Account not verified / Transaction denied
  • U - Authentication could not be completed
  • A – Transaction attempted successfully
  • R – Authentication rejected
  • D – Challenge required, decoupled authentication confirmed
  • I – Informational only
• consumerAuthenticationInformation.eciRaw
• 02 or 05 – Success
• 01 or 06 – Attempt
• 00 or 07 – Transaction without 3DS
• consumerAuthenticationInformation.cardholderMessage
• Text message provided by the ACS/Issuer to the bearer during a Frictionless authentication process.
• status
  • AUTHENTICATION_SUCCESSFUL
  • PENDING_AUTHENTICATION
  • INVALID_REQUEST
  • AUTHENTICATION_FAILED
• errorInformation.reason
  • INVALID_MERCHANT_CONFIGURATION
  • CONSUMER_AUTHENTICATION_REQUIRED
  • CONSUMER_AUTHENTICATION_FAILED
  • AUTHENTICATION_FAILED

SDK iOS Implementation

Links and Downloads

In order to implement 3DS, below are some links to the 3ds iOS Adiq SDK

Download link for the SDK iOS Adiq Homologation file “adiq-3ds-package-1.0.0-hml.xcframework": https://github.com/adiqpagamentos/SDK_3DS2.0_iOS_Mobile/blob/main/adiq-3ds-package-1.0.0-hml.xcframework.zip

Download link for the SDK iOS Adiq Production file “adiq-3ds-package-1.0.0.xcframework”: https://github.com/adiqpagamentos/SDK_3DS2.0_iOS_Mobile/blob/main/adiq-3ds-1.0.0.xcframework.zip

In order to use the files, it is necessary to download them and replace the files with the latest ones each time the code is updated.

NOTE: It is highly not recommended to use the SDK downloaded from other unofficial sources.

Procedures

Implementation of the 3DS 2.0 Protocol

The implementation of the 3DS 2.0 protocol consists of linking a call to the Adiq iOS SDK to the button that executes a purchase. This button will presumably be in a view of the ecommerce iOS application, specifically in the view where the end customer makes the purchase after inserting their credit/debit card.

Requirement

• iOS 9 and XCode 8 or above

Process Checkpoints

• Reference the SDK iOS from Adiq;
• Create and Update Front-End Codes;
• Update Back-End code;

Step 1 - Reference the SDK iOS adiq-3ds-package-1.0.0-hml.xcframework.

Stage 2 - Mobile Development

The SDK has a single class for use, Authorization3ds, which has 2 asynchronous and public methods:

• getThreeDsCode(request: ExecuteThreeDsRequestDto, timeoutToCodeThreeDsInSeconds: Int = 10) -> String
• initChallenge(pareq: String, transactionId: String, timeoutToChallengeInMinutes: Int = 5) -> ChallengeResponseDto

The getThreeDsCode() method is responsible for collecting the data from the mobile device that will later be used to analyze the transaction, and from the card data and the merchant reference code, it returns the “code3ds”, which must be sent to the “v1/payments” Gateway API. Afterwards, check whether the response from “v1/payments” returned the “threeDs” property. If it returns the status “challenge”, then it must submit the challenge to the client by calling the Adiq SDK's initChallenge() method. This method receives the “pareq” and “authenticationTransactionId” properties returned from “v1/payments” as parameters. If the challenge is answered correctly, the “initChallenge” method will return a token named “serverJwt”.

The “serverJwt” must be sent to the Gateway API “v1/payments/validate” to process the payment. At the end of the transaction, the cleanup() method of the Adiq SDK must be executed to undo the current instance of the 3DS service.

For more information on how to consume the Gateway APIs, visit the developers' documentation (https://developers.adiq.io/manual/ecommerce).

Required fields and validations in the e-commerce gateway

3DS Data

All the above fields are in the Body.

Buyer Data

All the above fields are in the Body.

All the above fields are in the Body.

                
                
{
    "Payment":
    { 
        "TransactionType": "debit", 
        "Amount":1111, 
        "CurrencyCode": "brl", 
        "ProductType": "debito", 
        "Installments": 1, 
        "CaptureType": "ac", 
        "Recurrent":false 
    }, 
    "CardInfo":
    { 
        "NumberToken":"d56109ce-6a3b-4190-beea-1c975e8cd486", 
         "CardholderName":"Luiz Silveira Neto", 
         "SecurityCode":"123", 
         "Brand": "mastercard", 
         "ExpirationMonth":"01", 
         "ExpirationYear":"29" 
    }, 
    "SellerInfo":
    { 
         "OrderNumber":"1110197548565", 
         "SoftDescriptor":"PAG*TESTE", 
         "UrlSite3DS":"empresa.ecommerce.com.br", 
         "Code3DS":"aa415dc21f4e4e7ca083a1473d5c4c58",
         "ThreeDsDataOnly":"false"
    }, 
    "Customer":
    { 
       "DocumentType": "cpf", 
       "DocumentNumber":"51115672088", 
        "FirstName":"Luiz", 
       "LastName":"Silveira Neto", 
       "Email":"luiz.silveira@teste.rafael.com", 
       "PhoneNumber":"1122542454", 
       "MobilePhoneNumber":"11987683332", 
       "Address":"Rua Luiz Vieira, 134", 
       "Complement":"apto. 34 - Vila Guarani", 
       "City":"São Paulo", 
       "State":"SP", 
       "ZipCode":"09876-098", 
       "IpAddress":"45.233.232.248", 
       "Country":"BR" 
    }, 
    "Sellers":[ 
    ], 
    "DeviceInfo":
    {        
       "DeviceChannel":"SDK"
    }
}
                			
            
        

                
                
{
   "paymentAuthorization":{
      "returnCode":"0",      
      "description":"Sucesso",
      "paymentId":"02008028610304095215000006201850000000",
      "authorizationCode":"043711",
      "orderNumber":"0000000001",
      "expireAt":"2019-09-24T13:20:52.8775511-03:00",
      "amount": 1035,
      "releaseAt": "2019-09-24T13:20:52.8775511-03:00"
   },
   "threeDs":{
      "status":"Silent",
      "eci":"02",
      "threeDsVersion":"2.1.0",
      "veresEnrolled":"Y",
      "paresStatus":"Y",
      "threeDsStatus":"AUTHENTICATION_SUCCESSFUL"
   }
}
                			
            
        

All the above Properties are in the Body.

Payment Validation with 3DS Challenge

In order to validate a transaction with 3DS Challenge, you need to send a request using the POST method to the “Validate” resource, as shown in the example:

Request

                
                
 { 
        "code3ds": "dbe5a61a-836d-45dd-82c1-52d0c5e3c010", 
         "validateToken": 
            "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1ZWNkNzVkNjNlMzFiYzQ3MWExZWM2MWYiLCJpYXQi
             OjE1OTQyMzI4MTcsImV4cCI6MTU5NDI0MDAxNywianRpIjoiYjFmNjEyZWEtMDRhZS00ZDY2LW
             EzM2QtY2I1MjgwOGY4M2FlIiwiQ29uc3VtZXJTZXNzaW9uSWQiOiIwX2E3MGIzMjk0LTI1MTIt
             NDc0ZS05OTcxLTZmZTk3YTllYWYzNiIsIlJlZmVyZW5jZUlkIjoiN2Y0ODc3YmVkODVhNDU2Mm
             IxYjNlZjk4MWQ2MjViY2UiLCJhdWQiOiIwMzc2NTk3ODgyMTU0NWRiOTBjN2Y1YmE1ZDNmNWU1
             NiIsIlBheWxvYWQiOiJ7XCJQYXltZW50XCI6e1wiVHlwZVwiOlwiQ0NBXCIsXCJQcm9jZXNzb3
             JUcmFuc2FjdGlvbklkXCI6XCJHc2pMM1lkczVmWk80MzBXYk1RMFwiLFwiRXh0ZW5kZWREYXRh
             XCI6e1wiQW1vdW50XCI6XCIxMTExXCIsXCJDdXJyZW5jeUNvZGVcIjpcIjk4NlwifX0sXCJFcn
             Jvck51bWJlclwiOjAsXCJFcnJvckRlc2NyaXB0aW9uXCI6XCJTdWNjZXNzXCJ9In0.9oBbxbtu
             hZyZaE_vuu6UzU-Mp5BjK2FNp5XAfoDy2uQ"         
}
                	
            
        

                
                
 { 
   "paymentAuthorization":{ 
      "returnCode":"0", 
      "description":"Sucesso", 
      "paymentId":"020006204409231653310000023790740000000000", 
      "authorizationCode":"026603", 
      "orderNumber":"3979908797721", 
      "amount":1111, 
      "releaseAt":"2020-09-23T16:53:34+00:00" 
    },
    "threeDs":{
      "status":"Challenge",
      "eci":"02",
      "threeDsVersion":"2.2.0",
      "paresStatus":"Y",
      "threeDsStatus":"AUTHENTICATION_SUCCESSFUL"
    }
} 
                	
            
        

                
                
 { 
    "FailureDetails":[ 
        { 
            "tag": "string",
            "description": "reason for failure" 
        }
    ]
} 
                	
            
        

All the above Properties are in the Body.

Domains

CyberSource Answer Domains

• consumerAuthenticationInformation.veresEnrolled
  • Y – Yes, bank has 3DS security protocol and will return AscUrl
  • N – No, bank does not have 3DS security protocol
  • U – Unavailable, 3DS or ACS unavailable for authentication at the time of the request.
  • B - Bypass, The merchant authentication rule is triggered to bypass authentication in this use case
• consumerAuthenticationInformation.paresStatus
  • Y – Authentication successful
  • N – Authentication failed / Account not verified / Transaction denied
  • U - Authentication could not be completed
  • A – Transaction attempted successfully
  • R – Authentication rejected
  • D – Challenge required, decoupled authentication confirmed
  • I – Informational only
• consumerAuthenticationInformation.eciRaw
• 02 or 05 – Success
• 01 or 06 – Attempt
• 00 or 07 – Transaction without 3DS
• consumerAuthenticationInformation.cardholderMessage
• Text message provided by the ACS/Issuer to the bearer during a Frictionless authentication process.
• status
  • AUTHENTICATION_SUCCESSFUL
  • PENDING_AUTHENTICATION
  • INVALID_REQUEST
  • AUTHENTICATION_FAILED
• errorInformation.reason
  • INVALID_MERCHANT_CONFIGURATION
  • CONSUMER_AUTHENTICATION_REQUIRED
  • CONSUMER_AUTHENTICATION_FAILED
  • AUTHENTICATION_FAILED

Test Cards 3DS 2.0

Test cards with challenge

Test cards without challenge

External 3DS

External 3DS is the service in which the Customer uses transaction authentication outside Adiq and sends us the data resulting from this authentication in the transaction according to the fields described in the documentation. Adiq's responsibility when using External 3DS is to ensure that the data received is sent in the transaction, and it is not responsible for validating, correcting, altering or storing any of this data. There is no cost to Adiq for using External 3DS.

What are the requirements to use External 3DS?

1. Have enabled External 3DS in Adiq.
2. Completed External 3DS homologation in Adiq.
3. Submit the required fields as specified.
4. For debit transactions, the authentication of 3DS 2.0 Adiq or External 3DS is mandatory, except for exceptions where the shopkeeper has permission to carry out debit transactions without authentication.

Note:

ECIs Table

Files Dictionary

Files that are used in this process

index.js: Payment page file (Front-End).

_Layout.cshtml: Where the jQuery script is placed. If the user of this documentation uses React, it will be necessary to put in the file where the jQuery script is placed.

Note: DTO files exchange information from the front-end to the back-end

Nomenclature Dictionary

Nomenclatures that are used in this process

ccnum: Card number.

validateChallengeCallback: Method that receives a response from the Challenge. The parameters of this method are two strings

• the first parameter being ValidateToken which must be submitted to v1/payments/validate
• the second parameter is the status of the challenge [Approved/Cancelled]
  • If Canceled, the process must be stopped because the challenge process has been canceled.

treatEnrollmentResponse: Method that will receive the payment response (in index.js - frontend).

CallPayment: Call for Payment.