3. Implementing the script
This step contains the script and the class mapping implementation responsible for comunicate with the card brands and issuers authentication platform. The example below shows the basic implementation. It is recommended that the snippet is placed at the end of the checkout HTML code:
A mouse-over the HTML code below will show the Copy button.
<html>
<head>
<title>Sample</title>
<script type="text/javascript">
function sendOrder() {
bpmpi_authenticate();
}
</script>
</head>
<body>
<div>
<h2>Sample</h2>
<input type="hidden" name="authEnabled" class="bpmpi_auth" value="true" />
<input
type="hidden"
name="authEnabledNotifyonly"
class="bpmpi_auth_notifyonly"
value="true"
/>
<input
type="hidden"
name="accessToken"
class="bpmpi_accesstoken"
value="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfbmFtZSI6IlFBXzNEU19BdXRoZW50aWNhdG9yIiwiY2xpZW50X2lkIjoiZGJhM2E4ZGItZmE1NC00MGUwLThiYWItN2JmYjliNmYyZTJlIiwic2NvcGVzIjoie1wiU2NvcGVcIjpcIjNEU0F1dGhlbnRpY2F0b3JcIixcIkNsYWltc1wiOlt7XCJOYW1lXCI6XCJNZXJjaGFudE5hbWVcIixcIlZhbHVlc1wiOltcIk1QSSBRQSBTdG9yZVwiXX0se1wiTmFtZVwiOlwiRXN0YWJsaXNobWVudENvZGVcIixcIlZhbHVlc1wiOltcIjEwMDU1NVwiXX0se1wiTmFtZVwiOlwiTUNDXCIsXCJWYWx1ZXNcIjpbXCI1NTU1XCJdfSx7XCJOYW1lXCI6XCJSZWZlcmVuY2VJZFwiLFwiVmFsdWVzXCI6W1wiMzU5ZmYxZWItOTgzNi00ZWFkLTg0OTItYjFhMDZhMjljYTRiXCJdfV19IiwiaXNzIjoiaHR0cHM6Ly9hdXRoc2FuZGJveC5icmFzcGFnLmNvbS5iciIsImF1ZCI6IlVWUXhjVUEyY1NKMWZrUTNJVUVuT2lJM2RtOXRmbWw1ZWxCNUpVVXVRV2c9IiwiZXhwIjoxNTM4MDcwMTk0LCJuYmYiOjE1Mzc5ODM3OTR9.uvQlQENbJomrdaRWYkBPeBAILJV9LuMdu5n7owhANoI"
/>
<div>
<label>Order Number:</label>
<input
type="text"
size="50"
name="orderNumber"
class="bpmpi_ordernumber"
value="123456"
/>
</div>
<div>
<label>Currency:</label>
<select name="currency" class="bpmpi_currency">
<option value="986" selected="selected">BRL</option>
<option value="840">USD</option>
<option value="032">ARS</option>
</select>
</div>
<div>
<label>Amount:</label>
<input
type="text"
size="50"
name="amount"
class="bpmpi_totalamount"
value="1000"
/>
</div>
<div>
<label>Installments:</label>
<input
type="text"
size="2"
name="installments"
class="bpmpi_installments"
value="1"
/>
</div>
<div>
<label>Payment Method:</label>
<select name="paymentMethod" class="bpmpi_paymentmethod">
<option value="credit" selected="selected">Credit</option>
<option value="debit">Debit</option>
</select>
</div>
<div>
<label>Card Number:</label>
<input
type="text"
size="50"
name="cardNumber"
class="bpmpi_cardnumber"
value="4000000000000002"
/>
</div>
<div>
<label>Expiration date:</label>
<input
type="text"
size="50"
name="expMonth"
class="bpmpi_cardexpirationmonth"
value="01"
/>
<input
type="text"
size="50"
name="expYear"
class="bpmpi_cardexpirationyear"
value="2021"
/>
</div>
<div>
<label>Card Alias:</label>
<input
type="text"
size="50"
class="bpmpi_cardalias"
value="cartaodoguilherme"
/>
</div>
<div>
<label>Default:</label>
<input type="text" size="50" class="bpmpi_default_card" value="true" />
</div>
<div>
<label>Recurring End Date:</label>
<input
type="text"
size="50"
class="bpmpi_recurring_enddate"
value="2021-01-16"
/>
</div>
<div>
<label>Recurring Frequency:</label>
<select class="bpmpi_recurring_frequency">
<option value="1">Monthly</option>
<option value="2">Bimonthly</option>
<option value="3">Quarterly</option>
<option value="4">FourMonths</option>
<option value="6">SemiAnnual</option>
<option value="12">Annual</option>
</select>
</div>
<div>
<label>Recurring Original Purchase Date:</label>
<input
type="text"
size="50"
class="bpmpi_recurring_originalpurchasedate"
value="2019-08-01T15:30:50"
/>
</div>
<fieldset style="width: 0">
<legend>Gift Card</legend>
<div>
<label>Amount:</label>
<input
type="text"
size="50"
class="bpmpi_giftcard_amount"
value="1000"
/>
<!-- em centavos -->
</div>
<div>
<label>Currency:</label>
<input
type="text"
size="50"
class="bpmpi_giftcard_currency"
value="BRL"
/>
</div>
</fieldset>
<!-- dados de cobrança -->
<fieldset style="width: 0">
<legend>Billing Address</legend>
<div>
<label>Customer ID (CPF/CNPJ):</label>
<input
type="text"
size="14"
class="bpmpi_billto_customerid"
value="12345678909"
/>
</div>
<div>
<label>New Customer:</label>
<select name="newCustomer" class="bpmpi_merchant_newcustomer">
<option value="credit" selected="selected">true</option>
<option value="debit">false</option>
</select>
</div>
<div>
<label>Name:</label>
<input
type="text"
size="50"
class="bpmpi_billto_name"
value="Comprador de Teste"
/>
</div>
<div>
<label>Phone number:</label>
<input
type="text"
size="50"
class="bpmpi_billto_phonenumber"
value="999225626381"
/>
</div>
<div>
<label>E-mail:</label>
<input
type="text"
size="50"
class="bpmpi_billto_email"
value="[email protected]"
/>
</div>
<div>
<label>Street 1:</label>
<input
type="text"
size="50"
class="bpmpi_billto_street1"
value="Av Marechal Camara 160"
/>
</div>
<div>
<label>Street 2:</label>
<input
type="text"
size="50"
class="bpmpi_billto_street2"
value="Sala 934 Centro"
/>
</div>
<div>
<label>City:</label>
<input
type="text"
size="50"
class="bpmpi_billto_city"
value="Rio de Janeiro"
/>
</div>
<div>
<label>State:</label>
<input type="text" size="50" class="bpmpi_billto_state" value="RJ" />
</div>
<div>
<label>Country:</label>
<input type="text" size="2" class="bpmpi_billto_country" value="BR" />
</div>
<div>
<label>Zipcode:</label>
<input
type="text"
size="50"
class="bpmpi_billto_zipcode"
value="20020080"
/>
</div>
</fieldset>
<!-- dados de entrega (obs: se o "bpmpi_shipto_sameasbillto" for "true" não é necessário enviar os dados de entrega) -->
<fieldset style="width: 0">
<legend>Delivery Address</legend>
<div>
<label>Same as billing address:</label>
<input
type="text"
size="50"
class="bpmpi_shipto_sameasbillto"
value="false"
/>
</div>
<div>
<label>Recipient:</label>
<input
type="text"
size="50"
class="bpmpi_shipto_name"
value="Destinatario de Teste"
/>
</div>
<div>
<label>Phone number:</label>
<input
type="text"
size="50"
class="bpmpi_shipto_phonenumber"
value="552122326381"
/>
</div>
<div>
<label>E-mail:</label>
<input
type="text"
size="50"
class="bpmpi_shipto_email"
value="[email protected]"
/>
</div>
<div>
<label>Street 1:</label>
<input
type="text"
size="50"
class="bpmpi_shipto_street1"
value="Rua do Carmo 64"
/>
</div>
<div>
<label>Street 2:</label>
<input
type="text"
size="50"
class="bpmpi_shipto_street2"
value="2º andar Centro"
/>
</div>
<div>
<label>City:</label>
<input
type="text"
size="50"
class="bpmpi_shipto_city"
value="Rio de Janeiro"
/>
</div>
<div>
<label>State:</label>
<input type="text" size="50" class="bpmpi_shipto_state" value="RJ" />
</div>
<div>
<label>Country:</label>
<input type="text" size="2" class="bpmpi_shipto_country" value="BR" />
</div>
<div>
<label>Zipcode:</label>
<input
type="text"
size="50"
class="bpmpi_shipto_zipcode"
value="20011020"
/>
</div>
<div>
<label>Shipping Method:</label>
<input
type="text"
size="50"
class="bpmpi_shipto_shippingmethod"
value="lowcost"
/>
<!-- ver domínio no manual -->
</div>
<div>
<label>Last usage date:</label>
<input
type="text"
size="50"
class="bpmpi_shipto_lastusagedate"
value="2018-09-06"
/>
</div>
</fieldset>
<!-- dados do device (coleção) -->
<fieldset style="width: 0">
<legend>Device</legend>
<div>
<label>Ip address:</label>
<input
type="text"
size="50"
class="bpmpi_device_ipaddress"
value="200.155.265.12"
/>
</div>
<div>
<label>Fingerprint:</label>
<input
type="text"
size="50"
class="bpmpi_device_1_fingerprint"
value="04003hQUMXGB0poNf94lis1ztuLYRFk+zJ17aP79a9O8mWOBmEnKs6ziAo94ggAtBvKEN6/FI8Vv2QMAyHLnc295s0Nn8akZzRJtHwsEilYx"
/>
</div>
<div>
<label>Provider:</label>
<input
type="text"
size="50"
class="bpmpi_device_1_provider"
value="cardinal"
/>
<!-- ver domínio no manual -->
</div>
</fieldset>
<!-- dados do carrinho (coleção) -->
<table border="1">
<caption>
Cart
</caption>
<thead>
<tr>
<th>Item</th>
<th>Description</th>
<th>Sku</th>
<th>Quantity</th>
<th>Unit Price</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<input
type="text"
class="bpmpi_cart_1_name"
value="ostarine mk-2866"
/>
</td>
<td>
<input
type="text"
class="bpmpi_cart_1_description"
value="Estimula o aumento da massa muscular e da força"
/>
</td>
<td>
<input
type="text"
class="bpmpi_cart_1_sku"
value="10000000000234"
/>
</td>
<td>
<input type="text" class="bpmpi_cart_1_quantity" value="2" />
</td>
<td>
<input type="text" class="bpmpi_cart_1_unitprice" value="450" />
<!-- em centavos -->
</td>
</tr>
<tr>
<td>
<input
type="text"
class="bpmpi_cart_2_name"
value="ostarine mk-2867"
/>
</td>
<td>
<input
type="text"
class="bpmpi_cart_2_description"
value="Estimula mais aumento da massa muscular e da força"
/>
</td>
<td>
<input
type="text"
class="bpmpi_cart_2_sku"
value="10000000000235"
/>
</td>
<td>
<input type="text" class="bpmpi_cart_2_quantity" value="3" />
</td>
<td>
<input type="text" class="bpmpi_cart_2_unitprice" value="550" />
<!-- em centavos -->
</td>
</tr>
</tbody>
</table>
<!-- dados de aérea (coleção de trechos) -->
<table border="1">
<caption>
Travel legs
</caption>
<thead>
<tr>
<th>Carrier</th>
<th>Departure Date</th>
<th>Origin</th>
<th>Destination</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<input
type="text"
class="bpmpi_airline_travelleg_1_carrier"
value="G3"
/>
</td>
<td>
<input
type="text"
class="bpmpi_airline_travelleg_1_departuredate"
value="2018-09-21"
/>
</td>
<td>
<input
type="text"
class="bpmpi_airline_travelleg_1_origin"
value="SDC"
/>
</td>
<td>
<input
type="text"
class="bpmpi_airline_travelleg_1_destination"
value="GIG"
/>
</td>
</tr>
<tr>
<td>
<input
type="text"
class="bpmpi_airline_travelleg_2_carrier"
value="G3"
/>
</td>
<td>
<input
type="text"
class="bpmpi_airline_travelleg_2_departuredate"
value="2018-09-22"
/>
</td>
<td>
<input
type="text"
class="bpmpi_airline_travelleg_2_origin"
value="GIG"
/>
</td>
<td>
<input
type="text"
class="bpmpi_airline_travelleg_2_destination"
value="SDC"
/>
</td>
</tr>
</tbody>
</table>
<!-- dados de passageiros (coleção) -->
<table border="1">
<caption>
Passengers
</caption>
<thead>
<tr>
<th>Name</th>
<th>Ticket Price</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<input
type="text"
class="bpmpi_airline_passenger_1_name"
value="Chuck Norris"
/>
</td>
<td>
<input
type="text"
class="bpmpi_airline_passenger_1_ticketprice"
value="450"
/>
<!-- em centavos -->
</td>
</tr>
<tr>
<td>
<input
type="text"
class="bpmpi_airline_passenger_2_name"
value="Charles Bronson"
/>
</td>
<td>
<input
type="text"
class="bpmpi_airline_passenger_2_ticketprice"
value="550"
/>
<!-- em centavos -->
</td>
</tr>
</tbody>
</table>
<!-- dados de aérea complementares -->
<fieldset style="width: 0">
<legend>Airline Aditional Data</legend>
<div>
<label>Number of passengers:</label>
<input
type="text"
size="50"
class="bpmpi_airline_numberofpassengers"
value="2"
/>
</div>
<div>
<label>Passport Country:</label>
<input
type="text"
size="50"
class="bpmpi_airline_billto_passportcountry"
value="BR"
/>
</div>
<div>
<label>Passport Number:</label>
<input
type="text"
size="50"
class="bpmpi_airline_billto_passportnumber"
value="4849494984911"
/>
</div>
<div>
<label>MDD1:</label>
<input type="text" size="50" class="bpmpi_mdd1" value="mdd1" />
</div>
<div>
<label>MDD2:</label>
<input type="text" size="50" class="bpmpi_mdd2" value="mdd2" />
</div>
<div>
<label>MDD3:</label>
<input type="text" size="50" class="bpmpi_mdd3" value="mdd3" />
</div>
<div>
<label>MDD4:</label>
<input type="text" size="50" class="bpmpi_mdd4" value="mdd4" />
</div>
<div>
<label>MDD5:</label>
<input type="text" size="50" class="bpmpi_mdd5" value="mdd5" />
</div>
</fieldset>
<!-- dados do pedido -->
<fieldset style="width: 0">
<legend>Order</legend>
<div>
<label>Transaction Mode:</label>
<input
type="text"
size="50"
class="bpmpi_transaction_mode"
value="R"
/>
</div>
<div>
<label>Merchant URL:</label>
<input
type="text"
size="50"
class="bpmpi_merchant_url"
value="http://www.loja.com.br"
/>
</div>
<div>
<label>Recurrence:</label>
<input
type="text"
size="50"
class="bpmpi_order_recurrence"
value="false"
/>
</div>
<div>
<label>Product code:</label>
<input
type="text"
size="50"
class="bpmpi_order_productcode"
value="PHY"
/>
<!-- ver domínio no manual -->
</div>
<div>
<label>Last 24 hours count:</label>
<input
type="text"
size="50"
class="bpmpi_order_countlast24hours"
value="1"
/>
</div>
<div>
<label>Last 6 month count:</label>
<input
type="text"
size="50"
class="bpmpi_order_countlast6months"
value="8"
/>
</div>
<div>
<label>Last year count:</label>
<input
type="text"
size="50"
class="bpmpi_order_countlast1year"
value="55"
/>
</div>
<div>
<label>Card attempts on last 24 hours:</label>
<input
type="text"
size="50"
class="bpmpi_order_cardattemptslast24hours"
value="3"
/>
</div>
<div>
<label>Marketing optin:</label>
<input
type="text"
size="50"
class="bpmpi_order_marketingoptin"
value="false"
/>
</div>
<div>
<label>Marketing source:</label>
<input
type="text"
size="50"
class="bpmpi_order_marketingsource"
value="mercadolivre"
/>
</div>
</fieldset>
<!-- dados do usuário/conta -->
<fieldset style="width: 0">
<legend>User account</legend>
<div>
<label>Guest:</label>
<input
type="text"
size="50"
class="bpmpi_useraccount_guest"
value="true"
/>
</div>
<div>
<label>Created date:</label>
<input
type="text"
size="50"
class="bpmpi_useraccount_createddate"
value="2018-08-01"
/>
</div>
<div>
<label>Changed date:</label>
<input
type="text"
size="50"
class="bpmpi_useraccount_changeddate"
value="2018-09-06"
/>
</div>
<div>
<label>Password changed date:</label>
<input
type="text"
size="50"
class="bpmpi_useraccount_passwordchangeddate"
value="2018-09-06"
/>
</div>
<div>
<label>Authentication method:</label>
<input
type="text"
size="50"
class="bpmpi_useraccount_authenticationmethod"
value="02"
/>
<!-- ver domínio no manual -->
</div>
<div>
<label>Authentication protocol:</label>
<input
type="text"
size="50"
class="bpmpi_useraccount_authenticationprotocol"
value="oauth"
/>
</div>
<div>
<label>Authentication timetamp:</label>
<input
type="text"
size="50"
class="bpmpi_useraccount_authenticationtimestamp"
value="201809061510"
/>
</div>
</fieldset>
<input
type="button"
onclick="sendOrder()"
value="Send Order"
id="btnSendOrder"
/>
</div>
</body>
<script type="text/javascript">
var env = getQueryString("env");
function bpmpi_config() {
return {
onReady: function () {
// Evento indicando quando a inicialização do script terminou.
document.getElementById("btnSendOrder").disabled = false;
},
onSuccess: function (e) {
// Cartão elegível para autenticação, e portador autenticou com sucesso.
var cavv = e.Cavv;
var xid = e.Xid;
var eci = e.Eci;
var version = e.Version;
var referenceId = e.ReferenceId;
},
onFailure: function (e) {
// Cartão elegível para autenticação, porém o portador finalizou com falha.
var xid = e.Xid;
var eci = e.Eci;
var version = e.Version;
var referenceId = e.ReferenceId;
},
onUnenrolled: function (e) {
// Cartão não elegível para autenticação (não autenticável).
var xid = e.Xid;
var eci = e.Eci;
var version = e.Version;
var referenceId = e.ReferenceId;
},
onDisabled: function () {
// Loja não requer autenticação do portador (classe "bpmpi_auth" false -> autenticação desabilitada).
},
onError: function (e) {
// Erro no processo de autenticação.
var xid = e.Xid;
var eci = e.Eci;
var returnCode = e.ReturnCode;
var returnMessage = e.ReturnMessage;
var referenceId = e.ReferenceId;
},
onUnsupportedBrand: function (e) {
// Bandeira não suportada para autenticação.
var returnCode = e.ReturnCode;
var returnMessage = e.ReturnMessage;
},
Environment: env ? env : "SDB",
Debug: true,
};
}
function getQueryString(field) {
var href = window.location.href;
var reg = new RegExp("[?&]" + field + "=([^&#]*)", "i");
var string = reg.exec(href);
return string ? string[1] : null;
}
</script>
<script src="/Scripts/BP.Mpi.3ds20.min.js" type="text/javascript"></script>
</html>
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 complementary information for decision-making.
Warning
Submitting a non-authenticated transaction for authorization is allowed; however, the liability in case of chargeback remains with the merchant.
| Event | Description |
|---|---|
onReady | This is triggered when the script is completely loaded, which includes validation of the access token, indicating that the checkout is ready to initiate authentication process |
onSuccess | It is triggered when the card is elegible and the authentication process is successfully finished. In this case, the variables CAVV, XID and ECI are returned. These data must be sent in together with the authorization request. In this scenario, if the transaction is authorized, the liability shift is transferred to the issuer. |
onFailure | It is triggered when the card is elegible but the authentication process failed for some reason. In this case, only ECI variable is returned. If the merchant decide to proceed with the authorization, the ECI must also be sent in 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 | It is triggered when the merchant chooses not to submit the cardholder to the authentication process. ("bpmpi_auth" class set as false). In this scenario, if the transaction is authorized, the liability shift remains with the merchant. |
onError | It is triggered when the authentication process receives a systemic error. In this scenario, if the transaction is authorized, the liability shift remains with the merchant. |
onUnsupportedBrand | It is triggered when the card scheme is not supported by 3DS. |
Input parameters
| Parameter | Description | Type |
|---|---|---|
| Environment | Indicates the environment to be used (Sandbox or Production) | String SDB – Sandbox (test environment) PRD – Production (production environment) |
| Debug | Boolean that identifies if debug mode is activated. When sent as true, the platform will generate the report on the browser's debug mechanism. | Boolean true false |
Important
The JavaScript file must be saved in the server where the merchant application is hosted. To download the file on Sandbox environment, access https://bit.ly/2CSOp2n
Output parameters
| Output | Description | Type | Size |
|---|---|---|---|
Cavv | Authentication signature | Text | - |
Xid | Authentication request identification | Text | - |
Eci | E-commerce indicator code, which represents the authentication result | Numeric | Max 2 |
Version | 3DS version applied in authentication process. Possible values: "2.2.0" or "2.1.0". | Numeric | 5 |
ReferenceId | Authentication request ID | GUID | 36 |
ReturnCode | Authentication return code | Alphanumeric | Max 5 |
ReturnMessage | Authentication result message | Alphanumeric | Variable |
Examples for script output
Example for event OnSuccess
OnSuccess{
Cavv: 'Y2FyZGluYWxjb21tZXJjZWF1dGg=',
Xid: null,
Eci: '01',
Version: '2.2.0',
ReferenceId: '973cf83d-b378-43d5-84b6-ce1531475f2a'
}
Example for event OnFailure
OnFailure{
Xid: null,
Eci: null,
ReturnCode: '231',
ReturnMessage: 'Unexpected error ocurred',
ReferenceId: null
}
Example when card brand is not supported for authentication
When the 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
}
Check possible values for ReturnCode in 3DS return codes.
Updated about 2 months ago