What is 3DS 2.0?

For more details about 3DS 2.0, please visit: https://braspag.github.io//en/manualp/emv3ds

Step 1 - Access Token Request

The solution consists of two steps, the API access token request and the JavaScript authentication request.

Environment	Endpoint	Authorization
SANDBOX	https://authsandbox.braspag.com.br/oauth2/token	Basic (Authorization) The Authorization value must be obtained by concatenating the value of the “ClientID”, colon (“:”), and “ClientSecret” E.g.: b4c14ad4-5184-4ca0-8d1a-d3a7276cead9:qYmZNOSo/5Tcjq7Nl2wTfw8wuC6Z8gqFAzc/utxYjfs= and then encode the result in base 64. This will generate an alphanumeric access code that will be used in the access token. For testing purposes, use the following data: ClientID : dba3a8db-fa54-40e0-8bab-7bfb9b6f2e2e ClientSecret:D/ilRsfoqHlSUChwAMnlyKdDNd7FMsM7cU/vo02REag=
PRODUCTION	https://auth.braspag.com.br/oauth2/token	Request the “ClientID” and “ClientSecret” data from the support team after completing sandbox development.

Request

{
     "EstablishmentCode":"1006993069",
     "MerchantName": "Example Store 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": "Example Store Ltda",
     "MCC": "5912"
}

Field	Description	Type/Size
EstablishmentCode	Cielo E-Commerce 3.0 Establishment Code	Numeric [10 positions]
MerchantName	Name of registered establishment in Cielo	Alphanumeric [up to 25 positions]
MCC	Merchant Category Code	Numeric [4 positions]

Response

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

--header "Content-Type: application/json"
--data-binary
{
      "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfbmFtZSI6IlFBXzNEU19BdXRoZW50aWNhdG9yIiwiY2xpZW50X2lkIjoiZGJhM2E4ZGItZmE1NC00MGUwLThiYWItN2JmYjliNmYyZTJlIiwic2NvcGVzIjoie1wiU2NvcGVcIjpcIjNEU0F1dGhlbnRpY2F0b3JcIixcIkNsYWltc1wiOlt7XCJOYW1lXCI6XCJNZXJjaGFudE5hbWVcIixcIlZhbHVlc1wiOFwiVmFsdWVzXCI6W1wiNTU1NVwiXX0se1wiTmFtZVwiOlwiUmVmZXJlbmNlSWRcIixcIlZhbHVlc1wiOltcImY3MjE1YmQ3LWM0OTQtNGQ5Yi1NzEyfQ.daMqXko3dZOV0TzNFQ2vSsVSKqOsrwuswg7RB82ecAASSSSSSSSSSSSFFFFFFFFFFFFFGGGGGGGGGGGGGGGGGGGGGGGG",
      "token_type": "bearer",
      "expires_in": "2018-07-23T11:29:32"
}

Field	Description	Type/Size
access_token	Token required to perform authentication.	Alphanumeric [variable size]
token_type	Fixed “bearer”	Alphanumeric
expires_in	Time in minutes to expire token	Numeric

Step 2 - Script Implementation

In this step we implement the script and mapping of classes, responsible for communicating with the brand and issuer authentication platforms. Follow the example below, which demonstrates the basic implementation. It is recommended that the snippet be placed at the end of your checkout HTML code:

To download the code, go here

3DS 2.0 Flux

Description of Events

Event	Description
onReady	Triggers when all solution script loading procedures have completed successfully, which includes access token validation, indicating that the checkout is ready to start authentication
onSuccess	Triggers when the card is eligible and has successfully completed the authentication process. In this case, the CAVV, XID, and ECI variables will be returned. This data must be sent in the request at the time of authorization. In this scenario, if the transaction is authorized, the liability shift is transferred to the issuer.
onFailure	Triggers when the card is eligible but the authentication process failed for some reason. In this case, only the ECI variable will be returned. If there is a decision to proceed with the authorization anyway, the ECI must be sent at the time of the request. In this scenario, if the transaction is authorized, the liability shift remains with the establishment.
onUnenrolled	Triggers when the card is not eligible, i.e. the holder and / or issuer does not participate in the authentication program. In this case, only the ECI variable will be returned. If there is a decision to proceed with the authorization anyway, the ECI must be sent at the time of the request. In this scenario, if the transaction is authorized, the liability shift remains with the establishment.
onDisabled	Triggers when the merchant has chosen not to subject the bearer to the authentication process (class “bpmpi_auth” as false). In this scenario, if the transaction is authorized, the liability shift remains with the establishment.
onError	Triggers when the authentication process has received a systemic error. In this scenario, if the transaction is authorized, the liability shift remains with the establishment.
onUnsupportedBrand	Triggers when card brand is not supported by 3DS 2.0

Description of Input Parameters

Parameter	Description	Type/Size
Environment	Indicates the environment to use (Sandbox or Production)	SDB - Sandbox (test environment) PRD - Production (production environment)
Debug	Boolean indicating whether debug mode is enabled or not. When true, the platform will report on the browser debug engine.	Boolean true - debug mode enabled false - debug mode disabled

IMPORTANT!

The JavaScript file must be saved on the server where the store application is located. To download the file, go to:

https://bit.ly/2CSOp2n

Description of outputs

Exit	Description	Type/Size
Cavv	Data representing authentication signature	Text
Xid	ID representing the authentication request	Text
Eci	E-commerce indicator code, which represents the result of authentication	Numeric [up to 2 positions]
Version	3DS Version Applied	Numeric [1 position] 1 - 3DS 1.02 - 3DS 2.0
ReferenceID	ID representing the authentication request	GUID [36 positions]
ReturnCode	Authentication Request Return Code	Alphanumeric [up to 5 positions]
ReturnMessage	Authentication Request Return Message	Alphanumeric [variable]

Step 3 - Class Mapping

The solution provides dozens of classes that must be mapped in your HTML code.

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

Parameterization Data	Description	Type/Size	Required
bpmpi_auth	Boolean indicating whether the transaction is submitted to or not for the authentication process	Boolean: true - submit to authentication false - do not submit to authentication	Yes
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 brand. VALID ONLY FOR MASTERCARD CARDS	Boolean: true - notification only mode; false - mode with authentication	No
bpmpi_auth_suppresschallenge	Boolean indicating whether or not to ignore the challenge when it exists. If a transaction authorized after ignoring the challenge, liability remains with the establishment.	Boolean: true - ignore challenges if any; false - present challenge if any	No
bpmpi_accesstoken	Token generated by the Access Token API (step 1)	Alphanumeric [variable]	Yes

Ordering Information	Description	Type/Size	Required
bpmpi_ordernumber	Order code at establishment	Alphanumeric [up to 50 positions]	Yes
bpmpi_currency	Currency Code	Fixed “BRL”	Yes
bpmpi_totalamount	Total transaction amount, sent in cents	Numeric [up to 15 positions]	Yes
bpmpi_installments	Number of Installments	Numeric [up to 2 positions]	Yes
bpmpi_paymentmethod	Type of card to be authenticated. In the case of a multiple card, you must specify either Credit or Debit	Credit - Credit CardDebit - Debit Card	Yes
bpmpi_cardnumber	Card Number	Numeric [up to 19 positions]	Yes
bpmpi_cardexpirationmonth	Card expiration month	Numeric [2 positions]	Yes
bpmpi_cardexpirationyear	Card expiration year	Numeric [4 positions]	Yes
bpmpi_cardalias	Card Alias	Alphanumeric [up to 128 positions]	No
bpmpi_default_card	Indicates if it is a standard customer card in store	Boolean true - yes false - no	No

Order characteristics data	Description	Type/Size	Required
bpmpi_recurring_enddate	Identifies recurrence end date	Text (YYYY-MM-DD)	No
bpmpi_recurring_frequency	Indicates frequency of recurrence	Number 1 - Monthly 2 - Bimonthly 3 - Quarterly 4 - Four-month period 6 - Half-yearly 12 - Annual	No
bpmpi_recurring_originalpurchasedate	Identifies the date of the 1st transaction that originated the recurrence	Text (YYYY-MM-DD)	No
bpmpi_order_recurrence	Indicates if it is an order that generates future recurrences	Boolean true false	No
bpmpi_order_productcode	Product Type	PHY: purchase Goods CHA: Check acceptance ACF: Account financing QCT: Quasi-Cash Transaction PAL: Prepaid Activation and Load	Yes
bpmpi_order_countlast24hours	Quantity of orders placed by this shopper in the last 24h	Numeric [up to 3 positions]	No
bpmpi_order_countlast6months	Number of orders placed by this shopper in the last 6 months	Numeric [up to 4 positions]	No
bpmpi_order_countlast1year	Number of orders placed by this shopper in the last year	Numeric [up to 3 positions]	No
bpmpi_order_cardattemptslast24hours	Number of same card transactions in last 24h	Numeric [up to 3 positions]	No
bpmpi_order_marketingoptin	Indicates if the buyer has accepted to receive marketing offers	Boolean true – yes false – no	No
bpmpi_order_marketingsource	Identifies the origin of the marketing campaign	Alphanumeric [up to 40 positions]	No
bpmpi_transactionMode	Identifies the channel that originated the transaction	M: MOTO R: Varejo S: E-Commerce P: Mobile T: Tablet	No
bpmpi_merchant_url	Establishment Website Address	Alphanumeric [100] Example: http://www.example.com	Yes

Specific data for Gift Card (prepaid)	Description	Type/Size	Required
bpmpi_giftcard_amount	The total amount of the purchase for rounded prepaid gift cards	Numeric [up to 15 positions], example: $ 125.54 = 12554	No
bpmpi_giftcard_currency	Prepaid Card Payment Transaction Currency Code	Fixed “BRL”	No

Billing Address Data	Description	Type/Size	Required
bpmpi_billto_customerid	Identifies the shopper CPF/CNPJ	Numeric [11 to 14 positions] 99999999999999	No
bpmpi_billto_contactname	Billing Address Contact Name	Alphanumeric [up to 120]	Yes
bpmpi_billTo_phonenumber	Billing Address Contact Phone	Numeric [up to 15 positions], in the format: 5511999999999	Yes
bpmpi_billTo_email	Billing Address Contact Email	Alphanumeric [up to 255], in the format [name@example.com] (mailto: name@example.com)	Yes
bpmpi_billTo_street1	Address and Billing Address Number	Alphanumeric [up to 60]	Yes
bpmpi_billTo_street2	Billing Address Supplement and Neighborhood	Alphanumeric [up to 60]	Yes
bpmpi_billTo_city	Billing Address City	Alphanumeric [up to 50]	Yes
bpmpi_billTo_state	Billing Address State Acronym	Text [2 positions]	Yes
bpmpi_billto_zipcode	Billing Address Zip Code	Alphanumeric [up to 8 positions], in the format: 99999999	Yes
country	Billing Address Country	Text [2 positions] E.g: BR	Yes

Shipping Address Data	Description	Type / Size	Required
bpmpi_shipto_sameasbillto	Indicates whether to use the same address provided for billing address	Boolean true false	No
bpmpi_shipto_addressee	Contact Name of Shipping Address	Alphanumeric [up to 60]	No
bpmpi_shipTo_phonenumber	Contact address of shipping address	Numeric [up to 15 positions], in the format: 5511999999999	No
bpmpi_shipTo_email	Shipping Address Contact Email	Alphanumeric [up to 255], in the format [name@example.com] (mailto: name@example.com)	No
bpmpi_shipTo_street1	Address and Delivery Address Number	Alphanumeric [up to 60]	No
bpmpi_shipTo_street2	Delivery Address Complement and Neighborhood	Alphanumeric [up to 60]	No
bpmpi_shipTo_city	City of delivery address	Alphanumeric [up to 50]	No
bpmpi_shipTo_state	Shipping Address State Acronym	Text [2 positions]	No
bpmpi_shipto_zipcode	Shipping Address ZIP Code	Alphanumeric [up to 8 positions], in the format: 99999999	No
bpmpi_shipto_country	Billing Address Country	Text [2 positions] E.g.: BR	No
bpmpi_shipTo_shippingmethod	Shipping Method Type	LOWCOST: Economical Shipping SAMEDAY: Same shipping ONEDAY: Next day shipping TWODAY: Two days shipping THREEDAY: Three days shipping PICKUP: Delivery at the store OTHER: There is no shippment	No
bpmpi_shipto_firstusagedate	Indicates the date when the shipping address was first used	Text YYYY-MM-DD - Date Created	No

Shopping Cart Details	Description	Type/Size	Required
bpmpi_cart_#_description	Item Description	Alphanumeric [up to 255 positions]	No
bpmpi_cart_#_name	Item Name	Alphanumeric [up to 255 positions]	No	Yes
bpmpi_cart_#_sku	Item SKU	Alphanumeric [up to 255 positions]	No
bpmpi_cart_#_quantity	Item Quantity in Cart	Numeric [up to 10 positions]	No
bpmpi_cart_#_unitprice	Cart item unit value in cents	Numeric [up to 10 positions]	No

User Data	Description	Type/Size	Required
bpmpi_useraccount_guest	Indicates if the buyer is a buyer without login (guest)	Boolean true – yes false – no	No
bpmpi_useraccount_createddate	Indicates the date when the buyer account was created	Text YYYY-MM-DD - Date Created	No
bpmpi_useraccount_changeddate	Indicates the date when the last buyer account change	Text YYYY-MM-DD - date of last change	No
bpmpi_useraccount_passwordchangeddate	Indicates the date when the buyer account password was changed	Text YYYY-MM-DD - Last Password Change Date	No
bpmpi_useraccount_authenticationmethod	Authentication Method of the shopper in the store	01- Does not happen authentication 02- Login at the own store 03- Login at federated ID 04- Login with FIDO authenticator	No
bpmpi_useraccount_authenticationprotocol	This represents the store login protocol	Alphanumeric [up to 2048 positions]	No
bpmpi_useraccount_authenticationtimestamp	The date and time the store was logged in	Text [19 positions] YYYY-MM-ddTHH: mm: SS	No
bpmpi_merchant_newcustomer	Identifies if a new buyer in the store	Boolean true – yes false – no	No

Data of device used for purchase	Description	Type/Size	Required
bpmpi_device_ipaddress	Shopper’s Machine IP Address	Alphanumeric [up to 45]	No
bpmpi_device_#_fingerprint	Id returned by Device Finger Print	Alphanumeric [without limitation]	No
bpmpi_device_#_provider	Device Finger Print Provider Name	Alphanumeric [up to 32 positions] cardinal inauth threatmetrix	No

Specific airline data	Description	Type/Size	Required
bpmpi_airline_travelleg _ # _ carrier	IATA code for the stretch	Alphanumeric [2 positions]	No
bpmpi_useraccount_createddate	Indicates the date when the buyer account was created	Text YYYY-MM-DD - Date Created	No
bpmpi_airline_travelleg_#_origin	IATA code of origin airport	Alphanumeric [5 positions]	No
bpmpi_airline_travelleg_#_destination	IATA code of destination airport	Alphanumeric [5 positions]	No
bpmpi_airline_passenger_#_name	Passenger Name	Alphanumeric [up to 60 positions]	No
bpmpi_airline_passenger_#_ticketprice	The ticket value in Numeric cents [up to 15 positions], example: $ 125.54 = 12554	No
bpmpi_airline_numberofpassengers	Number of Passengers	Numeric [3 positions]	No
bpmpi_airline_billto_passportcountry	Passport country code (ISO Standard Country Codes)	Text [2 positions]	No
bpmpi_airline_billto_passportnumber	Passport Number	Alphanumeric [40 positions]	No

Extra property data (if applicable)	Description	Type/Size	Required
bpmpi_mdd1	Extra data defined by the shopkeeper	Alphanumeric [up to 255 positions]	No
bpmpi_mdd2	Extra data defined by the shopkeeper	Alphanumeric [up to 255 positions]	No
bpmpi_mdd3	Extra data defined by the shopkeeper	Alphanumeric [up to 255 positions]	No
bpmpi_mdd4	Extra data defined by the shopkeeper	Alphanumeric [up to 255 positions]	No
bpmpi_mdd5	Extra data defined by the shopkeeper	Alphanumeric [up to 255 positions]	No

Step 4 - Implementing the Authentication Event Request

The event bpmpi_Authenticate()” must be called at checkout. See the example below:

UNTRANSLATED_CONTENT_START

UNTRANSLATED_CONTENT_END

Test Cards

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

Test cards with challenge

CARD	BRAND	RESULT	DESCRIPTION
4000000000001091 5200000000001096 6505050000001091	VISA MASTER ELO	SUCCESS	Authentication with challenge and cardholder successfully authenticated
4000000000001109 5200000000001104 6505050000001109	VISA MASTER ELO	FAILURE	Authentication with challenge and cardholder authentication terminated with failure
4000000000001117 5200000000001112 6505050000001117	VISA MASTER ELO	UNENROLLED	Authentication with challenge currently not available
4000000000001125 5200000000001120 6505050000001125	VISA MASTER ELO	UNENROLLED	System error during authentication

Test cards without challenge

CARD	BRAND	RESULT	DESCRIPTION
4000000000001000 5200000000001005 6505050000001000	VISA MASTER ELO	SUCCESS	Authentication without challenge and cardholder successfully authenticated
4000000000001018 5200000000001013 6505050000001018	VISA MASTER ELO	FAILURE	Authentication without challenge and cardholder authentication terminated with failure

Authorization with Authentication

After authentication is completed, it undergoes the authorization process by submitting the authentication data in the “external authentication” (node ExternalAuthentication). See more details at: https://braspag.github.io//en/manualp/authorization-with-authentication

Last updates

To see the manual’s latest updates, click here