3DS 2.2 Authentication

Redirecionando para https://docs.cielo.com.br/ecommerce-cielo-en/docs/what-is-3ds-22-authentication ...

The documentation for 3DS 2.2 Authentication is now on a new portal

new e-commerce developers portal for Cielo and Braspag

Access the new E-commerce developers portal at docs.cielo.com.br.

Warning: The content on this page is being discontinued and will not receive updates after 09/16/2024. Please visit the new documentation at docs.cielo.br.

3DS 2.2 Authentication

What is 3DS 2.2?

EMV 3DS, also known as 3DS 2.2 is an authentication technology developed by the payments industry in order to reduce the risk of fraud without harming the conversion rate. This new version analyzes several variables used as a criteria to determine the cardholder authencity, allowing in some cases decreased cardholder authentication interactions (challenges), without risking the merchant’s Liability Shift.

Main benefits:

Key words: Credit and Debit Card Authentication, EMVCO, 3DS 2.2, Visa, Mastercard, E-Commerce

Who is able to use the 3DS 2.2?

3DS 2.2 is valid for all e-commerce transactions, whether debit, credit or prepaid. For segments that have a high rate of chargeback/fraud, the solution tends to be even more advantageous compared to the benefit of passing the liability shift to the issuing bank.

What is required to use 3DS 2.2?

The merchant must attend the below requirements to use 3DS 2.2:

What is the Data Only - Notification Only

What is it?

Data Only is an optional field that can be used to contribute to the brand and issuer database, improving authentication performance.

Data Only can be used when the issuer does not perform authentication. In this case, if the Data only field was parameterized in the script, the brand will receive the parameterized data and share this information with the issuer. Over time, the issuer will have more transaction data for that card and the cardholder and will have more elements to perform authentication.

How to use Data Only?

Just parameterize bpmpi_auth_notifyonly. Authorization occurs in the same way as any [Authorization with Authentication].

To use Data Only, in Integração do script parameterize the field bpmpi_auth_notifyonly described in item Etapa de Autenticação – passo 3 – Mapeamento de classes.

In the Data Only model, additional 3DS 2.2 fields are mapped in the same way and sent to the brand, however, authentication is not requested

Data Only is valid for Mastercard and Visa brands.

For Data Only Mastercard, the ECI will always be 4;
For Data Only Visa, the ECI will always be 7.

What is the benefit of using Data Only?

Warning:

Payment Flow 3DS 2.2 | With challenge

Flow with challenge 01 Flow with challenge 02

  1. The holder fills the card details at the checkout of the merchant.
  2. The merchant set the 3DS 2.2 solution from Cielo via script for authentication.
  3. Cielo’s 3DS 2.2 solution sends the buyer’s information to the MPI (authentication platform).
  4. MPI communicates with the card brand to process the authentication. The brand identifies the issuer of the card, and sends the buyer’s information for analysis. The issuer identifies the holder as a possible risk, then, requires the challenge and returns the Authentication URL.
  5. A card brand returns an authentication URL to MPI.
  6. MPI returns the authentication URL to the 3DS 2.2 solution.
  7. The 3DS 2.2 solution return the authentication URL to the merchant via script.
  8. The script shows the authentication screen via lightbox.
  9. The holder solve the challenge on the issuer screen.
  10. The issuer returns the authentication result to the card brand.
  11. The card brand return the authentication result to the MPI.
  12. The MPI return the authentication result to the 3DS 2.2 solution.
  13. The 3DS 2.2 solution return the authentication result to the merchant via script (CAVV, ECI e XID).
  14. The merchant sends an authentication request with the authentication data to the API Cielo 3.0.
  15. The API Cielo 3.0 returns the authentication result to the merchant.
  16. The merchant notifies the payment result.

Payment Flow 3DS 2.2 | Without challenge

Flow without challenge

  1. The holder fills the card details at the checkout of the merchant.
  2. The merchant set the 3DS 2.2 solution from Cielo via script for authentication.
  3. Cielo’s 3DS 2.2 solution sends the buyer’s information to the MPI (authentication platform).
  4. MPI communicates with the card brand to process the authentication. The brand identifies the issuer of the card, and sends the buyer’s information for analysis. The issuer identifies the holder as a possible risk, then, requires the challenge and returns the Authentication URL.
  5. The card brand returns the silent authentication result (CAVV e ECI).
  6. The MPI returns the silent authentication result to the 3DS 2.2 solution.
  7. The 3DS 2.2 solution returns the silent authentication result to the merchant via script.
  8. The merchant sends an authentication request with the authentication data to the API Cielo 3.0.
  9. The API Cielo 3.0 returns the authentication result to the merchant.
  10. The merchant notifies the payment result.

How does the authenticated authorization via 3DS 2.2 work?

The authorization process using authentication through 3DS 2.2 occurs in two steps:

  1. Authentication
  2. Authorization

The steps below describes the detailed process:

Fluxo 3DS 2.0

  1. Cardholder choose to pay with credit or debit card.
  2. Merchant requests authentication through Cielo solution.
  3. Authentication platform can perform two ways: request cardholder authentication or perform the authentication silently. In the first case, the platform will return the Authentication URL to the merchant. In the second case, the next step is already is the return with the authentication result.
  4. Merchant presents the authentication interface on lightbox (Issuer Authentication URL).
  5. The cardholder authenticates in the issuer (process known as complete the challenge process)
  6. Card issuer returns authentication result to 3DS platform, which pass it back to the merchant.
  7. Merchant decides if they want to go ahead with authorization process. Once they decide to go ahead, the authentication result must be submitted with the authorization.
  8. Cielo returns the authorization result to the merchant, which passes it to the cardholder.

ECI (E-commerce Indicator)

The E-Commerce Indicator (ECI) is returned in the authentication process. This code is an indicator of what exactly occurred in the transaction authentication process.

Through ECI, it can be verified whether the transaction was authenticated and who was the agent responsible for that authentication. Check out the ECI table.

3DS Integration via Javascript

STEP 1. Access Token Request

The solution is composed by the access token request via the API and authentication request via Java Script.

Environment Endpoint Authorization
SANDBOX https://mpisandbox.braspag.com.br Basic (Authorization)
The Authorization must be generated concatenating “ClientID”, colon character (“:”) and “ClientSecret”
Ex. dba3a8db-fa54-40e0-8bab-7bfb9b6f2e2e:D/ilRsfoqHlSUChwAMnlyKdDNd7FMsM7cU/vo02REag=
after this, encode the result in base 64.
Then, this will generate an alphanumeric code that will be used in the access token request. For test purposes, use the following data:
ClientID: dba3a8db-fa54-40e0-8bab-7bfb9b6f2e2e
ClientSecret: D/ilRsfoqHlSUChwAMnlyKdDNd7FMsM7cU/vo02REag=
PRODUCTION https://mpi.braspag.com.br Please contact our support team to generate the “ClientID” and “ClientSecret” after integrating on sandbox environment.

Request

{
  "EstablishmentCode": "1006993069",
  "MerchantName": "Loja Exemplo Ltda",
  "MCC": "5912"
}

curl
--request POST "https://mpisandbox.braspag.com.br/v2/auth/token"
--header "Content-Type: application/json"
--header "Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--data-binary
--verbose
{
     "EstablishmentCode":"1006993069",
     "MerchantName": "Loja Exemplo Ltda",
     "MCC": "5912"
}
Parameter Description Type Size
EstablishmentCode Cielo E-commerce 3.0 affiliation code Numeric 10
MerchantName Merchant Name as registered on Cielo Alphanumeric Max 25
MCC Merchant category code Numeric 4

Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfbmFtZSI6IlFBXzNEU19BdXRoZW50aWNhdG9yIiwiY2xpZW50X2lkIjoiZGJhM2E4ZGItZmE1NC00MGUwLThiYWItN2JmYjliNmYyZTJlIiwic2NvcGVzIjoie1wiU2NvcGVcIjpcIjNEU0F1dGhlbnRpY2F0b3JcIixcIkNsYWltc1wiOlt7XCJOYW1lXCI6XCJNZXJjaGFudE5hbWVcIixcIlZhbHVlc1wiOFwiVmFsdWVzXCI6W1wiNTU1NVwiXX0se1wiTmFtZVwiOlwiUmVmZXJlbmNlSWRcIixcIlZhbHVlc1wiOltcImY3MjE1YmQ3LWM0OTQtNGQ5Yi1NzEyfQ.daMqXko3dZOV0TzNFQ2vSsVSKqOsrwuswg7RB82ecAASSSSSSSSSSSSFFFFFFFFFFFFFGGGGGGGGGGGGGGGGGGGGGGGG",
  "token_type": "barear",
  "expires_in": "2018-07-23T11:29:32"
}

--header "Content-Type: application/json"
--data-binary
{
      "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfbmFtZSI6IlFBXzNEU19BdXRoZW50aWNhdG9yIiwiY2xpZW50X2lkIjoiZGJhM2E4ZGItZmE1NC00MGUwLThiYWItN2JmYjliNmYyZTJlIiwic2NvcGVzIjoie1wiU2NvcGVcIjpcIjNEU0F1dGhlbnRpY2F0b3JcIixcIkNsYWltc1wiOlt7XCJOYW1lXCI6XCJNZXJjaGFudE5hbWVcIixcIlZhbHVlc1wiOFwiVmFsdWVzXCI6W1wiNTU1NVwiXX0se1wiTmFtZVwiOlwiUmVmZXJlbmNlSWRcIixcIlZhbHVlc1wiOltcImY3MjE1YmQ3LWM0OTQtNGQ5Yi1NzEyfQ.daMqXko3dZOV0TzNFQ2vSsVSKqOsrwuswg7RB82ecAASSSSSSSSSSSSFFFFFFFFFFFFFGGGGGGGGGGGGGGGGGGGGGGGG",
      "token_type": "barear",
      "expires_in": "2018-07-23T11:29:32"
}
Parameter Description Type
access_token Token required to continue with authentication Alphanumeric
token_type Fixed "Bearer" Alphanumeric
expires_in Token expiration time (minutes) Numeric

STEP 2. Script implementation

This step contains the script and the mapping of classes implementation responsable to comunicate with the authentication platform from brands and issuers. The example below shows the basic implementation. It is recommended that the snippet is placed at the end of the checkout HTML code:

To download the code, Click here

Script Example 3DS 2.0

Description of Events

The events are actions that the script considers as a response for following the authentication process, but do not indicate if the transaction was successfully authenticated.

The ECI (E-commerce Indicator) is what indicates if the transaction was authenticated or not and the liability in case of chargeback. In order to sumbit a transaction for authorization, please consider the ECI value and use the events only as a complemenatry information for decision-making.

Event Description
onReady This is triggered when the script is completely loaded, which includes validation of the access token, indicating that the checkout is ready to initiate authentication process
onSuccess It is triggered when the card is elegible and the authentication process is successfully finished. In this case, the variables CAVV, XID and ECI are returned. These data must be sent in together with the authorization request. In this scenario, if the transaction is authorized, the liability shift is transferred to the issuer.
onFailure It is triggered when the card is elegible but the authentication process failed for some reason. In this case, only ECI variable is returned. If the merchant decide to proceed with the authorization, the ECI must also be sent in the request. In this scenario if the transaction is authorized, the liability shift remains with the merchant.
onUnenrolled It is triggered when the card is not elegible, in other words, the cardholder and/or issuer does not support the authentication program. In this case, guide the shopper to check with the issuer if the card is enabled to perform authentication in e-commerce. Only the ECI variable is returned. If the merchant decides to proceed with the authorization, the ECI must be sent together with the authorization. If the transaction is authorized, the liability shift remains with the merchant.
onDisabled It is triggered when the merchant chooses not to submit the cardholder to the authentication process. ("bpmpi_auth" class set as false). In this scenario, if the transaction is authorized, the liability shift remains with the merchant.
onError It is triggered when the authentication process receives a systemic error. In this scenario, if the transaction is authorized, the liability shift remains with the merchant.
onUnsupportedBrand It is triggered when the card scheme is not supported by 3DS 2.2

Description of Request Parameters

Parameter Description Type
Environment Indicates the environment to be used (Sandbox or Production) String
SDB – Sandbox (test environment) PRD – Production (production environment)
Debug Boolean that identifies if debug mode is activated. When sent as true, the platform will generate the report on the browser’s debug mechanism. Boolean
true
false

NOTE!

The JavaScript file must be saved in the server where the merchant application is hosted. To download the file on Sandbox environment, access:

https://bit.ly/2CSOp2n

Output Description

Output Description Type Size
Cavv Authentication signature Text -
Xid Authentication request ID Text -
Eci E-commerce indicator code, which represents the authentication result Numeric Max 2
Version 3DS applied version Numeric 1
1.0 = 3DS 1.0;
2.0 = 3DS 2.0;
ReferenceId Authentication request ID GUID 36
ReturnCode Authentication return code Alphanumeric Max 5
ReturnMessage Authentication result message Alphanumeric Variable

Examples for script output

Example for event OnSuccess

{
  Cavv: 'Y2FyZGluYWxjb21tZXJjZWF1dGg=',
  Xid: null,
  Eci: '01',
  Version: '2',
  ReferenceId: '973cf83d-b378-43d5-84b6-ce1531475f2a'
}

Example for event OnFailure

{
  Xid: null,
  Eci: null,
  ReturnCode: '231',
  ReturnMessage: 'Unexpected error ocurred',
  ReferenceId: null
}

Example when card brand is not supported for authentication

When tha card brand is not supported for 3DS, the MPI returns the code “MPI600” and the message “Brand not supported for authentication”.

{
  Xid: null,
  Eci: null,
  ReturnCode: 'MPI600',
  ReturnMessage: 'Brand not supported for authentication',
  ReferenceId: null
}

Confira os valores possíveis de ReturnCodes na tabela Lista de Return Codes.

STEP 3. Mapping Classes

Classes that must be mapped in your HTML code.

Once the class is mapped to it’s given field, the script is able to retrieve the value contained in the field and submit it to compose the authentication request.

Data Category Field Description Type/Size Required
Parameterization bpmpi_auth Boolean indicating whether or not the transaction is submitted to the authentication process. Boolean:
true - submit to authentication
false - don’t subit to authentication		 Yes
Parameterization bpmpi_auth_notifyonly Boolean indicating whether the card transaction will be submitted in “notification only” mode. In this mode, the authentication process will not be triggered, however, the data will be submitted to the flag. VALID ONLY FOR MASTERCARD CARDS Boolean:
true - notification only mode;
false - authentication mode		 No
Parameterization bpmpi_auth_suppresschallenge Boolean that indicates if ignore or not the challenge. If the challenge is ignored, the liability will keep with the merchant. Boolean:
true – ignore challenge
false – perform challenge		 Yes
Parameterization bpmpi_accesstoken Token generated by Access Token API (step 1) Alphanumeric (variable) Yes
Order bpmpi_ordernumber Merchant order number Alphanumeric [max 50 positions] Yes
Order bpmpi_currency Currency code Fixed “BRL” Yes
Order bpmpi_totalamount Total transaction amount (cents) Numeric [max 15 positions] Yes
Order bpmpi_installments Number of Installments Numeric [max 2 positions] Yes
Order bpmpi_paymentmethod Card type to be authenticated. If the card has both functions, it is necessary to specify the transaction type. Credit - Credit Card
Debit - Debit Card		 Yes
Order bpmpi_cardnumber Card number Numeric [max 19 positions] Yes
Order bpmpi_cardexpirationmonth Card expiration month Numeric [max 2 positions] Yes
Order bpmpi_cardexpirationyear Card expiration year Numeric [max 4 positions] Yes
Order bpmpi_cardalias Card alias Alphanumeric [max 128 positions] No
Order bpmpi_default_card Indicates whether it is a standard customer card in the e-commerce Boolean
true - yes
false - no		 No
Order bpmpi_recurring_enddate End date of recurrency Text (AAAA-MM-DD) No
Order bpmpi_recurring_frequency Frequency of recurrency Number
1 - Monthly
2 - Bimonthly
3 - Quarterly
4 - Four Monthly
6 - Semester
12 - Annual		 No
Order bpmpi_recurring_originalpurchasedate Date of first transaction that orignated the recurrency Text (AAAA-MM-DD) No
Order Description bpmpi_order_recurrence Indicates whether it is an order that generates future recurrences Boolean
true
false		 No
Order Description bpmpi_order_productcode Product Type PHY: purchase Goods
CHA: Check acceptance
ACF: Account financing
QCT: Quasi-Cash Transaction
PAL: Prepaid Activation and Load
 Yes
Order Description bpmpi_order_countlast24hours Number of orders placed by same customer in the last 24 hours Numeric [max 3 positions] No
Order Description bpmpi_order_countlast6months Number of orders placed by same customer in the last 6 months Numeric [max 4 positions] No
Order Description bpmpi_order_countlast1year Number of orders placed by same customer in the last year Numeric [max 3 positions] No
Order Description bpmpi_order_cardattemptslast24hours Number of orders placed with the same card in the last 24 hours Numeric [max 3 positions] No
Order Description bpmpi_order_marketingoptin Indicates whether the shopper accepted to receive marketing offers Boolean
true - yes
false - no		 No
Order Description bpmpi_order_marketingsource Identifies the origin of the marketing campaign Alphanumeric [max 40 positions] No
Order Description bpmpi_transaction_mode Identifies the channel from which the transaction originates M: MOTO
R: Varejo
S: E-Commerce
P: Mobile
T: Tablet		 No
Order Description bpmpi_merchant_url Address of the e-commerce’s web site Alphanumeric [max 100 positions] Example: http://www.exemplo.com.br Yes
Prepaid cards bpmpi_giftcard_amount The total purchase amount for prepaid gift cards in rounded value Numeric [max 15 positions],
example: R$125,54 = 12554		 No
Prepaid cards bpmpi_giftcard_currency Transaction currency code paid with prepaid type card Fixed “BRL” No
Billing Address bpmpi_billto_customerid Identifies the CPF/CNPJ of customer Numeric [11 to 14 positions]
99999999999999		 No
Billing Address bpmpi_billto_contactname Billing address contact name Alphanumeric [max 120 positions] No
Billing Address bpmpi_billto_phonenumber Billing address phone number Numeric [max 15 positions], in the format: 5511999999999 No
Billing Address bpmpi_billto_email Billing address contact email Alphanumeric [max 255 positions], in the format name@example.com No
Billing Address bpmpi_billto_street1 Street address and billing address number Alphanumeric [max 60 positions] No
Billing Address bpmpi_billto_street2 Neighborhood and complement billing address Alphanumeric [max 60 positions] No
Billing Address bpmpi_billto_city Billing address city Alphanumeric [max 50 positions] No
Billing Address bpmpi_billto_state Billing address state Text [2 positions] No
Billing Address bpmpi_billto_zipcode Billing address zip code Alphanumeric [max 8 positions], in the format: 99999999 No
Billing Address bpmpi_billto_country Billing address country Text [2 positions] e.g., BR No
Delivery Address bpmpi_shipto_sameasbillto Indicates it is the same address provided on the billing address Boolean
true
false		 No
Delivery Address bpmpi_shipto_addressee Shipping address contact name Alphanumeric [max 60 positions] No
Delivery Address bpmpi_shipTo_phonenumber Delivery address phone number Numeric [max 15 positions], in the format: 5511999999999 No
Delivery Address bpmpi_shipTo_email Delivery address contact email Alphanumeric [max 255 positions], in the format name@example.com No
Delivery Address bpmpi_shipTo_street1 Street address and delivery address number Alphanumeric [max 60 positions] No
Delivery Address bpmpi_shipTo_street2 Neighborhood and complement delivery address Alphanumeric [max 60 positions] No
Delivery Address bpmpi_shipTo_city Delivery address city Alphanumeric [max 50 positions] No
Delivery Address bpmpi_shipTo_state Accuracy of delivery address state string [2 positions] No
Delivery Address bpmpi_shipto_zipcode Delivery address zip code Alphanumeric [max 2 positions], in the format: 99999999 No
Delivery Address bpmpi_shipto_country Delivery address country Text [2 positions], e.g., BR No
Delivery Address bpmpi_shipTo_shippingmethod Shipping method type lowcost
sameday
oneday
twoday
threeday
pickup
other		 No
Delivery Address bpmpi_shipto_firstusagedate Indicates the date of first use of the delivery address Text
AAAA-MM-DD - criation date		 No
Shopping Cart bpmpi_cart_#_description Item description Alphanumeric [max 255 positions] No
Shopping Cart bpmpi_cart_#_name Item name Alphanumeric [max 255 positions] No
Shopping Cart bpmpi_cart_#_sku Item SKU Alphanumeric [max 255 positions] No
Shopping Cart bpmpi_cart_#_quantity Cart item quantity Numeric [max 10 positions] No
Shopping Cart bpmpi_cart_#_unitprice Unit value of the cart item (cents) Numeric [max 10 positions] No
User bpmpi_useraccount_guest Indicates whether the customer is not logged (guest) Boolean
true - yes
false - no		 No
User bpmpi_useraccount_createddate Indicates the account creation date String
AAAA-MM-DD - creation date		 No
User bpmpi_useraccount_changeddate Indicates the last change date of shopper’s account String
AAAA-MM-DD - last alteration date		 No
User bpmpi_useraccount_passwordchangeddate Indicates the date when the shopper’s account password changed Text
AAAA-MM-DD - date of the last password change		 No
User bpmpi_useraccount_authenticationmethod Shopper’s authentication method 01 - No authentication
02 - Store login
03 - Login with federated ID
04 - Login with FIDO authenticator		 No
User bpmpi_useraccount_authenticationprotocol Data that represents the login protocol carried out in the store Alphanumeric [max 2048 positions] No
User bpmpi_useraccount_authenticationtimestamp The date and time the store was logged in String [max 19 positions]YYYY-MM-ddTHH:mm:ss No
User bpmpi_merchant_newcustomer Indicates whether the consumer is a new or existing customer with the merchant Boolean
true – yes
false – no		 No
Device bpmpi_device_ipaddress IP address of the shopper’s machine Alphanumeric [max 45 positions] Conditional - required for Visa only
Device bpmpi_device_#_fingerprint Id returned by Device Fingerprint Alphanumeric [no limit] No
Device bpmpi_device_#_provider Device Fingerprint provider name Alphanumeric [max 32 positions] cardinal
inauth
threatmetrix		 No
Device bpmpi_device_#_channel Channel from which the transaction came from. Possible values:
-Browser
-SDK
-3RI		 Alphanumeric [up to 7 positions] Yes
Recurrence bpmpi_recurring_type Recurring payment type. Number
1 - First transaction
2 - Subsequent transaction
3 - Modification
4-Cancellation		 No
Recurrence bpmpi_recurring_validationIndicator Indicates whether the recurring payment transaction was validated or not. Number
0 - Not validated
1 - Validated		 No
Recurrence bpmpi_recurring_maximumAmount Maximum amount agreed by the cardholder. numeric [up to 12 positions] No
Recurrence bpmpi_recurring_referenceNumber Unique reference number for the recurring payment transaction. Alphanumeric [up to 35 positions] No
Recurrence bpmpi_recurring_occurrence Indicates how often a recurring payment occurs. Number
01 - Daily
02 - Twice a week
03 - Weekly
04 - Every ten days
05 - Fortnightly
06- Monthly
07 - Bimonthly
08 - Every three months
09 - Every four months
10 - Every six months
11 - Annually
12 - Unscheduled.		 No
Recurrence bpmpi_recurring_numberOfPayments Total number of payments during the recurring subscription. Number [up to 2 positions] No
Recurrence bpmpi_recurring_amountType Indicates the type of recurring amount agreed by the cardholder. Supported values:
1 - Recurring payment of fixed value
2 - Recurring payment with maximum value.		 No
Airlines bpmpi_airline_travelleg_#_carrier IATA code for the stretch Alphanumeric [2 positions] No
Airlines bpmpi_airline_travelleg_#_departuredate Departure date String
AAAA-MM-DD		 No
Airlines bpmpi_airline_travelleg_#_origin IATA code from origin airport Alphanumeric [5 positions] No
Airlines bpmpi_airline_travelleg_#_destination IATA code from destination airport Alphanumeric [5 positions] No
Airlines bpmpi_airline_passenger_#_name Passenger name Alphanumeric [max 60 positions] No
Airlines bpmpi_airline_passenger_#_ticketprice Ticket price (cents) Numeric [max 15 positions],
example:R$125,54 = 12554		 No
Airlines bpmpi_airline_numberofpassengers Passenger number Numeric [3 positions] No
Airlines bpmpi_airline_billto_passportcountry Code of the country that emitted the passport (ISO Standard Country Codes) Text [2 positions] No
Airlines bpmpi_airline_billto_passportnumber Passport number Alphanumeric [40 positions] No
Merchant Defined Data bpmpi_mdd1 Extra data defined by the merchant Alphanumeric [max 255 positions] No
Merchant Defined Data bpmpi_mdd2 Extra data defined by the merchant Alphanumeric [max 255 positions] No
Merchant Defined Data bpmpi_mdd3 Extra data defined by the merchant Alphanumeric [max 255 positions] No
Merchant Defined Data bpmpi_mdd4 Extra data defined by the merchant Alphanumeric [max 255 positions] No
Merchant Defined Data bpmpi_mdd5 Extra data defined by the merchant Alphanumeric [max 255 positions] No
Merchant Defined Data bpmpi_brand_establishment_code Amex Establishment Code (EC) Text [10 positions] Required on Amex authentications

STEP 4. Implementing authentication request

The "bpmpi_Authenticate()" event must be requested when finishing the checkout(finishing the order). Example:

<input type="button"onclick="bpmpi_authenticate()" />

ECI (E-commerce Indicator)

The ECI (Electronic Commerce Indicator) is a code returned by the brands and indicates the result of the cardholder’s 3DS authentication with the issuer or brand. Check the ECIs corresponding to each flag and the authentication result in the table below.

Subsequently, the ECI value must be sent in the transaction request in the Payment.ExternalAuthentication.Eci field

Mastercard Visa Elo Amex Authentication result Was the transaction authenticated?
02 05 05 05 Authenticated by the issuer – chargeback risk goes to the issuer. Yes
01 06 06 06 Authenticated by the issuer – chargeback risk goes to the issuer. Yes
Different than 01, 02 and 04 Different than 05 and 06 Different than 05 and 06 Different than 05 and 06 Not authenticated - chargeback risk remais with the merchant. No
04 - - - Not authenticated, transaction characterized as Data Only - chargeback risk remains with the merchant. No

Card Numbers for test Purpose

Use the test cards below to simulate different scenarios in the SANDBOX environment

Test Cards with Challenge

CARD FLAG RESULT DESCRIPTION
4000000000001091
5200000000001096
6505290000001234		 VISA
MASTER
ELO		 SUCCESS Challenge authentication and bearer authenticated successfully
4000000000001109
5200000000001104
6505050000001109		 VISA
MASTER
ELO		 FAILURE Challenged authentication and bearer authenticated failed
4000000000001117
5200000000001112
6505050000001117		 VISA
MASTER
ELO		 UNENROLLED Challenge authentication currently unavailable
4000000000001125
5200000000001120
6505050000001125		 VISA
MASTER
ELO		 UNENROLLED System error during authentication step

No Challenge Test Cards

CARD FLAG RESULT DESCRIPTION
4000000000001000
5200000000001005
6505050000001000		 VISA
MASTER
ELO		 SUCCESS Unchallenged authentication and bearer successfully authenticated
4000000000001018
5200000000001013
6505050000001018		 VISA
MASTER
ELO		 FAILURE Unchallenged authentication and bearer authenticated failed

Authorization with Authentication

After authentication is completed, submit to the authorization procedure, sending the authentication data in the model of quot;external authentication" (node ExternalAuthentication ). This procedure is also valid for establishments that performed authentication outside Cielo (External MPI).

See example below, describing the Cielo E-commerce API authorization request authentication data:

Request

{
   "MerchantOrderId":"2017051002",
   "Customer":
   {
     (...)
   },
   "Payment":
   {
     (...)
     "Authenticate":true,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2021",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Cavv":"AAABB2gHA1B5EFNjWQcDAAAAAAB=",
       "Xid":"Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
       "Eci":"5",
       "Version":"2",
       "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
     }
   }
}

curl
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--header "MerchantKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--data-binary
--verbose
{
   "MerchantOrderId":"2017051002",
   "Customer":
   {
     (...)
   },
   "Payment":
   {
     (...)
     "Authenticate":true,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2021",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Cavv":"AAABB2gHA1B5EFNjWQcDAAAAAAB=",
       "Xid":"Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
       "Eci":"5",
       "Version":"2",
       "ReferenceId":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
     }
   }
}
Field Description Type/Size Required
Payment.Authenticate Boolean which defines whether the buyer will be directed to the issuing Bank for card authentication Boolean Yes, for authentication to be performed it is required to send as true
Payment.ExternalAuthentication.Cavv Signature that is returned in authentication success scenarios Text Yes, when authentication was a success
Payment.ExternalAuthentication.Xid XID returned in authentication process Text Yes, when the 3DS version is "1"
Payment.ExternalAuthentication.Eci E-Commerce Indicator returned in authentication process Numeric [1 character] Yes
Payment.ExternalAuthentication.Version 3DS version used in authentication process Alphanumeric [1 character] Yes, when the 3DS version is "2"
Payment.ExternalAuthentication.ReferenceId RequestID returned in authentication process GUID [36 characters] Yes, when the 3DS version is "2"

Response

See Cielo E-commerce API for the response.

Authorization for Data Only Transactions

After the authentication step in Data Only model is completed (field bpmpi_auth_notifyonly set as “true”), the transaction undergoes the authorization process by sending the authentication data in the “external authentication” model (node ExternalAuthentication).

See example below, describing the submission of authentication data from the Cielo E-commerce API authorization request, using POST:

Request

{  
   "MerchantOrderId":"2017051002",
   "Customer":
   {  
     (...)
   },
   "Payment":
   {  
     (...)
     "Authenticate":false,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{  
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2027",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Eci":"4",
       "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6",
       "dataonly":true
     }
   }
}

--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--header "MerchantKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--data-binary
--verbose
{  
   "MerchantOrderId":"2017051002",
   "Customer":
   {  
     (...)
   },
   "Payment":
   {  
     (...)
     "Authenticate":false,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{  
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2027",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Eci":"4",
       "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6",
       "dataonly":true
     }
   }
}
FIELD DESCRIPTION TYPE/SIZE REQUIRED
Payment.Authenticate Defines if the buyer will be directed to the issuing Bank for card authentication Boolean (true or false) Yes. For Data Only transactions the value must be “false”
Payment.ExternalAuthentication.Eci E-commerce Indicator returned in authentication process Numeric [1 position] Yes
Payment.ExternalAuthentication.ReferenceId RequestID returned in authentication process GUID [36 positions] Yes
Payment.ExternalAuthentication.DataOnly Defines if transaction is Data Only Boolean (true or false) Yes. For Data Only transactions the value must be “true”

Response

See Cielo E-commerce API for detailed examples of Authorization with Authentication response.