3DS 2.0 via Web Checkout

The Carat Portal HTML payment is integrated with 3DS Server, which is responsible for performing 3DS 2.0 authentications.

This model allows for easier integration, featuring two payment checkout modalities, frame and pop-up (both within the client's merchant), and can be customized with the client's logo and colors (white label).

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.

Automatic activation for debit#

Debit transactions will enable authentication by default, if the merchant is configured with 3DS data, thus overriding any other options that might disable this authentication method.

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.

Attention: If a request is performed with 3DS and antifraud using enabled_after_auth, and the transaction is successfully authenticated by the 3DS Server, then Carat will not proceed with the antifraud analysis.
If the user cancels or abandons the challenge before it is completed, antifraud will not be called and the transaction will be denied.

Available acquirers#


Bin
E.Rede
CieloEC

Available authorizers#

This integration is supported by the following authorizers:

ID	Name
`1`	Visa Credit
`2`	Mastercard Credit
`41`	Elo Credit
`221`	Visa Debit
`286`	Mastercard Debit
`288`	Elo Debit

Required credentials#

The following information must be provided to our support and production teams:

Name	Description
Acquirer Merchant ID	For each routing used, you must obtain your Acquirer Merchant ID from the acquirer. This value can be the same used as the establishment code for the authorization process, and must follow the format specified in ISO 8583.
Acquirer BIN	Identifier of each payment method assigned by the purchaser.

Thereby, the registration will be done so that the store is prepared to transact with 3DS.

Integration specific parameters#

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

Parameter	Description	Format	Mandatory
`authenticate`	Identifies the 3DS 2.0 authentication type. `1` = Enable the use of 3DS. But if the 3DS server does not support the flag or fails to perform authentication, payment will be denied. `2` = Enable the use of 3DS. However, if the 3DS server does not support the flag, it does not do authentication with 3DS server. If the flag is supported and authentication is denied, the payment will be denied. `3` = Enable the use of 3DS. However, even if authentication fails, payment will not be denied upon authentication, with the exception of cases where the user cancel or abandon the challenge before it is completed.	= 1 N	YES
`additional_data`	General transaction data.
`exponent`	Minor units of currency as specified in the ISO 4217 currency exponent. The default value will be `2`.	= 1 N	NO
`extra_info`	Additional information about the account optionally provided by the 3DS Requestor.	< 64 AN	NO
`additional_data` `.authentication`	General authentication data.
`transaction_type`	Identifies the type of transaction being authenticated. `01` = Goods/ Service Purchase `03` = Check Acceptance `10` = Account Funding `11` = Quasi-Cash Transaction `28` = Prepaid Activation and Load You should always consider `01` in 3ds transactions.	= 2 N	NO
`indicator`	Indicates the type of Authentication request. `01` = Payment transaction `02` = Recurring transaction `03` = Instalment transaction `04` = Add card `05` = Maintain card `06` = Cardholder verification as part of EMV token ID&V It should be assumed that it is always `01`. The recurrence scenario will not be addressed for the time being.	= 2 N	NO
`challenge_indicator`	Indicates whether a challenge is requested for this transaction. `01` = No preference `02` = No challenge requested `03` = Challenge requested (3DS Requestor preference) `04` = Challenge requested (Mandate) `05` = No challenge requested (transactional risk analysis is already performed) `06` = No challenge requested (Data share only) `07` = No challenge requested (strong consumer authentication is already performed) `08` = No challenge requested (utilise whitelist exemption if no challenge required) `09` = Challenge requested (whitelist prompt requested if challenge required)	= 2 N	NO
`address_match`	Indicates whether the delivery address and billing address of the bearer are the same. `Y` = Addresses are the same `N` = Addresses are not the same	= 1 AN	NO
`additional_data` `.authentication` `.info`	Information about how 3DS Requestor authenticated the cardholder before or during the transaction.
`method`	Mechanism used by the Cardholder to authenticate to the 3DS Requestor. `01` = No 3DS Requestor authentication occurred (i.e. cardholder “logged in” as guest) `02` = Login to the cardholder account at the 3DS Requestor system using 3DS Requestor’s own credentials `03` = Login to the cardholder account at the 3DS Requestor system using federated ID `04` = Login to the cardholder account at the 3DS Requestor system using issuer credentials `05` = Login to the cardholder account at the 3DS Requestor system using third-party authentication `06` = Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator `07` = Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator (FIDO assurance data signed) `08` = SRC Assurance Data	= 2 N	NO
`timestamp`	Date and time in UTC of the cardholder authentication in `YYYYMMDDHHMM` format.	= 12 N	NO
`additional_data` `.authentication` `.prior_info`	Information about how 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction.
`method`	Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor. `01` = Frictionless authentication occurred by ACS `02` = Cardholder challenge occurred by ACS `03` = AVS verified `04` = Other issuer methods	= 2 N	NO
`timestamp`	Date and time in UTC of the prior cardholder authentication in `YYYYMMDDHHMM` format.	= 12 N	NO
`reference`	This data element provides additional information to the ACS to determine the best approach for handing a request.	< 36 AN	NO
`additional_data` `.authentication` `.account`	Buyer's account information on 3DS Requestor.
`age_indicator`	Length of time that the cardholder has had the account with the 3DS Requestor. `01` = No account (guest check-out) `02` = Created during this transaction `03` = Less than 30 days `04` = 30−60 days `05` = More than 60 days	= 2 N	NO
`change_date`	Date that the cardholder’s account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added, in `YYYYMMDD` format.	= 8 N	NO
`change_indicator`	Length of time since the cardholder’s account information with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added. `01` = Changed during this transaction `02` = Less than 30 days `03` = 30−60 days `04` = More than 60 days	= 2 N	NO
`date`	Date that the cardholder opened the account with the 3DS Requestor in `YYYYMMDD` format.	= 8 N	NO
`password_change`	Date that cardholder’s account with the 3DS Requestor had a password change or account reset in `YYYYMMDD` format.	= 8 N	NO
`password_change_indicator`	Indicates the length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset. `01` = No change `02` = Changed during this transaction `03` = Less than 30 days `04` = 30−60 days `05` = More than 60 days	= 2 N	NO
`number_purchases`	Number of purchases with this cardholder account during the previous six months.	< 4 N	NO
`provision_attempts_day`	Number of card addition attempts in the last 24 hours.	< 3 N	NO
`txn_activity_day`	Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours.	< 3 N	NO
`txn_activity_year`	Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year.	< 3 N	NO
`payment_account_age`	Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor in `YYYYMMDD` format.	= 8 N	NO
`payment_account_indicator`	Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor. `01` = No account (guest check-out) `02` = During this transaction `03` = Less than 30 days `04` = 30−60 days `05` = More than 60 days	= 2 N	NO
`ship_address_usage`	Date when the shipping address used for this transaction was first used with the 3DS Requestor in `YYYYMMDD` format.	= 8 N	NO
`ship_address_usage_indicator`	Indicates when the shipping address used for this transaction was first used with the 3DS Requestor. `01` = This transaction `02` = Less than 30 days `03` = 30−60 days `04` = More than 60 days	= 2 N	NO
`ship_name_indicator`	Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction. `01` = Account Name identical to shipping Name `02` = Account Name different than shipping Name	= 2 N	NO
`suspicious_activity`	Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account. `01` = No suspicious activity has been observed `02` = Suspicious activity has been observed	= 2 N	NO
`additional_data` `.authentication` `.merchant_risk`	Store assessment of the level of fraud risk for carrier-specific authentication and the authentication being conducted.
`delivery_email_address`	For Electronic delivery, the email address to which the merchandise was delivered.	< 254 AN	NO
`delivery_timeframe`	Indicates the merchandise delivery timeframe. `01` = Electronic Delivery `02` = Same day shipping `03` = Overnight shipping `04` = Two-day or more shipping	= 2 N	NO
`gift_card_amount`	For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).	< 15 N	NO
`gift_card_count`	For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.	< 2 N	NO
`gift_card_currency`	For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card.	= 3 N	NO
`pre_order_date`	For a pre-ordered purchase, the expected date that the merchandise will be available in `YYYYMMDD` format.	= 8 N	NO
`pre_order_purchase_indicator`	Indicates whether Cardholder is placing an order for merchandise with a future availability or release date. `01` = Merchandise available `02` = Future availability	= 2 N	NO
`reorder_items_indicator`	Indicates whether the cardholder is reordering previously purchased merchandise. `01` = First time ordered `02` = Reordered	= 2 N	NO
`shipping_indicator`	Indicates shipping method chosen for the transaction. `01` = Ship to cardholder’s billing address `02` = Ship to another verified address on file with merchant `03` = Ship to address that is different than the cardholder’s billing address `04` = “Ship to Store” / Pick-up at local store (Store address shall be populated in shipping address fields) `05` = Digital goods (includes online services, electronic gift cards and redemption codes) `06` = Travel and Event tickets, not shipped `07` = Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.)	= 2 N	NO
`additional_data` `.authentication` `.message`	Details about 3DS messaging.
`category`	Identifies the message category for a specific use case. `01` - payment authentication `02` - Non-payment authentication `80` - Mastercard Identity Check Insights (Data only) authentication Default value: `01`.	= 2 N	NO
`additional_data` `.authentication` `.recurring`	Recurrence data.
`expiry`	Date on which no more authorizations will be made in the format `YYYYMMDD`. Mandatory when `authentication.indicator` = `02` or `03`.	= 8 N	COND.
`frequency`	Indicates the minimum number of days between authorizations. Mandatory when `authentication.indicator` = `02` or `03`.	< 4 N	COND.
`additional_data` `.purchase_information_data`	Purchase data.
`date`	UTC date and time of purchase in the format `YYYYMMDDHHMMSS`.	= 12 N	NO
`additional_data` `.payer`	Cardholder information.
`email`	The email address associated with the account that is either entered by the Cardholder, or is on file with the 3DS Requestor. If it is not sent, the completed form will be requested on the payment screen.	< 256 AN	NO
`name`	Name of the Cardholder. If it is not sent, the completed form will be requested on the payment screen.	< 45 AN	NO
`additional_data` `.payer` `.phones[]`	Cardholder phone information.
`ddi`	DDI of the phone. If it is not sent, the completed form will be requested on the payment screen.	< 3 N	NO
`ddd`	DDD of the phone. If it is not sent, the completed form will be requested on the payment screen.	< 3 N	NO
`number`	Phone number. If it is not sent, the completed form will be requested on the payment screen.	< 12 N	NO
`type`	Phone type: `1`: residential (fixed) `2`: commercial `6`: mobile When not sent, default value is assigned: `06`	< 12 N	NO
`additional_data` `.billing_data` `.address`	Billing address.
`city`	City. If it is not sent, the completed form will be requested on the payment screen.	< 50 AN	NO
`country`	ISO 3166-1 three-digit numeric country code. If it is not sent, the completed form will be requested on the payment screen.	= 3 N	NO
`street_name`	Street name. If it is not sent, the completed form will be requested on the payment screen.	< 50 AN	NO
`street_number`	Street number. If it is not sent, the completed form will be requested on the payment screen.	< 50 AN	NO
`complement`	Address complement. If it is not sent, the completed form will be requested on the payment screen.	< 50 AN	NO
`zip_code`	Zip code. If it is not sent, the completed form will be requested on the payment screen.	< 16 AN	NO
`state`	State acronym. If it is not sent, the completed form will be requested on the payment screen.	< 3 AN	NO
`additional_data` `.shipment` `.address`	Delivery address.
`city`	City. If it is not sent, the completed form will be requested on the payment screen.	< 50 AN	NO
`country`	ISO 3166-1 three-digit numeric country code. If it is not sent, the completed form will be requested on the payment screen.	= 3 N	NO
`street_name`	Street name. If it is not sent, the completed form will be requested on the payment screen.	< 50 AN	NO
`street_number`	Street number. If it is not sent, the completed form will be requested on the payment screen.	< 50 AN	NO
`complement`	Address complement. If it is not sent, the completed form will be requested on the payment screen.	< 50 AN	NO
`zip_code`	Zip code. If it is not sent, the completed form will be requested on the payment screen.	< 16 AN	NO
`state`	State acronym. If it is not sent, the completed form will be requested on the payment screen.	< 3 AN	NO

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"
      }
    }
  }
}

Home

Interval limits for 3DS automatic activation#

Automatic activation for debit#

Antifraud over 3DS#

Available acquirers#

Available authorizers#

Required credentials#

Integration specific parameters#

Mastercard 3DS Identity Check Insights (Dataonly)#

Via parameter when starting transaction#

Via merchant configuration#