3DS 2.0 Checkout Fiserv

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:

Approval Environment:
https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/init/[return_type].se
Production Environment
https://esitef.softwareexpress.com.br/e-sitef/init/[return_type].se

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:

Parameter	Description	Format	Mandatory
`merchant_key`	Store authentication key in Carat. The production and certification keys will be different.	80 AN	YES

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:

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

Transaction begin process#

Integration specific parameters#

Mastercard 3DS Identity Check Insights (Dataonly)#

Via parameter when starting transaction#

Via merchant configuration#