Overview

What is 3DS 2.0 ?

3DS 2.0 is an authentication protocol for payment of online transactions that has 3 levels of validation (3D): trade, brand and issuer.

It is the most current version of the 3-Domain Secure (3DS) authentication protocol, designed to authenticate e-commerce transactions with credit, debit or prepaid cards. It adds a layer of protection by requiring cardholder authentication through unique codes per transaction (such as tokens via SMS or available through the issuing bank's app), PINs, or other validation methods (such as a direct action through the app via a push). Its security protocol is used by the main card brands around the world.

In its version 2.0, the 3DS protocol brings a significant update compared to the original 3Ds version, with improvements mainly in security and user experience.

Carat offers support for 3D-Secure 2.0 transactions through two different integrations:

• 3DS Server
• Web Checkout

Some of the key improvements in 3DS 2.0 include:

• Risk-based authentication: 3DS 2.0 utilizes additional information, such as the buyer's transaction history and device information, to assess fraud risk in real-time. This enables the card issuer to evaluate risk more accurately and determine whether additional validation is necessary.
• Streamlined user experience: 3DS 2.0 offers a simplified and less intrusive authentication flow for the buyer, with fewer redirects to other pages or the need to enter passwords.
• Mobile device support: 3DS 2.0 is designed to work seamlessly on mobile devices, with features like biometric authentication that make the authentication process easier and more convenient for the buyer.

In summary, 3DS 2.0 is a significant upgrade to the 3-Domain Secure authentication protocol, making e-commerce transactions more secure and convenient for buyers.

Benefits for the consumer

• Greater acceptance of debit cards: allows the use of the card in the debit function when purchasing online.
• More security: as safe as in-person purchases with a chip/password or by contact.
• Fraud reduction: the system performs authentication to confirm that the buyer is truly legitimate, preventing card scams.

Benefits for the online retailer

• International safety standard.
• Possibility of expanding sales with debit card transactions and, in normal scenarios, greater conversion compared to the traditional process (CNP).
• Authenticated transactions prevent fraud chargebacks. The issuing bank now guarantees the transaction, as upon successful authentication there is a change of responsibility (“Liability Shift”). If the transaction is authenticated, responsibility passes from the Merchant to the Issuing Bank.
• Reduction of fraud and greater security, both on debit cards and credit cards.
• Broad integration for a better authentication experience during the purchase process.

How does 3DS 2.0 work?

During the payment process, if the buyer's card BIN is enabled in the respective brand's 3D-Secure,
when entering the card details on the payment screen, the 3DS 2.0 APIs enable the collection of purchase
information and send the data to the Issuing Bank. This one, using the data provided, will decide whether the cardholder's identity should be verified
or not. If the data is sufficient, buyer authentication will be carried out without interaction on your part.
This is then called silentor frictionless authentication. Some of the major improvements in 3DS 2.0 include:

If, during authentication, the data is not sufficient to validate the cardholder, an additional process
(known as “step up”) requested by the issuing bank may be necessary, with the aim of verifying the identity of that cardholder.
This authentication process in which an interaction is required from the cardholder is called challenge.
In this additional step, various methods can be included, such as security code verification,
biometric authentication, token validation, approvals on the buyer's mobile device or others.

That's why, it is important to emphasize that the more data the merchant can send about the transaction
and the customer, the greater the chances of obtaining silent authentication.

What are the advantages of 3DS 2.0?

The main advantage is the Liability Shift of fraudulent chargebacks. If the transaction is authenticated, the liability shifts from the Merchant to the Issuing Bank. In other words, for authenticated transactions, the Merchant does not receive chargebacks due to fraud, thus mitigating financial losses. Additionally, there are several other benefits, such as:

• Broad support for devices and authentications
• Streamlined checkout flow
• Smarter decision-making based on risk analysis
• Higher authorization rates and fewer false positives

Authentication vs Authorization

During a payment with authentication, one might have the impression that the authorization and authentication processes are the same. However, a successful authentication does not guarantee payment authorization as these are distinct features:

• Authentication: process to ensure that the cardholder is the legitimate owner of the card.
• Authorization: process used by an Issuer to approve or decline a Purchase Transaction from a Merchant/Acquirer.

While Authentication is the process that validates the user's identity, Authorization is the process that verifies whether the presented card can be used for the purchase after the authentication is validated. It is important to be aware that these features occur in the same flow but can have different outcomes, which will reflect in the final response.

Applicability

The 3DS 2.0 protocol is valid for all online transactions with cards, both debit and credit, and for debit cards, the use of 3DS is mandatory (except for businesses registered in the “debit without password” program). in the Abecs model), and for credit cards, the use of the 3DS is optional.

The main acquirers in Brazil are available for the Fiserv Gateway, as well as the most important brands.

How to activate

The merchant must contact Fiserv's commercial representative and request the inclusion of the 3DS 2.0 service in the Carat contract.
After requesting and contracting the service, with the assistance of the implementation team, the retailer must access the Carat online documentation in the 3DS Overview section and begin the technical integration in your site.

To configure the environment, the merchant needs to provide the following information:

• Merchant ID of the acquirer: unique identification code generated by the acquirer for the merchant
• MCC (Merchant Category Code): standard code that identifies the merchant’s field of activity

If you are not a Fiserv (BIN) purchaser, also inform:

• Acquire Bin.

Acceptance

Check below is the acceptance of issuers regarding 3DS.

Important: Authentication Results.

This guide shows the process of a frictionless authentication, using the Software Express 3DS Server REST interface.

What you'll need

• Active account on 3DS Server's homologation environment (obtained with our support team)
• A tool capable of performing HTTP calls, such as Postman, REST Client or cURL

Creating the transaction

HTTP method: POST

URL: https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication

Headers:

• Content-Type: application/json
• merchant_id: {your merchant id}
• merchant_key: {your merchant key}

Request:

{
   "cardholder":{
      "acct":{
         "number":"1234123412341234"
      }
   },
   "brand_id":"2"
}

curl
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "cardholder":{
      "acct":{
         "number":"1234123412341234"
      }
   },
   "brand_id":"2"
}
--verbose

Response:

{
    "three_ds_method_url": "https://www.example.com",
    "three_ds_server": {
        "trans_id": "12341234-1234-1234-1234-123412341234",
        "status": "NEW"
    },
    "acs": {
        "protocol_version": {
            "start": "2.1.0",
            "end": "2.2.0"
        }
    },
    "device_channel": "02",
    "ds": {
        "protocol_version": {
            "start": "2.1.0",
            "end": "2.2.0"
        }
    },
    "message_version": "2.2.0"
}

Learn more about this service.

Performing the authentication

HTTP Method: PUT

URL: https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/**{3DS Server transaction ID}**

Headers:

• Content-Type: application/json
• merchant_id: {your merchant id}
• merchant_key: {your merchant key}

Request:

{
   "three_ds_comp_ind":"Y",
   "pay_token_ind":"false",
   "notification_url":"https://www.requestor.com/notification",
   "decoupled_notification_url":"https://www.requestor.com/decoupled_notification",
   "trans_type":"01",
   "three_ds_requestor":{
      "authentication_ind":"01",
      "decoupled_max_time":"10",
      "id":"id",
      "name":"Loja de Testes",
      "url":"https://www.requestor.com"
   },
   "acquirer":{
      "bin":"2",
      "merchant_id":"00000000"
   },
   "browser":{
      "accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "ip":"10.20.30.40",
      "javascript_enabled":"true",
      "java_enabled":"false",
      "language":"pt-BR",
      "color_depth":"24",
      "screen_height":"864",
      "screen_width":"1536",
      "tz":"180",
      "user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
   },
   "cardholder":{
      "card_expiry_date":"2212",
      "name":"Joaquim",
      "acct":{
         "type":"02",
         "number":"1234123412341234"
      }
   },
   "merchant":{
      "mcc":"1234",
      "country_code":"BRA",
      "name":"Loja de Teste",
   },
   "message":{
      "category":"01"
   },
   "purchase":{
      "amount":"10000",
      "currency":"986",
      "exponent":"2",
      "date":"date"
   }
}

curl
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/12341234-1234-1234-1234-123412341234"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "three_ds_comp_ind":"Y",
   "pay_token_ind":"false",
   "notification_url":"https://www.requestor.com/notification",
   "decoupled_notification_url":"https://www.requestor.com/decoupled_notification",
   "trans_type":"01",
   "three_ds_requestor":{
      "authentication_ind":"01",
      "decoupled_max_time":"10",
      "id":"id",
      "name":"Loja de Testes",
      "url":"https://www.requestor.com"
   },
   "acquirer":{
      "bin":"2",
      "merchant_id":"00000000"
   },
   "browser":{
      "accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "ip":"10.20.30.40",
      "javascript_enabled":"true",
      "java_enabled":"false",
      "language":"pt-BR",
      "color_depth":"24",
      "screen_height":"864",
      "screen_width":"1536",
      "tz":"180",
      "user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
   },
   "cardholder":{
      "card_expiry_date":"2212",
      "name":"Joaquim",
      "acct":{
         "type":"02",
         "number":"1234123412341234"
      }
   },
   "merchant":{
      "mcc":"1234",
      "country_code":"BRA",
      "name":"Loja de Teste",
   },
   "message":{
      "category":"01"
   },
   "purchase":{
      "amount":"10000",
      "currency":"986",
      "exponent":"2",
      "date":"date"
   }
}
--verbose

Response:

{
    "three_ds_server": {
        "trans_id": "12341234-1234-1234-1234-123412341234",
        "status": "AUY"
    },
    "acs": {
        "operator_id": "acsOperatorID",
        "reference_number": "acsReferenceNumber",
        "trans_id": "43214321-4321-4321-4321-432143214321"
    },
    "eci": "05",
    "device_channel": "02",
    "authentication": {
        "value": "1234567890123456789012345678"
    },
    "broad_info": "broadInfo",
    "ds": {
        "reference_number": "dsReferenceNumber",
        "trans_id": "56785678-5678-5678-5678-567856875678"
    },
    "transaction": {
        "status": "Y"
    },
    "message_version": "2.2.0"
}

Learn more about this service.

Transaction Creation Service

import ApiDoc from '../../../../../src/components/api-doc/ApiDoc';

This call is required to obtain the 3DS Method URL corresponding to the card, besides creating a 3DS Server transaction, which will be used in the following steps of the flow.

Important: The value of the message_version field returned in the response must be used in the CREQ step (for challenge transactions).

Call details

• Resource: /v2/authentication
• HTTP Method: POST
• Request format: JSON
• Response format: JSON
• Header parameters:

* Note: For security reasons, for transaction authentication to be performed, it is recommended to inform a value for Authorization field.
If the store has registered its public key through the Carat Portal, this field is mandatory.

Available authorizers

Signature generation

To generate the value to be sent in the Authorization header, it is necessary:

• Generate public and private keys
  • See the Signature authentication page, section Creating private and public keys.
  • Send only the public key to our support team, who will internally associate that key with your store's registration.
• Follow the signature generation instructions described on Signature authentication page, section Signature algorithm, except the subsection Second part (payload), which will be different in this case - see more details below.

Payload

It is possible to generate the signature using 2 different payloads:

• Payload using card number for this functionality must have the following format:

{
  "merchant_id": "XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "cartao": "5555555555555555",
  "timestamp": "1620952402824"
}

• Payload using token for this functionality must have the following format:

{
  "merchant_id":"XXXXX",
  "merchant_key": "XXXXXXXXXXXXXXX",
  "token": "er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467",
  "timestamp": "1620952402824"
}

Payload Base64:

eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M

Payload composition

Examples

Below are some examples of the transaction creation service using the cURL tool.

Request with card number:

To use this example, don't forget to define the variable {{url}} with the value

curl 
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M'
--data-binary
{
   "cardholder":{
      "acct":{
         "number":"1234123412341234"
      }
   },
   "brand_id":"2"
}
--verbose

Response:

{
  "three_ds_method_url": "https://www.example.com",
  "three_ds_server": {
    "trans_id": "12341234-1234-1234-1234-123412341234",
    "status": "NEW"
  },
  "acs": {
    "protocol_version": {
      "start": "2.1.0",
      "end": "2.2.0"
    }
  },
  "device_channel": "02",
  "ds": {
    "protocol_version": {
      "start": "2.1.0",
      "end": "2.2.0"
    }
  },
  "message_version": "2.2.0"
}

Request with token:
To use this example, don't forget to define the variable {{url}} with the value

curl 
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--header "carat_merchant_id: yyyyyyyyyyyyyyy"
--header "carat_merchant_key: zzzzzzzzzzzzzz"
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJtZXJjaGFudF9pZCI6IkRBVEFPTkxZT04iLCJtZXJjaGFudF9rZXkiOiI5QUM0RjVEQTk0NDExODJDMUNEODJEMzlDNDg2ODYzOTNBRkZDNjlGQzRFMDczM0VFNDgyNjRDNjNCODZENUVFIiwiY2FydGFvIjoiNDExMTEyMDAwMDAwMDAwMCIsInRpbWVzdGFtcCI6IjE2MjA5NTEyNDA5NzUifQ.oYlyOKPsJ9aOCrmJcOq024FGnKReevWdSbKXTcopNqp8AT_4dERYD9G4v-h7pq-xbZOGUOO7YpNmGIqmC-oWHLHGdDGenM7bJyuq1QUff3D9WoMNLeBk5wyguVPoaH7QApksWJllp4fUfLz_BDjw5xwc8ksrDQu1M8w-_PP8wWv9f1_A34Lo7dk1FTQwuFNO4ZBfnkTRLfn0_pIypU9h42Sh9Nr4V8_9Xz0TZvbSw5_FNFY_iQAwXs1Ipr0tGHNL1fvKBlgXfB06ouenHIFNhvzdgPjwGZToJo5hG3NSLsRAI-OiXEkK9loPNNNldkSTzbrtYYTD8gDL90dbQe8fIE3fir-48dsGCzyqO7dZigSbSXxRZkHC6ArfIY6MtY9C4pD8Ero4kOXjAMfxfJq7fhsTh7wrnUhkU-hZxl4nGH_0BPWAe7vBqdCw2agOpUzixY1rLtlQlJ41W42rbIL7lSW6zPF1oLtYG73hUjlcmW8aAdoJlQANWK9_dv6gHv0PjV-BS6jZsLT2aL5Mqgi8DCVPg6cRwAfv2DXSizcSX-6a6mpfQ7ZgR0eU0vHgopX_t6jnO3O3v6Lp2vIArrsH8SW0LT1oBDn-9p-SvtMIJQDhejkPuzrVmwNNXMy8Sb6c8LmhfnPhmyeObUbk1I1iCcbIrCdvqteZdrlGMCImo2M'
--data-binary
{
   "cardholder":{
      "acct":{
         "token":"er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
      }
   },
   "brand_id":"2"
}
--verbose

Response:

{
    "three_ds_method_url": "https://www.example.com",
    "three_ds_server": {
        "trans_id": "12341234-1234-1234-1234-123412341234",
        "status": "NEW"
    },
    "acs": {
        "protocol_version": {
            "start": "2.1.0",
            "end": "2.2.0"
        }
    },
    "device_channel": "02",
    "ds": {
        "protocol_version": {
            "start": "2.1.0",
            "end": "2.2.0"
        }
    },
   "message_version": "2.2.0"
}

Request parameters

The table below describes the request parameters of the transaction creation service:

Response parameters

If successful, the HTTP response code will be 201. Any other code must be interpreted as an error. The table below describes the response parameters of the transaction creation service:

Data Only - Mastercard and Visa

"Data Only" is the term used to describe a transaction flow in which a merchant shares only the data of a transaction with the Issuer through the 3DS rail, without presenting a challenge to the cardholder. This can be influenced by the level of challenges requested by an Issuer and has the following characteristics:

• Always frictionless. The Issuer cannot enforce a challenge for the cardholder in a Data Only transaction.
• There is no liability shift, meaning the merchant remains responsible for potential fraud in this case, not the issuer.
• Depending on the risk of the transaction (e.g., isolated lower-value transactions) or for issuers with a low level of frictionless or technical issues in the authentication process, higher approval rates can be achieved. More information aids in decision-making.

For more details on the official documentation, please contact the card networks Mastercard and VISA and enter "visa secure documentation."

Autentication

To use Identity Check Insights you need to send the value 80 in message.category in the authentication operation.

The Identity Check Insights authentication response has the following characteristics:

• three_ds_server.status: AUU
• ECI: 04
• transaction.status: U
• transaction.status_reason: 80

Success example

Request:

To use this example, don't forget to define the variable {{url}} with the value

curl 
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/12341234-1234-1234-1234-123412341234"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "three_ds_comp_ind":"Y",
   "pay_token_ind":"false",
   "notification_url":"https://www.requestor.com/notification",
   "decoupled_notification_url":"https://www.requestor.com/decoupled_notification",
   "trans_type":"01",
   "three_ds_requestor":{
      "authentication_ind":"01",
      "decoupled_max_time":"10",
      "id":"id",
      "name":"Loja de Testes",
      "url":"https://www.requestor.com"
   },
   "acquirer":{
      "bin":"2",
      "merchant_id":"00000000"
   },
   "browser":{
      "accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "ip":"10.20.30.40",
      "javascript_enabled":"true",
      "java_enabled":"false",
      "language":"pt-BR",
      "color_depth":"24",
      "screen_height":"864",
      "screen_width":"1536",
      "tz":"180",
      "user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
   },
   "cardholder":{
      "card_expiry_date":"2212",
      "name":"Joaquim",
      "acct":{
         "type":"02",
         "number":"1234123412341234"
      }
   },
   "merchant":{
      "mcc":"mcc",
      "country_code":"BRA",
      "name":"Loja de Teste",
   },
   "message":{
      "category":"80"
   },
   "purchase":{
      "amount":"10000",
      "currency":"986",
      "exponent":"2",
      "date":"date"
   }
}
--verbose

Response:

{
   "three_ds_server":{
      "trans_id":"12341234-1234-1234-1234-123412341234",
      "status":"AUU"
   },
   "acs":{
      "operator_id":"acsOperatorID",
      "reference_number":"acsReferenceNumber",
      "trans_id":"43214321-4321-4321-4321-432143214321"
   },
   "eci":"04",
   "device_channel":"02",
   "broad_info":"broadInfo",
   "ds":{
      "reference_number":"dsReferenceNumber",
      "trans_id":"56785678-5678-5678-5678-567856875678"
   },
   "transaction":{
      "status":"U",
      "status_reason":"80"
   }
}

Authentication Failure

If there is any failure in the Identity Check Insights authentication operation, the response must have the following characteristics:

• ECI will not be returned
• A response message will be returned containing a MAIQ response name extension in the message.extension object

More details in the official documentation.

Example

Response

{
  "three_ds_server" : {
    "trans_id" : "71b92918-967e-499f-9371-eec6f4736739",
    "status" : "AUU"
  },
  "acs" : {
    "operator_id" : "acsOperatorID",
    "reference_number" : "acsReferenceNumber",
    "trans_id" : "61491484-029e-48d1-96ec-9cb57a0ec136"
  },
  "device_channel" : "02",
  "broad_info" : "broadInfo",
  "ds" : {
    "reference_number" : "dsReferenceNumber",
    "trans_id" : "550be910-99c9-4676-9fed-2fd33d057727"
  },
  "message" : {
    "extension" : [ {
      "criticality_indicator" : "false",
      "data" : "{\"A000000004-maiqRes\": {\"status\": \"fail\"}}",
      "id" : "A000000004-maiqRes",
      "name" : "MAIQ response"
    } ]
  },
  "transaction" : {
    "status" : "U",
    "status_reason" : "80"
  }
}

Decoupled Notification

During the decoupled authentication process, 3DS Server will send a notification to the 3DS Requestor informing the authentication result. This notification is performed with an HTTP POST on the URL informed on the authentication service (decoupled_notification_url field), in the application/x-www-form-urlencoded format. The 3DS Requestor mut respond to this call with HTTP code 200.

Below are the parameters of this notification:

Transaction Query Service

import ApiDoc from '../../../../../src/components/api-doc/ApiDoc';

This call allows 3DS Requestor to query the status of a transaction. This operation must be used by 3DS Requestor in case of problems receiving the CRes. We will return status, ECI and CAVV, which are necessary to proceed with an authorization.

Call details

• Recurso: /v2/transaction/{3DS Server Transaction Id}
• HTTP Method: GET
• HTTP Response OK: 200
• Request format: there are no request parameters
• Response format: JSON
• Header parameters:

Examples

Below is an example of the transaction query service call using the cURL tool.

Request:
To use this example, don't forget to define the variable {{url}} with the value

curl 
--request GET "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/transaction/123456789-aaaa-bbbb-cccc-ddddddddddd"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--verbose

Response:

{
    "three_ds_server": {
        "trans_id": "12345678-1234-1234-1234-123456789012",
        "status": "AUY"
    },
    "brand_id": "2",
    "eci": "05",
    "device_channel": "02",
    "authentication": {
        "value": "1234567890123456789012345678"
    },
     "message_version": "2.2.0"
}

Examples with challenge cancel

Below is an example of the transaction query service call using challenge cancel in response

Requisição:

curl
--request GET "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/transaction/123456789-aaaa-bbbb-cccc-ddddddddddd"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--verbose

Resposta:

{
    "three_ds_server": {
        "trans_id": "12345678-1234-1234-1234-123456789012",
        "status": "AUY"
    },
    "brand_id": "2",
    "challenge_cancel": "01",
    "eci": "05",
    "device_channel": "02",
    "authentication": {
        "value": "1234567890123456789012345678"
    }, 
     "message_version": "2.2.0"
}

Response parameters

If successful, the HTTP response code will be 200. Any other code must be interpreted as an error. The table below describes the response parameters of the transaction query service:

Authentication Result

Authentication in the context of 3D-Secure has several possible outcomes, depending on the authentication protocol used and the
card issuer requirements. Here are some of the key results of an authentication:

• Authentication Passed: Transaction authentication is successful
  either automatically (frictionless) or by flag, using a similar process
  to ‘stand-in’, known as attempt.
• Authentication Denied: Authentication fails, and is denied. This may occur if the cardholder
  entering incorrect information if additional authentication is not completed correctly
  or if there is a problem connecting to the authentication server. In this case,
  Anti fraud settings can be made to complement the analyzes and
  allow other ways of validating these challenges.
• Challenged Authentication: In some cases, authentication may be
  challenged, which means you need to provide additional information or go through
  an additional authentication step to confirm the legitimacy of the transaction. This may involve
  the use of passwords, PINs, security codes sent via SMS or other authentication methods.
• Authentication rejected by the Issuer: In this case, the issuer, by having specific rules for
  validate authentication, you can reject the authentication for reasons ranging from card status or
  specific validations per client. Each issuer may have specific rules for these validations.

It is important to note that the results of an authentication may vary depending on the rules and
policies established by the card issuer, as well as the specific implementation of 3D-Secure by the merchant and the card brand.
Remembering that after the authentication process, we still have every step related to authorization of the transaction,
which would be the approval, or not, of the transaction, according to the rules of each issuer.

ECI Table

The ECI (Electronic Commerce Indicator) is a code returned by card networks and indicates the result of the cardholder's 3DS authentication with the issuer or card network. Check the following table for the corresponding ECIs for each card network and the authentication result.

Initiating a 3DS Method

The "3DS Method" is a script call, only present in the Browser channel, provided by the 3DS Server and placed on the merchant's website to capture additional browser information, aiming to facilitate risk-based decision-making (RBA-Risk Based Analysis), increasing the chances of obtaining a challenge-free authentication.

Upon transaction creation, the 3DS Server returns the URL of the "3DS Method" in the three_ds_method_url field if device fingerprint capture is enabled for the card's BIN used. This indicates that an invisible frame should be rendered on the buyer's screen pointing to this URL. To achieve this, an HTTP POST in the application/x-www-form-urlencoded format is required, passing the threeDSMethodData field, which is a Base64-encoded JSON.

The return from the "3DS Method" call may take a few seconds. Therefore, for a better user experience, it is recommended to make this call soon after entering the card number. This way, while the user fills in the other checkout details, the "3DS Method" call will have already finished.

When the "3DS Method" call is successfully completed, the authentication request (AREQ) should be sent with the three_ds_comp_ind field set to "Y".

threeDSMethodData object parameters

Examples

threeDSMethodData JSON:

{
   "threeDSServerTransID":"12341234-1234-1234-1234-123412341234",
   "threeDSMethodNotificationURL":"threeDSMethodNotificationURL"
}

threeDSMethodData Base64:

ewogICAidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxMjM0MTIzNC0xMjM0LTEyMzQtMTIzNC0xMjM0MTIzNDEyMzQiLAogICAidGhyZWVEU01ldGhvZE5vdGlmaWNhdGlvblVSTCI6InRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiCn0=

HTML form:

<form name="frm" method="POST" action="Rendering URL">
    <input type="hidden" name="threeDSMethodData" value="ewogICAidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxMjM0MTIzNC0xMjM0LTEyMzQtMTIzNC0xMjM0MTIzNDEyMzQiLAogICAidGhyZWVEU01ldGhvZE5vdGlmaWNhdGlvblVSTCI6InRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiCn0=">
</form>
<iframe name="threeDsMethodFrame" height="1px" width="1px" frameborder="0"></iframe>
<script>
		console.log('3DS Method');
		document.forms.threeDsMethodForm.submit();
</script>

3DS Method notification

This call will be performed by the ACS on the URL informed by the 3DS Requestor (threeDSMethodNotificationURL field) using the same format of the form described above. This call is important for sending the three_ds_comp_ind field on the authentication service.

Authentication Service

import ApiDoc from '../../../../../src/components/api-doc/ApiDoc';

After creating the transaction, it's necessary to call the authentication service to continue the flow. If the AUC status is returned, a challenge must be initiated. For the AUD status, the "decoupled" flow must be followed. Otherwise, further calls won't be required.

Call details

• Resource: /v2/authentication/{3DS Server Transaction ID}
• HTTP Method: PUT
• Request format: JSON
• Response format: JSON
• Header parameters:

Example

Below are some examples of the authentication service call using the cURL tool.

Frictionless Flow

Request with card number:
To use this example, don't forget to define the variable {{url}} with the value

curl 
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/12341234-1234-1234-1234-123412341234"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "three_ds_comp_ind":"Y",
   "pay_token_ind":"false",
   "notification_url":"https://www.requestor.com/notification",
   "trans_type":"01",
   "three_ds_requestor":{
      "authentication_ind":"01",
      "id":"id",
      "name":"Loja de Testes",
      "url":"https://www.requestor.com"
   },
   "acquirer":{
      "bin":"2",
      "merchant_id":"00000000"
   },
   "browser":{
      "accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "ip":"10.20.30.40",
      "javascript_enabled":"true",
      "java_enabled":"false",
      "language":"pt-BR",
      "color_depth":"24",
      "screen_height":"864",
      "screen_width":"1536",
      "tz":"180",
      "user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
   },
   "cardholder":{
      "card_expiry_date":"2212",
      "name":"Joaquim",
      "acct":{
         "type":"02",
         "number":"1234123412341234"
      }
   },
   "merchant":{
      "mcc":"1234",
      "country_code":"BRA",
      "name":"Loja de Teste",
   },
   "message":{
      "category":"01"
   },
   "purchase":{
      "amount":"10000",
      "currency":"986",
      "exponent":"2",
      "date":"date"
   }
}
--verbose

Response:

{
  "three_ds_server": {
    "trans_id": "12341234-1234-1234-1234-123412341234",
    "status": "AUY"
  },
  "acs": {
    "operator_id": "acsOperatorID",
    "reference_number": "acsReferenceNumber",
    "trans_id": "43214321-4321-4321-4321-432143214321"
  },
  "eci": "05",
  "device_channel": "02",
  "authentication": {
    "value": "1234567890123456789012345678"
  },
  "broad_info": "broadInfo",
  "ds": {
    "reference_number": "dsReferenceNumber",
    "trans_id": "56785678-5678-5678-5678-567856875678"
  },
  "transaction": {
    "status": "Y"
  },
  "message_version": "2.2.0"
}

Request with token:
To use this example, don't forget to define the variable {{url}} with the value

curl 
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/12341234-1234-1234-1234-123412341234"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "three_ds_comp_ind":"Y",
   "pay_token_ind":"false",
   "notification_url":"https://www.requestor.com/notification",
   "trans_type":"01",
   "three_ds_requestor":{
      "authentication_ind":"01",
      "id":"id",
      "name":"Loja de Testes",
      "url":"https://www.requestor.com"
   },
   "acquirer":{
      "bin":"2",
      "merchant_id":"00000000"
   },
   "browser":{
      "accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "ip":"10.20.30.40",
      "javascript_enabled":"true",
      "java_enabled":"false",
      "language":"pt-BR",
      "color_depth":"24",
      "screen_height":"864",
      "screen_width":"1536",
      "tz":"180",
      "user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
   },
   "cardholder":{
      "card_expiry_date":"2212",
      "name":"Joaquim",
      "acct":{
         "type":"02",
         "token":"er334gvdgdf5dfgdfg63456363434tre345353rg34tb4576jfgrtu464jj56j56u56u56ghhrthrhrthrth467"
      }
   },
   "merchant":{
      "mcc":"1234",
      "country_code":"BRA",
      "name":"Loja de Teste",
   },
   "message":{
      "category":"01"
   },
   "purchase":{
      "amount":"10000",
      "currency":"986",
      "exponent":"2",
      "date":"date"
   }
}
--verbose

Response:

{
  "three_ds_server": {
    "trans_id": "12341234-1234-1234-1234-123412341234",
    "status": "AUY"
  },
  "acs": {
    "operator_id": "acsOperatorID",
    "reference_number": "acsReferenceNumber",
    "trans_id": "43214321-4321-4321-4321-432143214321"
  },
  "eci": "05",
  "device_channel": "02",
  "authentication": {
    "value": "1234567890123456789012345678"
  },
  "broad_info": "broadInfo",
  "ds": {
    "reference_number": "dsReferenceNumber",
    "trans_id": "56785678-5678-5678-5678-567856875678"
  },
  "transaction": {
    "status": "Y"
  },
  "message_version": "2.2.0"
}

Challenge Flow

Request:
To use this example, don't forget to define the variable {{url}} with the value

curl 
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/12341234-1234-1234-1234-123412341234"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "three_ds_comp_ind":"Y",
   "pay_token_ind":"false",
   "notification_url":"https://www.requestor.com/notification",
   "trans_type":"01",
   "three_ds_requestor":{
      "authentication_ind":"01",
      "id":"id",
      "name":"Loja de Testes",
      "url":"https://www.requestor.com"
   },
   "acquirer":{
      "bin":"2",
      "merchant_id":"00000000"
   },
   "browser":{
      "accept_header":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8",
      "ip":"10.20.30.40",
      "javascript_enabled":"true",
      "java_enabled":"false",
      "language":"pt-BR",
      "color_depth":"24",
      "screen_height":"864",
      "screen_width":"1536",
      "tz":"180",
      "user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:75.0) Gecko/20100101 Firefox/75.0"
   },
   "cardholder":{
      "card_expiry_date":"2212",
      "name":"Joaquim",
      "acct":{
         "type":"02",
         "number":"1234123412341234"
      }
   },
   "merchant":{
      "mcc":"1234",
      "country_code":"BRA",
      "name":"Loja de Teste",
   },
   "message":{
      "category":"01"
   },
   "purchase":{
      "amount":"10004",
      "currency":"986",
      "exponent":"2",
      "date":"date"
   }
}
--verbose

Response:

{
  "three_ds_server": {
    "trans_id": "12341234-1234-1234-1234-123412341234",
    "status": "AUC"
  },
  "acs": {
    "challenge_mandated": "Y",
    "operator_id": "acsOperatorID",
    "reference_number": "acsReferenceNumber",
    "trans_id": "43214321-4321-4321-4321-432143214321",
    "url": "https://www.acs.com/challenge"
  },
  "device_channel": "02",
  "authentication": {
    "type": "01"
  },
  "broad_info": "broadInfo",
  "ds": {
    "reference_number": "dsReferenceNumber",
    "trans_id": "56785678-5678-5678-5678-567856875678"
  },
  "transaction": {
    "status": "C"
  },
  "message_version": "2.2.0"
}

Request parameters

The table below describes the request parameters of the authentication service:

Response parameters

If successful, the HTTP response code will be 200. Any other code must be interpreted as an error. The table below describes the response parameters of the authentication service:

How to Test the 3DS API

This manual has been created to assist you in testing the 3DS API in your development environment. With this manual, you will be able to understand how the API works and how to use it to perform tests on your payment system.

By following the instructions in this manual, you will be able to ensure that your integration with the 3DS API is reliable and secure for your users.

Attention:

The tests will be conducted in a CARAT staging environment, which provides a more controlled and secure environment for conducting the tests.

Table with different cards for testing:

Table with values in cents that can be used to simulate different statuses in 3DS:

Examples

Below, we will provide examples of tests in the Frictionless and Challenge flows, as well as a test with a card number that is not within the range of cards supported for 3DS 2.0 authentication. All tests will be performed using the cURL tool.

Frictionless [Creating the Transaction]

Request Type: POST

URL: https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication

Headers:

• Content-Type: application/json
• merchant_id: {Please request your store code from the support team.}
• merchant_key: {Please request your merchant key from the support team.}

Mastercard Card: 5555555555555555

Request:

curl
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "cardholder":{
      "acct":{
         "number":"5555555555555555"
      }
   },
   "brand_id":"2"
}
--verbose

Response:

{
  "three_ds_method_url": "https://mpi-homolog.softwareexpress.com.br/e-sitef-homologacao/acs/3dsmethod.se",
  "three_ds_server": {
    "trans_id": "fb26dfb6-2486-442a-8887-d1241c940a61",
    "status": "NEW"
  },
  "acs": {
    "protocol_version": {
      "start": "2.1.0",
      "end": "2.2.0"
    }
  },
  "device_channel": "02",
  "ds": {
    "protocol_version": {
      "start": "2.1.0",
      "end": "2.2.0"
    }
  }
}

Learn more about this service.

Frictionless [Performing the authentication.]

Request Type: PUT

URL: https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/fb26dfb6-2486-442a-8887-d1241c940a61

In the above URL, the 3DS Server transaction ID was filled with the value fb26dfb6-2486-442a-8887-d1241c940a61, which was obtained during the transaction creation.

Headers:

• Content-Type: application/json
• merchant_id: {Please request your store code from the support team.}
• merchant_key: {Please request your merchant key from the support team.}

Request:

curl
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/fb26dfb6-2486-442a-8887-d1241c940a61"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
  "three_ds_comp_ind" : "Y",
  "notification_url" : "https://3dsnotification.requestcatcher.com/test?trans_id=fb26dfb6-2486-442a-8887-d1241c940a61",
  "decoupled_notification_url" : "decoupledNotificationURLParaPasso10",
  "trans_type" : "01",
  "three_ds_requestor" : {
    "authentication_ind" : "01",
    "decoupled_max_time" : "10",
    "id" : "2",
    "name" : "e-SiTef",
    "url" : "https://teste.com.br"
  },
  "acquirer" : {
    "bin" : "12343",
    "merchant_id" : "555555"
  },
  "browser" : {
    "accept_header" : "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
    "ip" : "192.168.50.141",
    "javascript_enabled" : true,
    "java_enabled" : "false",
    "language" : "en-US",
     "color_depth" : "30",
    "screen_height" : "1080",
    "screen_width" : "1920",
    "tz" : "180",
    "user_agent" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101 Firefox/102.0"
  },
  "cardholder" : {
    "card_expiry_date" : "2202",
    "email" : "[email protected]",
    "mobile_phone" : {
      "cc" : "55",
      "subscriber" : "11111111111"
    },
    "name" : "Nome do Cartao",
    "acct" : {
      "type" : "02",
      "number":"5555555555555555"
    },
    "bill_addr" : {
      "city" : "Guarulhos",
      "country" : "076",
      "line1" : "rua xxx",
      "line2" : "99",
      "line3" : "complemento",
      "post_code" : "22222-222",
      "state" : "SP"
    },
    "ship_addr" : {
      "city" : "Rio de Janeiro",
      "country" : "076",
      "line1" : "Rua yyy",
      "line2" : "88",
      "line3" : "complemento 2",
      "post_code" : "33333-333",
      "state" : "RJ"
    }
  },
  "merchant" : {
    "mcc" : "0121",
    "country_code" : "076",
    "name" : "Loja de Teste"
  },
  "message" : {
    "category" : "01"
  },
  "purchase" : {
    "amount" : "10000",
    "currency" : "986",
    "exponent" : "2",
    "date" : "20221006163646"
  }
}

Response:

{
  "three_ds_server": {
    "trans_id": "fb26dfb6-2486-442a-8887-d1241c940a61",
    "status": "AUY"
  },
  "acs": {
    "operator_id": "acsOperatorID",
    "reference_number": "acsReferenceNumber",
    "trans_id": "8a1c3ef2-25ff-46e8-ba9e-463f5172dab0"
  },
  "eci": "02",
  "device_channel": "02",
  "authentication": {
    "value": "kFOAbf75KviDMXVzmGEoG3NIjJTF"
  },
  "broad_info": "broadInfo",
  "ds": {
    "reference_number": "dsReferenceNumber",
    "trans_id": "d57be3da-6c42-4dbb-8372-1ff7c840ff6a"
  },
  "transaction": {
    "status": "Y"
  }
}

Learn more about this service.

Card not supported for 3DS 2.0 authentication. [Creating the transaction]

Request Type: POST

URL: https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication

Headers:

• Content-Type: application/json
• merchant_id: {Please request your store code from the support team.}
• merchant_key: {Please request your merchant key from the support team.}

Mastercard Card: 5251743209931344

Request:

curl
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "cardholder":{
      "acct":{
         "number":"5251743209931344"
      }
   },
   "brand_id":"2"
}
--verbose

Response:

{
  "three_ds_server": {
    "trans_id": "9e696005-da29-48f1-a796-5d5f2e2ccf21",
    "status": "INV"
  },
  "device_channel": "02",
  "error": {
    "code": "305",
    "component": "S",
    "description": "Cardholder Account Number is not in a range belonging to Issuer",
    "detail": "acctNumber"
  }
}

Learn more about this service.

Challenge [Creating the transaction.]

Request Type: POST

URL: https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication

Headers:

• Content-Type: application/json
• merchant_id: {Please request your store code from the support team.}
• merchant_key: {Please request your merchant key from the support team.}

Mastercard Card: 5555555555555555

Request:

curl
--request POST "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "cardholder":{
      "acct":{
         "number":"5555555555555555"
      }
   },
   "brand_id":"2"
}
--verbose

Response:

{
  "three_ds_method_url": "https://mpi-homolog.softwareexpress.com.br/e-sitef-homologacao/acs/3dsmethod.se",
  "three_ds_server": {
    "trans_id": "fb26dfb6-2486-442a-8887-d1241c940a61",
    "status": "NEW"
  },
  "acs": {
    "protocol_version": {
      "start": "2.1.0",
      "end": "2.2.0"
    }
  },
  "device_channel": "02",
  "ds": {
    "protocol_version": {
      "start": "2.1.0",
      "end": "2.2.0"
    }
  }
}

Learn more about this service.

Challenge [Performing the authentication.]

Request Type: PUT

URL: https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/fb26dfb6-2486-442a-8887-d1241c940a61

In the above URL, the 3DS Server transaction ID was filled with the value fb26dfb6-2486-442a-8887-d1241c940a61, which was obtained during the transaction creation.

Attention

To simulate the Challenge flow, it is necessary to pass the value 10014 in the purchase.amount field of the transaction, as indicated in the table presented at the beginning of this manual.

Headers:

• Content-Type: application/json
• merchant_id: {Please request your store code from the support team.}
• merchant_key: {Please request your merchant key from the support team.}

Request:

curl
--request PUT "https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/authentication/fb26dfb6-2486-442a-8887-d1241c940a61"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx" 
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
  "three_ds_comp_ind" : "Y",
  "notification_url" : "https://3dsnotification.requestcatcher.com/test?trans_id=fb26dfb6-2486-442a-8887-d1241c940a61",
  "decoupled_notification_url" : "decoupledNotificationURLParaPasso10",
  "trans_type" : "01",
  "three_ds_requestor" : {
    "authentication_ind" : "01",
    "decoupled_max_time" : "10",
    "id" : "2",
    "name" : "e-SiTef",
    "url" : "https://teste.com.br"
  },
  "acquirer" : {
    "bin" : "12343",
    "merchant_id" : "555555"
  },
  "browser" : {
    "accept_header" : "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
    "ip" : "192.168.50.141",
    "javascript_enabled" : true,
    "java_enabled" : "false",
    "language" : "en-US",
     "color_depth" : "30",
    "screen_height" : "1080",
    "screen_width" : "1920",
    "tz" : "180",
    "user_agent" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101 Firefox/102.0"
  },
  "cardholder" : {
    "card_expiry_date" : "2202",
    "email" : "[email protected]",
    "mobile_phone" : {
      "cc" : "55",
      "subscriber" : "11111111111"
    },
    "name" : "Nome do Cartao",
    "acct" : {
      "type" : "02",
      "number":"5555555555555555"
    },
    "bill_addr" : {
      "city" : "Guarulhos",
      "country" : "076",
      "line1" : "rua xxx",
      "line2" : "99",
      "line3" : "complemento",
      "post_code" : "22222-222",
      "state" : "SP"
    },
    "ship_addr" : {
      "city" : "Rio de Janeiro",
      "country" : "076",
      "line1" : "Rua yyy",
      "line2" : "88",
      "line3" : "complemento 2",
      "post_code" : "33333-333",
      "state" : "RJ"
    }
  },
  "merchant" : {
    "mcc" : "0121",
    "country_code" : "076",
    "name" : "Loja de Teste"
  },
  "message" : {
    "category" : "01"
  },
  "purchase" : {
    "amount" : "10014",
    "currency" : "986",
    "exponent" : "2",
    "date" : "20221006163646"
  }
}

Response:

{
  "three_ds_server": {
    "trans_id": "fb26dfb6-2486-442a-8887-d1241c940a61",
    "status": "AUC"
  },
  "acs": {
    "challenge_mandated": "Y",
    "operator_id": "acsOperatorID",
    "reference_number": "acsReferenceNumber",
    "trans_id": "f215fa24-88ff-4045-b8a2-f400a9c421ae",
    "url": "https://mpi-homolog.softwareexpress.com.br/e-sitef-homologacao/acs/challenge.se?brandId=2&sleepTime=120000"
  },
  "device_channel": "02",
  "authentication": {
    "type": "01"
  },
  "broad_info": "broadInfo",
  "ds": {
    "reference_number": "dsReferenceNumber",
    "trans_id": "081ed552-eaed-4548-8680-e89ae6309890"
  },
  "transaction": {
    "status": "C"
  }
}

Challenge

Request Type: POST

URL: https://mpi-homolog.softwareexpress.com.br/e-sitef-homologacao/acs/challenge.se?brandId=2

In the above URL, you need to insert the value of brandId, which in our test is defined as 2, as we are using a Mastercard card.

Headers:

• Content-Type: application/x-www-form-urlencoded

Sending the CReq.

To obtain the challenge, the parameter creq must be sent, which contains the CReq encoded in Base64 URL-safe encoding.

CReq Json

In this JSON, we include the same transaction ID from the 3DS Server three_ds_server.trans_id and the transaction ID from the ACS acs.trans_id, which were obtained in the previous two steps.

{
  "threeDSServerTransID":"fb26dfb6-2486-442a-8887-d1241c940a61",
  "acsTransID":"081ed552-eaed-4548-8680-e89ae6309890",
  "challengeWindowSize":"05",
  "messageType":"CReq",
  "messageVersion":"2.2.0"
}

CReq Base64:

ewogICJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImZiMjZkZmI2LTI0ODYtNDQyYS04ODg3LWQxMjQxYzk0MGE2MSIsCiAgImFjc1RyYW5zSUQiOiIwODFlZDU1Mi1lYWVkLTQ1NDgtODY4MC1lODlhZTYzMDk4OTAiLAogICJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLAogICJtZXNzYWdlVHlwZSI6IkNSZXEiLAogICJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIgp9

Learn more about this service.

After encoding the CReq JSON in Base64, we create the following request.

Request:

curl --location --request POST 'https://mpi-homolog.softwareexpress.com.br/e-sitef-homologacao/acs/challenge.se?brandId=2' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: JSESSIONID=3cfQENgsLzfHjQ2WxBr-M-OfkHbcb6a2hRkw2dZV.ip-10-53-55-113' \
--data-urlencode 'creq=ewogICJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImZiMjZkZmI2LTI0ODYtNDQyYS04ODg3LWQxMjQxYzk0MGE2MSIsCiAgImFjc1RyYW5zSUQiOiIwODFlZDU1Mi1lYWVkLTQ1NDgtODY4MC1lODlhZTYzMDk4OTAiLAogICJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLAogICJtZXNzYWdlVHlwZSI6IkNSZXEiLAogICJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIgp9'

Response:

The response will return a script from our simulator that simulates an ACS (Issuer) challenge. Normally, this script would be added to the application in an iframe, but for testing purposes, let's save it as an HTML file and open it in the browser. After that, select the desired challenge status - let's choose Status Y, indicating success - and click the submit button.

HTML file opened in the browser:

Attention

This is just a CARAT simulator to simulate the challenge.

Script response to simulate the challenge as represented in the image above.:

Attention

This script is returned to the response of the CReq submission.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
</html>

Query the transaction status after the challenge.

Request Type: GET

URL: https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/transaction/fb26dfb6-2486-442a-8887-d1241c940a61

In the URL above, the ID of the 3DS Server transaction was filled with the value fb26dfb6-2486-442a-8887-d1241c940a61, which was obtained during the transaction creation.

Headers:

• Content-Type: application/json
• merchant_id: {Please request your store code from the support team.}
• merchant_key: {Please request your merchant key from the support team.}

Request:

curl --location --request GET 'https://mpi-homolog.softwareexpress.com.br/3ds-server/v2/transaction/fb26dfb6-2486-442a-8887-d1241c940a61' \
--header 'merchant_id: XXXXXXXXX' \
--header 'merchant_key: XXXXXXXX'

Response:

{
    "three_ds_server": {
        "trans_id": "fb26dfb6-2486-442a-8887-d1241c940a61",
        "status": "AUY"
    },
    "brand_id": "2",
    "eci": "02",
    "device_channel": "02",
    "authentication": {
        "value": "kFOAbf75KviDMXVzmGEoG3NIjJTF"
    }
}

E para saber mais sobre essas nomenclaturas (Bin, Software Express, Carat, e-Sitef) Saiba mais

3D Secure Glossary

Brand IDs

3DS Server transaction status

Error codes

device_channel field

Glossary

• 3DS Requestor: Store or gateway (such as Carat)
• 3D-Secure: Also known as Visa Secure, Mastercard Identity Check,
  American Express SafeKey, Discover ProtectCode or Elo SecureCode,
  is a security protocol used by card brands to authenticate online transactions and reduce fraud.
• ACS (Access Control Server): The server responsible for
  provide the authentication interface on behalf of the issuer during the
  3D-Secure transaction process. It interacts with the issuer and cardholder to verify the authenticity of the transaction.
• DS (Directory Server): Represents the flag
• AReq: Authentication Request, according to the 3DS 2.0 protocol
• ARes: Authentication Response, according to the 3DS 2.0 protocol
• CReq: Challenge Request, according to the 3DS 2.0 protocol
• CRes: Challenge Response, according to the 3DS 2.0 protocol
• RReq: Results Request, according to the 3DS 2.0 protocol
• RRes: Results Response, according to the 3DS 2.0 protocol
• Challenge/Step-up Flow: Also known as "challenge flow".
  It is a form of 3D-Secure authentication in which the cardholder is directed to
  a page or application to provide additional information or enter a security code to confirm the transaction.
• Frictionless Flow: Also known as "frictionless flow".
  It is a form of 3D-Secure authentication in which the transaction is automatically authenticated
  based on available data, without the need for intervention by the cardholder.
  This usually occurs when the issuer has sufficient information
  (such as data about the holder or the device used) to confirm the identity of the holder.
• 3DS Server Id: ID that identifies the transaction on the 3DS Server (three_ds_server.trans_id field of the transaction creation or authentication response)
• DS Id: ID that identifies the transaction on the Bandeira server (ds.trans_id field of the transaction authentication response)
• ACS ID: ID that identifies the transaction at the Issuer (acs.trans_id field of the transaction authentication response)
• 3DS Method URL: Issuer URL to send a post to collect information from the buyer's device in web transactions
• reference_id: Field to be used in the Carat payment rest API (the ds.trans_id value of the transaction authentication response must be passed)
• ECI (or “e-commerce indicator”): Code returned to the MPI by the brands, which indicates the result of the bearer’s 3DS authentication with the issuer
• CAVV or IAV: Cryptogram code used in transaction authentication and sent by the establishment's MPI (authentication.value field in the transaction authentication response or in the transaction query).
• Authentication: The process of verifying the identity of the
  cardholder during an online transaction. 3D-Secure requires authentication
  additional information, usually through a security code, PIN or biometrics by the requesting business.
• Issuer: The financial institution (bank or credit card company)
  who issues the credit card, debit card to the holder.
• Commerce/Merchant: A company or website that accepts online payments via credit or debit cards.
• Enrollment: The process of registering a card for use in 3D-Secure. The cardholder normally carries out
  the enrollment process when using the card for the first time on a 3D-Secure compatible website.
• Liability Shift: The transfer of responsibility from the merchant to the issuer occurs in the case of a fraudulent transaction, provided that the transaction has been authenticated by 3D-Secure, and the merchant is enabled on 3DS, allowing them to win the "Reversal of Responsibility.".
• RBA (Risk-Based Analysis): It is an approach within 3D-Secure in which the card issuer assesses the risk of a transaction to determine if additional verification is necessary. Based on factors such as transaction value, device identification, and the cardholder's history, low-risk transactions may be approved without additional validation, while medium or high-risk transactions may require extra steps to ensure security. This enhances the customer experience by reducing friction in low-risk transactions while simultaneously safeguarding against fraudulent transactions.
• MPI (Merchant Plug-In): The software or service used by a merchant to connect to the 3D-Secure authentication system. It facilitates communication between the merchant, the issuer and the card brand.

Carat provides support for 3D-Secure 2.0 transactions through its 3DS Server

And to learn more about these nomenclatures (Bin, Software Express, Carat, e-Sitef) Learn more

Challenge

To initiate a challenge, only redirecting the cardholder to the URL obtained in the acs.url field is not enough; it's necessary to POST the CReq. At the end of the challenges, the 3DS Requestor will receive information (on the URL indicated in the notification_url field) regarding the 3DS transaction in the CRes object.

Sending the CReq

The CReq POSt must be performed with the Content-Type header = application/x-www-form-urlencoded when device_channel = 02 or application/jose when device_channel = 01. In this form, the creq parameter must be sent, which has the Base64 URL-safe encoded CReq as its value.

Examples

CReq JSON:

{
    "threeDSServerTransID":"12341234-1234-1234-1234-123412341234",
    "acsTransID":"43214321-4321-4321-4321-432143214321",
    "challengeWindowSize":"05",
    "messageType":"CReq",
    "messageVersion":"2.2.0"
}

CReq Base64:

ewogICAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiMTIzNDEyMzQtMTIzNC0xMjM0LTEyMzQtMTIzNDEyMzQxMjM0IiwKICAgICJhY3NUcmFuc0lEIjoiNDMyMTQzMjEtNDMyMS00MzIxLTQzMjEtNDMyMTQzMjE0MzIxIiwKICAgICJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLAogICAgIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsCiAgICAibWVzc2FnZVZlcnNpb24iOiIyLjIuMCIKfQ

Challenge redirecting HTML:

<!DOCTYPE html
</html>

CReq parameters

Receiving the CRes

The CRes will be sent in JSON format, Base64 encoded, on the URL informed on the authentication service (notification_url field).

CRes parameters

3DS 2.0 Checkout Transparent JavaScript

Quick Start

This guide shows the JavaScript payment process with 3DS 2.0 authentication using an integrated test web merchant
in the approval environment.

Attention: All procedures demonstrated on this page were carried out in the approval environment only to illustrate the flow of a JavaScript Payment with 3DS 2.0 authentication. None of the following screens will be used in the production environment.

What you will need

• Active registration in the Carat approval environment (obtained from our support team)
• Store registered and configured to use JavaScript payment with 3DS 2.0 authentication (obtained from our
  support)

Table with different cards used for testing:

Table with values in cents that can be used to simulate different statuses on 3DS:

Creating transaction

In our online store, found on the left side of the menu, a submenu titled Pagamento 3DS MPI. It's in this
submenu where we will generate the transaction, inserting the relevant information in the payload, such as the Merchant ID (your store code) and the
Merchant Key (key to your store). The other data cannot be changed, if you do not want to simulate different statuses of the
3DS 2.0 authentication. After filling in the data,
simply click the Fechar Pedido button to create the transaction.

subtitles

• 1 - 3DS MPI Payment Submenu
• 2 - Merchant ID
• 3 - Merchant Key
• 4 - Request Json
• 5 - Close Order

Payment page

On this page, the card data will be inserted, with calls to the startThreeDs and esitefDoPayment functions
are executed. After filling out the card, the startThreeDs function is triggered to validate the card on 3DS 2.0 and
check whether the 3DS Method will be used. This entire process takes place internally, without intervention from the buyer. When
all other fields on the screen are filled in and the CONFIRMAR PAGAMENTO button is clicked, the esitefDoPayment function
is activated. This function, in turn, performs payment authentication and authorization.

subtitles

• 1 - After filling out the card, the event is triggered to call the startThreeDs function
• 2 - When clicking the button CONFIRMAR PAGAMENTO the event is triggered to call the esitefDoPayment function

Challenge Flow

In certain situations, authentication with 3DS 2.0 may require a challenge to validate the cardholder's information.
card. When the buttonCONFIRMAR PAGAMENTO is pressed, the function esitefDoPayment will open a modal for carrying out
of this challenge. In our approval environment, a simulator will be displayed, offering options for the desired status of the
challenge - we will choose Status Y, indicating successful authentication - and then click on the button Enviar.

subtitle

• 1 - Combobox with challenge status options
• 2 - Enviar button to complete the challenge.

Helper pages

After completing the challenge or if you have not gone through the challenge flow, you will be redirected to a processing screen. This redirection is performed
by the onProcessing callback function, which was passed as a parameter in the esitefDoPayment function.

On the processing screen, there is an internal routine that performs a query to check if there has been any change in the transaction status.
If there are changes, redirection to the success screen is triggered, using the onSuccess callback function passed as a parameter
in the esitefDoPayment function.

Transaction Query Service

This service should be called after receiving the callbacks of success or failure to ensure the transaction status and obtain more information regarding the payment. This operation should also be used to inquire about the transaction status while waiting for a response from the payment page.

For more details about this call, refer to the REST Payment Transaction Inquiry Service.

Online Merchant Payment Page with 3DS Authentication

After completing the transaction creation step, the merchant's page should be displayed to the user. On this page, integrated with JavaScript payment and 3DS 2.0 authentication, it is crucial to include two files on the checkout page: a JS script and a CSS style sheet. These two files are essential to ensure that the 3DS 2.0 authentication payment functions correctly. In addition to these files, it is necessary to add an HTML tag to the payment page (this HTML tag will be used in the event of a 3DS method flow).

Below are the URLs for download:

Script JS

Below are the homologation and production URLs for download:

URL for Production environment:

https:///js/esitefauthenticatepayment-1.0.min.js

URL for Homologation environment:

https:///js/esitefauthenticatepayment-1.0.min.js

CSS style sheet

Below are the homologation and production URLs for download:

URL for Production environment:

https:///css/v2/threeds.css

URL para ambiente de Homologação:

https:///css/v2/threeds.css

Tag div

Below is the mandatory div tag for the operation of the 3DS method.

<div id="divThreeDsMethodData"></div>

The card fields must contain the specified classes below:

Two functions must be called during the checkout:

startThreeDsCall details : This function should be called through an event after the final card input; it initiates 3DS and, depending on the BIN, may trigger the 3DS method call if necessary.

esitefDoPaymentCall details : This function should be called through an event after filling in all the necessary data for the checkout completion. This call will initiate the 3DS authentication; the issuer may request a challenge to be performed by the buyer. In this case, a modal will open with the respective challenge. In this scenario, the merchant should redirect the end of the request to a processing screen and await the response from the status notification.

Below is an example of a page integrated with Carat's JavaScript payment:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Coleta de dados de cartão via JS</title
</form>

Key points of the implementation example above:

• Import of the JS for 3DS authentication:

<script type="text/javascript" src="https://esitef-homologacao.softwareexpress.com.br/js/esitefauthenticatepayment-1.0.min.js"></script>

• Import of the css for 3DS authentication:

<link rel="stylesheet" href="https://esitef-homologacao.softwareexpress.com.br/css/v2/threeds.css" />

• Call to the startThreeDs function. Learn more. (The call is inside the threedMethod function) when filling the card-number field with a length of 16:

    $("#card-number").on('blur', function() {
        result = isFieldSizeValid($(this).val(), 16, null);
        updateIconSignAndInput("#card-number", ".payment-checked-number", ".payment-error-number", (result));
    
        if(result){
            threedMethod();
        }
    
        enableConfirmButton(result);
    });

• Implementation of the request creation and startThreeDs function call:

function threedMethod() {
   var request = {
      onSuccess: function(response) {
         var responseValue = JSON.stringify(response);
      },
      onFailure: function(response) {
          var responseValue = JSON.stringify(response);
          console.log("Error 3ds method: "+ responseValue);
      },
      onInvalid: function(response) {
         var message = response[0].field + ' ' + response[0].cause;
         for (var i = 1; i < response.length; i++) {
             message += ', ' + response[i].field + ' ' + response[i].cause;
         }
         document.getElementById('resultInvalid').innerHTML = message;
      },
      nit: findGetParameter('nit'),
      payToken: findGetParameter('payToken'),
      merchantId: findGetParameter('merchantId'),
      authorizerId: findGetParameter('authorizerId')
   };
  startThreeDs(request);

• Implementation of the request creation and esitefDoPayment function call:

function myPay() {
   var request = {
      onSuccess: function(response) {
         var responseValue = JSON.stringify(response);
         localStorage.setItem('resultSuccess', responseValue);
  esitefDoPayment(request);

• Implementation of the div with id="divThreeDsMethodData" for the execution of the 3DS method:

  <div id ="divThreeDsMethodData"></div>

Start ThreeDS

Function startThreeDs in Carat's JavaScript

This call is essential to activate 3DS 2.0 authentication, check if the cardholder's card number is within the
supported card range for authentication, and, when necessary, initiate the 3DS Methods flow to capture
additional browser information, aiming to facilitate risk-based decision-making (RBA - Risk-Based
Analysis), increasing the chances of obtaining a challenge-free authentication.

To use the startThreeDs function, simply add the JavaScript payment file with 3DS 2.0 authentication and the div tag
to the checkout page. Both the file and the div tag are essential to
ensure that the startThreeDs function works correctly.

Script JS

URL for Production environment:

https:///js/esitefauthenticatepayment-1.0.min.js

URL for Homologation environment:

https:///js/esitefauthenticatepayment-1.0.min.js

Below is the mandatory div tag for the operation of the 3DS method.

<div id="divThreeDsMethodData"></div>

Card number field

In addition to the items mentioned earlier, it is crucial that the card number field has the specified class below:

Example

<input type="number" id="card-number" maxlength="16"  class="esitef-cardnumber">

Calling the startThreeDS function in Carat JavaScript

When the buyer enters the card number on the screen, it is possible to create a JavaScript event or a button that triggers the startThreeDS function. The implementation of the event or button does not follow a specific rule, as long as it is triggered after filling in the card number. When calling the startThreeDS function, it is essential to provide a request with the following fields as arguments:

Response of Success and Failure Callbacks

The onSuccess and onFailure callback functions receive an object as an argument containing information regarding the response of the startThreeDs function. Below are the descriptions of these fields:

Validation error callback response.

The onInvalid callback function receives, as an argument, a list of validation error objects containing the following fields:

Example

Below is an example of a page integrated with Carat's JavaScript payment:

To use this example, don't forget to set the {{url}} variable with the value.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <script type="text/javascript" src="https://{{url}}/js/esitefauthenticatepayment-1.0.min.js"></script>
    <script>
        document.addEventListener('DOMContentLoaded', function() {
            document.getElementById('card-number').addEventListener('input', function() {
                var valor = this.value;

Authorize the Payment with Authentication

Function esitefDoPayment

After the customer fills in all the fields on the store's screen, they should click a button to complete the payment. In the onclick event, a JavaScript function should be called, filling the request with nit, payToken, merchantId, authenticate, onSuccess callback function, onProcessing, onFailure, onInvalid, and subsequently invoking the esitefDoPayment function, passing the request as a parameter.
The esitefDoPayment function performs 3DS authentication, which may display a challenge involving security code checks, token validation, approvals on the buyer's mobile device, or other verifications. Following authentication, payment authorization takes place with the acquirer.
It is important to clarify that, according to the parameterization provided during the transaction creation (authenticate field), the transaction authorization behavior may change:

• If the transaction is submitted with authenticate = 1, then the transaction will only be authorized if the authentication is approved.
• If the transaction is submitted with authenticate = 2, then the transaction will only be authorized if the authentication is approved, but for card networks not supported by 3DS, the authentication step will be skipped.
• If the transaction is submitted with authenticate = 3, then the transaction will go through the authentication flow, but if there is a negative result, the flow proceeds to authorization.

Calling the Carat script

When the buyer fills in the card details and clicks 'pay,' the merchant's page should call the JavaScript function esitefDoPayment, passing as an argument a request with the following fields:

Response from success and failure callbacks.

The callback functions onSuccess and onFailure receive an object as an argument containing information related to the payment. Below are the descriptions of these fields:

Validation error callback response.

The onInvalid callback function receives, as an argument, a list of objects representing validation errors, containing the following fields:

Example

Below is an example of a JavaScript function calling esitefDoPayment:

function myPay() {
    var request = {
          onSuccess: function(response) {
             var responseValue = JSON.stringify(response);
             localStorage.setItem('resultSuccess', responseValue);
        
             if (response.payment.status == 'PPC') {
                window.location = 'loja-pag-pendente-3ds-mpi.html?nit='+ findGetParameter('nit');                    
             } else {
                 window.location = 'loja-sucesso-3ds-mpi.html';
             }
          },
          onProcessing: function() {
             window.location = 'loja-pag-pendente-3ds-mpi.html?nit='+ findGetParameter('nit');
          },
          onFailure: function(response) {
              var responseValue = JSON.stringify(response);
              localStorage.setItem('resultFailure', responseValue);
        
              window.location = 'loja-fracasso-js.html';
          },
          onInvalid: function(response) {
             var message = response[0].field + ' ' + response[0].cause;
             for (var i = 1; i < response.length; i++) {
                 message += ', ' + response[i].field + ' ' + response[i].cause;
             }
             document.getElementById('resultInvalid').innerHTML = message;
          },
          nit: findGetParameter('nit'),
          payToken: findGetParameter('payToken'),
          merchantId: findGetParameter('merchantId'),
          authenticate: 'true'
    };
    
    esitefDoPayment(request);
}

Transaction Creation Service

The consumption of this service is mandatory in the JavaScript payment flow. In addition to the
REST payment request parameters, the following parameters must also be sent:

In response, the following parameter will be additionally returned:

For more details about this call, refer to REST Payment.

Example

Request:

To use this example, don't forget to set the variable. {{url}} with the value

curl
--request POST "https://{{url}}/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxx"
--data-binary
{
    "authenticate": "1",
    "merchant_usn":"12042142155",
    "order_id":"12042142155",
    "installments":"1",
    "installment_type":"4",
    "authorizer_id":"2",
    "amount":"10004",
    "payment_js":"true"
}
--verbose

Response:

{
    "code":"0",
    "message":"OK. Transaction successful.",
    "payment":{
        "status":"NOV",
        "nit":"1234567890123456789012345678901234567890123456789012345678901234",
        "order_id":"12042142155",
        "merchant_usn":"12042142155",
        "amount":"1000",
        "pay_token":"123456789012345678901234567890123456789012345678901234567890123456"
    }
}

Customization of the threeds.css File

The modal displayed in the 3DS 2.0 authentication challenge is customizable. To customize it, you can replace
the threeds.css file with another, as long as the new file follows the code structure provided below. Ensure to
preserve the same class names and style logic to ensure the proper functioning of the modal.

Presentation of the Modal

In 3DS 2.0 authentication, the dimensions of the challenge are standardized through an integer provided in the
challengeWindowSize field. It is through this parameter that the size of the content in the challenge is replicated.
This field is a parameter in the esitefDoPayment function call in the Carat JavaScript. If no value is provided,
a default value will be automatically configured based on the buyer's screen size. The following are the possible values for use:

File threeds.css

Default Modal

.modal-challenge {
  display: block;
  position: fixed;
  top: 50%;
  left: 50%;
  transform: translate(-50%, -50%) translateY(-100%);
  background-color: #fff;
  border: 1px solid #ccc;
  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
  z-index: 1000;
  border-radius: 10px;
  opacity: 0;
  transition: transform 0.3s ease-out, opacity 0.6s ease;
}

Modal opening

.modal-challenge.open {
  transform: translate(-50%, -50%) translateY(0);
  opacity: 1;
}

Overlay (initially transparent)

.overlay-challenge {
  display: block;
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  background-color: rgba(0, 0, 0, 0);
  z-index: 999;
}

Adding to the overlay when the modal is open

.overlay-challenge.open {
  background-color: rgba(0, 0, 0, 0.3);
}

Transaction begin process

The transaction creation process must follow the following steps:

• The transaction is created according to the parameters sent in the request key and represented by a JSON object via POST in the request;
• The store receives a success or error message, formatted as XML or JSON, according to the "return type" parameter in the URL sent when starting a transaction.

URL to start a transaction via POST HTTPS:

Attention: The IP should never be used instead of the domain esitef-ec.softwareexpress.com.br (or {{url}} for the approval environment). The IP can change at any time and without prior notice, so it is important to always use the domain to access Carat.

• Header parameters:

For more information see HTML transaction creation service

Integration specific parameters

The HTML transaction creation service has the following fields specific to the 3DS 2.0 integration:

ATTENTION: Parameters that exist in payer, billing and shipment when not passed to the transaction creation service via additional_data, will be requested in the payment screen. However, if the parameters are passed in the transaction creation service, you will not be asked to fill in the fields on the payment screen.

JSON example:

{
  "merchant_id": "XXXXX",
  "authorizer_id": "2",
  "amount": "10004",
  "authenticate": "1",
  "additional_data": {
    "purchase_information_data": {
      "date": "20201023113749"
    },
    "exponent": "2",
    "authentication": {
      "transaction_type": "01",
      "indicator": "01"
    }
  }
}

Mastercard 3DS Identity Check Insights (Dataonly)

Identity Check Insights is a 3DS mode exclusive to Mastercard that has the following characteristics:

• It provides a frictionless experience, with reduced latency and no possibility of a cardholder challenge.
• The merchant will be responsible for paying for the fraud (without liability shift).
• Higher approval rate.
• Exclusive for Mastercard branded cards.

More details in the official Mastercard documentation.

In Carat Portal it is possible to make a payment transaction using Identity Check Insights in two ways:

• Via parameter when starting a payment transaction
• Via merchant configuration

Via parameter when starting transaction

The merchant can indicate that he wants to use Identity Check Insights by informing the value 80 in the parameter additional_data.authentication.message.category.

Example:

{
  "merchant_id": "LOJAYYZ",
  "authorizer_id": "2",
  "amount": "10004",
  "authenticate": "1",
  "additional_data": {
    "purchase_information_data": {
      "date": "20201023113749"
    },
    "exponent": "2",
    "authentication": {
      "transaction_type": "01",
      "indicator": "01",
      "message": {
        "category": "80"
      }
    }
  }
}

Via merchant configuration

The merchant can ask the e-SiTef Support Team to enable the option Utiliza Mastercard 3DS Identity Check Insights.

With this setting enabled, all payment transactions using Mastercard and Maestro branded cards will use Mastercard 3DS Identity Check Insights by default.

Example:

{
  "merchant_id": "DATAONLYON",
  "authorizer_id": "2",
  "amount": "10004",
  "authenticate": "1",
  "additional_data": {
    "purchase_information_data": {
      "date": "20201023113749"
    },
    "exponent": "2",
    "authentication": {
      "transaction_type": "01",
      "indicator": "01"
    }
  }
}

It is possible to override this behavior by sending the value 01 in the parameter additional_data.authentication.message.category, ignoring the merchant configuration.

Example:

{
  "merchant_id": "DATAONLYON",
  "authorizer_id": "2",
  "amount": "10004",
  "authenticate": "1",
  "additional_data": {
    "purchase_information_data": {
      "date": "20201023113749"
    },
    "exponent": "2",
    "authentication": {
      "transaction_type": "01",
      "indicator": "01",
      "message": {
        "category": "01"
      }
    }
  }
}

Customizations

Customizations

Interval limits for 3DS automatic activation

For cases where the interval limits for automatic activation of 3DS are configured in the merchant and a value of authenticate is passed in the creation of the transaction, the Carat Portal will only accept the value of authenticate passed if the transaction is between the activation limits. And if the 3DS automatic activation interval limits are configured in the merchant and an authenticate value is not passed in the transaction, the value 1 will be assumed as the default for the authentication type. Important: intervals that allow the use of 3DS and anti-fraud together must not be used. More information at Integration specific parameters.

Antifraud over 3DS

It is possible to configure in the merchant a parameter for activating anti-fraud if the chosen brand does not support 3DS. If the transaction using a merchant with this configuration is marked with 3DS (with authenticate = 1) and the card used is not supported on the 3DS Server (brand was not certified or card out of range in the 3DS base for authentication), then Payment Online will not deny the transaction and will follow the payment flow using anti-fraud ("enabled_after_auth"). Please contact our support team to find out how to enable this setting.

Mastercard 3DS Identity Check Insights (Dataonly)

Mastercard 3DS Identity Check Insights (Dataonly)

Identity Check Insights is a 3DS mode exclusive to Mastercard that has the following characteristics:

• It provides a frictionless experience, with reduced latency and no possibility of a cardholder challenge.
• The merchant will be responsible for paying for the fraud (without liability shift).
• Higher approval rate.
• Exclusive for Mastercard branded cards.

More details in the official Mastercard documentation.

In Carat Portal it is possible to make a payment transaction using Identity Check Insights in two ways:

• Via parameter when starting a payment transaction
• Via merchant configuration

Via parameter when starting transaction

The merchant can indicate that he wants to use Identity Check Insights by informing the value 80 in the parameter additional_data.authentication.message.category.

Example:

{
  "merchant_id": "LOJAYYZ",
  "authorizer_id": "2",
  "amount": "10004",
  "authenticate": "1",
  "additional_data": {
    "purchase_information_data": {
      "date": "20201023113749"
    },
    "exponent": "2",
    "authentication": {
      "transaction_type": "01",
      "indicator": "01",
      "message": {
        "category": "80"
      }
    }
  }
}

Via merchant configuration

The merchant can ask the e-SiTef Support Team to enable the option Utiliza Mastercard 3DS Identity Check Insights.

With this setting enabled, all payment transactions using Mastercard and Maestro branded cards will use Mastercard 3DS Identity Check Insights by default.

Example:

{
  "merchant_id": "DATAONLYON",
  "authorizer_id": "2",
  "amount": "10004",
  "authenticate": "1",
  "additional_data": {
    "purchase_information_data": {
      "date": "20201023113749"
    },
    "exponent": "2",
    "authentication": {
      "transaction_type": "01",
      "indicator": "01"
    }
  }
}

It is possible to override this behavior by sending the value 01 in the parameter additional_data.authentication.message.category, ignoring the merchant configuration.

Example:

{
  "merchant_id": "DATAONLYON",
  "authorizer_id": "2",
  "amount": "10004",
  "authenticate": "1",
  "additional_data": {
    "purchase_information_data": {
      "date": "20201023113749"
    },
    "exponent": "2",
    "authentication": {
      "transaction_type": "01",
      "indicator": "01",
      "message": {
        "category": "01"
      }
    }
  }
}