});

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 to 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 Establishment Code in Cielo E-Commerce 3.0 or Getnet, or PV at Rede Numeric [10 positions]
MerchantName Name of registered establishment in the acquirer 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

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 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 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 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 merchant.
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 merchant.
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]

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
}

Please refer to the full list of ReturnCodes for more information.

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.

Data category Field Description Type/Size Required    
Parametrization 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    
Parametrization 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    
Parametrization 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    
Parametrization bpmpi_accesstoken Token generated by the Access Token API (step 1) Alphanumeric [variable] Yes    
Order Information bpmpi_ordernumber Order code at establishment Alphanumeric [up to 50 positions] Yes    
Order Information bpmpi_currency Currency Code Fixed “BRL” Yes    
Order Information bpmpi_totalamount Total transaction amount, sent in cents Numeric [up to 15 positions] Yes    
Order Information bpmpi_installments Number of Installments Numeric [up to 2 positions] Yes    
Order Information 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    
Order Information bpmpi_cardnumber Card Number Numeric [up to 19 positions] Yes    
Order Information bpmpi_cardexpirationmonth Card expiration month Numeric [2 positions] Yes    
Order Information bpmpi_cardexpirationyear Card expiration year Numeric [4 positions] Yes    
Order Information bpmpi_cardalias Card Alias Alphanumeric [up to 128 positions] No    
Order Information bpmpi_default_card Indicates if it is a standard customer card in store Boolean
true - yes
false - no
No    
Order characteristics bpmpi_recurring_enddate Identifies recurrence end date Text (YYYY-MM-DD) No    
Order characteristics bpmpi_recurring_frequency Indicates frequency of recurrence Number
1 - Monthly
2 - Bimonthly
3 - Quarterly
4 - Four-month period
6 - Half-yearly
12 - Annual
No    
Order characteristics bpmpi_recurring_originalpurchasedate Identifies the date of the 1st transaction that originated the recurrence Text (YYYY-MM-DD) No    
Order characteristics bpmpi_order_recurrence Indicates if it is an order that generates future recurrences Boolean
true
false
No    
Order characteristics 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 characteristics bpmpi_order_countlast24hours Quantity of orders placed by this shopper in the last 24h Numeric [up to 3 positions] No    
Order characteristics bpmpi_order_countlast6months Number of orders placed by this shopper in the last 6 months Numeric [up to 4 positions] No    
Order characteristics bpmpi_order_countlast1year Number of orders placed by this shopper in the last year Numeric [up to 3 positions] No    
Order characteristics bpmpi_order_cardattemptslast24hours Number of same card transactions in last 24h Numeric [up to 3 positions] No    
Order characteristics bpmpi_order_marketingoptin Indicates if the buyer has accepted to receive marketing offers Boolean
true – yes
false – no
No    
Order characteristics bpmpi_order_marketingsource Identifies the origin of the marketing campaign Alphanumeric [up to 40 positions] No    
Order characteristics bpmpi_transactionMode Identifies the channel that originated the transaction M: MOTO
R: Varejo
S: E-Commerce
P: Mobile
T: Tablet
No    
Order characteristics bpmpi_merchant_url Establishment Website Address Alphanumeric [100] Example: http://www.example.com Yes    
Gift Card (prepaid) bpmpi_giftcard_amount The total amount of the purchase for rounded prepaid gift cards Numeric [up to 15 positions],
example: $ 125.54 = 12554
No    
Gift Card (prepaid) bpmpi_giftcard_currency Prepaid Card Payment Transaction Currency Code Fixed “BRL” No    
Billing Address bpmpi_billto_customerid Identifies the shopper CPF/CNPJ Numeric [11 to 14 positions]
99999999999999
No    
Billing Address bpmpi_billto_contactname Billing Address Contact Name Alphanumeric [up to 120] Yes    
Billing Address bpmpi_billto_phonenumber Billing Address Contact Phone Numeric [up to 15 positions], in the format: 5511999999999 Yes    
Billing Address bpmpi_billto_email Billing Address Contact Email Alphanumeric [up to 255], in the format [name@example.com] (mailto: name@example.com) Yes    
Billing Address bpmpi_billto_street1 Address and Billing Address Number Alphanumeric [up to 60] Yes    
Billing Address bpmpi_billto_street2 Billing Address Supplement and Neighborhood Alphanumeric [up to 60] Yes    
Billing Address bpmpi_billto_city Billing Address City Alphanumeric [up to 50] Yes    
Billing Address bpmpi_billto_state Billing Address State Acronym Text [2 positions] Yes    
Billing Address bpmpi_billto_zipcode Billing Address Zip Code Alphanumeric [up to 8 positions], in the format: 99999999 Yes    
Billing Address bpmpi_billto_country Billing Address Country Text [2 positions] E.g: BR Yes    
Shipping Address bpmpi_shipto_sameasbillto Indicates whether to use the same address provided for billing address Boolean
true
false
No    
Shipping Address bpmpi_shipto_addressee Contact Name of Shipping Address Alphanumeric [up to 60] No    
Shipping Address bpmpi_shipTo_phonenumber Contact address of shipping address Numeric [up to 15 positions], in the format: 5511999999999 No    
Shipping Address bpmpi_shipTo_email Shipping Address Contact Email Alphanumeric [up to 255], in the format [name@example.com] (mailto: name@example.com) No    
Shipping Address bpmpi_shipTo_street1 Address and Delivery Address Number Alphanumeric [up to 60] No    
Shipping Address bpmpi_shipTo_street2 Delivery Address Complement and Neighborhood Alphanumeric [up to 60] No    
Shipping Address bpmpi_shipTo_city City of delivery address Alphanumeric [up to 50] No    
Shipping Address bpmpi_shipTo_state Shipping Address State Acronym Text [2 positions] No    
Shipping Address bpmpi_shipto_zipcode Shipping Address ZIP Code Alphanumeric [up to 8 positions], in the format: 99999999 No    
Shipping Address bpmpi_shipto_country Billing Address Country Text [2 positions] E.g.: BR No    
Shipping Address 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    
Shipping Address bpmpi_shipto_firstusagedate Indicates the date when the shipping address was first used Text
YYYY-MM-DD - Date Created
No    
Shopping Cart Details bpmpi_cart_#_description Item Description Alphanumeric [up to 255 positions] No    
Shopping Cart Details bpmpi_cart_#_name Item Name Alphanumeric [up to 255 positions] No Yes  
Shopping Cart Details bpmpi_cart_#_sku Item SKU Alphanumeric [up to 255 positions] No    
Shopping Cart Details bpmpi_cart_#_quantity Item Quantity in Cart Numeric [up to 10 positions] No    
Shopping Cart Details bpmpi_cart_#_unitprice Cart item unit value in cents Numeric [up to 10 positions] No    
User bpmpi_useraccount_guest Indicates if the buyer is a buyer without login (guest) Boolean
true – yes
false – no
No    
User bpmpi_useraccount_createddate Indicates the date when the buyer account was created Text
YYYY-MM-DD - Date Created
No    
User bpmpi_useraccount_changeddate Indicates the date when the last buyer account change Text
YYYY-MM-DD - date of last change
No    
User bpmpi_useraccount_passwordchangeddate Indicates the date when the buyer account password was changed Text
YYYY-MM-DD - Last Password Change Date
No    
User 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    
User bpmpi_useraccount_authenticationprotocol This represents the store login protocol Alphanumeric [up to 2048 positions] No    
User bpmpi_useraccount_authenticationtimestamp The date and time the store was logged in Text [19 positions] YYYY-MM-ddTHH: mm: SS No    
User bpmpi_merchant_newcustomer Identifies if a new buyer in the store Boolean
true – yes
false – no
No    
Device bpmpi_device_ipaddress Shopper’s Machine IP Address Alphanumeric [up to 45] Conditional - required only for Visa    
Device bpmpi_device_#_fingerprint Id returned by Device Finger Print Alphanumeric [without limitation] No    
Device bpmpi_device_#_provider Device Finger Print Provider Name Alphanumeric [up to 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    
Airline bpmpi_airline_travelleg _ # _ carrier IATA code for the stretch Alphanumeric [2 positions] No    
Airline bpmpi_useraccount_createddate Indicates the date when the buyer account was created Text
YYYY-MM-DD - Date Created
No    
Airline bpmpi_airline_travelleg_#_origin IATA code of origin airport Alphanumeric [5 positions] No    
Airline bpmpi_airline_travelleg_#_destination IATA code of destination airport Alphanumeric [5 positions] No    
Airline bpmpi_airline_passenger_#_name Passenger Name Alphanumeric [up to 60 positions] No    
Airline bpmpi_airline_passenger_#_ticketprice The ticket value in Numeric cents [up to 15 positions],
example: $ 125.54 = 12554
No      
Airline bpmpi_airline_numberofpassengers Number of Passengers Numeric [3 positions] No    
Airline bpmpi_airline_billto_passportcountry Passport country code (ISO Standard Country Codes) Text [2 positions] No    
Airline bpmpi_airline_billto_passportnumber Passport Number Alphanumeric [40 positions] No    
Merchant-defined data bpmpi_mdd1 Extra data defined by the merchant Alphanumeric [up to 255 positions] No    
Merchant-defined data bpmpi_mdd2 Extra data defined by the merchant Alphanumeric [up to 255 positions] No    
Merchant-defined data bpmpi_mdd3 Extra data defined by the merchant Alphanumeric [up to 255 positions] No    
Merchant-defined data bpmpi_mdd4 Extra data defined by the merchant Alphanumeric [up to 255 positions] No    
Merchant-defined data bpmpi_mdd5 Extra data defined by the merchant 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:

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
6505290000001234
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.

ANNEX

Reason Codes List

See the reason codes that Cybersource returns with the response.

Reason Code Description
100 Successful transaction.
101 The request is missing one or more required fields.
Possible action: See the response fields missingField_0 through missingField_N for the missing fields. Resend the request with the complete information.
102 One or more fields in the request contains invalid data.
Possible action: See the response fields invalidField_0 through invalidField_N for the invalid fields. Resend the request with the correct information.
150 Error: General system failure.
Possible action: Wait a few minutes and resend the request.
151 Error: The request was received, but a server time-out occurred. This error does not include time-outs between the client and the server.
Possible action: Wait a few minutes and resend the request.
152 Error: The request was received, but a service time-out occurred.
Possible action: Wait a few minutes and resend the request.
234 A problem exists with your merchant configuration.
Possible action: Do not resend the request. Contact Braspag Support to correct the configuration problem.
475 The customer is enrolled in payer authentication. Authenticate the cardholder before continuing with the transaction.
476 The customer cannot be authenticated.
Possible action: Review the customer’s order.
MPI901 Unexpected error.
MPI902 Unexpected authentication response.
MPI900 An error has occurred.
MPI601 Challenge suppressed.
MPI600 Brand not supported for authentication.