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.
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 merchant | Alphanumeric [up to 255 positions] | No |
bpmpi_mdd2 | Extra data defined by the merchant | Alphanumeric [up to 255 positions] | No |
bpmpi_mdd3 | Extra data defined by the merchant | Alphanumeric [up to 255 positions] | No |
bpmpi_mdd4 | Extra data defined by the merchant | Alphanumeric [up to 255 positions] | No |
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. |