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, thenCaratwill 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 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 in 3ds transactions. | = 2 N | NO |
indicator | Indicates the type of Authentication request.
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.
| = 2 N | NO |
address_match | Indicates whether the delivery address and billing address of the bearer are 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.
| = 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.
| = 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.
| = 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.
| = 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.
| = 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.
| = 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.
| = 2 N | NO |
ship_name_indicator | Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.
| = 2 N | NO |
suspicious_activity | Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
| = 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.
| = 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.
| = 2 N | NO |
reorder_items_indicator | Indicates whether the cardholder is reordering previously purchased merchandise.
| = 2 N | NO |
shipping_indicator | Indicates shipping method chosen for the transaction.
| = 2 N | NO |
additional_data.authentication.message | Details about 3DS messaging. | ||
category | Identifies the message category for a specific use case.
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:
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,billingandshipmentwhen not passed to the transaction creation service viaadditional_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:
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:
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:
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: