What is 3DS 2.0?

For more details about 3DS 2.0, please visit: [https://braspag.github.io/manualp/emv3ds#o-que-%C3%A9-3ds-2.0?] (https://braspag.github.io/manualp/emv3ds#o-que-%C3%A9-3ds-2.0?)

Step 1 - Access Token Request

The solution consists of the API access token request step and Java Script authentication request step.

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 Required
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 Required
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, is implemented script and mapping of classes are responsible for communicating with the flag and sender 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] (https://github.com/Braspag/braspag.github.io/blob/docs/_i18n/pt/_posts/emv3ds/example.html)

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 It is 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 It is triggers when the card is eligible but has not had 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 It is triggered when the card is not eligible, ie 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 It is 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 It is triggered 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 flagged. ** 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 Month of Card Expiration Numeric [2 positions] Yes
bpmpi_cardexpirationyear Year of card expiration 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 (checkout). See the example below:

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

Test Cards

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

Cards Result Description
Visa: 4000000000001000
Mastercard: 5200000000001005
SUCCESS Silent Authentication and card holder successfully authenticated
Visa: 4000000000001018
Mastercard: 5200000000001013
FAILURE Silent and card holder authentication terminated with failure
Visa: 4000000000001034
Mastercard: 5200000000001039
UNENROLLED Card not eligible for authentication
Visa:4000000000001091
Mastercard: 5200000000001096
SUCCESS Challenging and card holder authentication successfully authenticated
Visa:4000000000001109
Mastercard: 5200000000001104
FAILURE Challenge authentication and card holder failed authentication

Authorization with Authentication

After authentication is completed, it undergoes the authorization process by submitting the authentication data in the & quot; external authentication & quot; (node ExternalAuthentication). See more details at: [https://braspag.github.io/manual/aautizacao-com-autenticacao[(https://braspag.github.io/manual/autorizacao-com-autenticacao)

Last updates

To view the latest manual updates, [click here] (https://github.com/Braspag/braspag.github.io/commits/docs/_i18n/en/_posts/emv3ds/2019-09-13-integracao-javascript .md)