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