Getting Started

Guides

Reference

Plugins

Masterpass

What is Masterpass?

Masterpass provides an alternative for the data of the client's card to be safely provided to Openpay when making a payment.

We provide to you our integration guide, which will simplify the use of the Masterpass Javascript library, to integrate with the Openpay credit / debit card payment methods.

Documentation.

Request here for detailed information about Masterpass.

Behavior.

There are two possible flows for the customer to select a card in Masterpass:

Through Ajax, using the Lightbox modal interface.
Or directly in Masterpass by Redirecting.

Ajax flow (Lightbox).

The customer presses the Masterpass button on the web site.
The event that was previously initialized in the function OpenpayMasterpass.configureButton
Openpay returns the authentication result of your site.
The card selection process is initialized in the modal “Masterpass lightbox”.
The customer selects the card.
Masterpass sends the result of the selection to Openpay
Openpay gets the selected card.
Masterpass returns the information of the card.
Openpay stores the information of the card and returns the token.
The payment confirmation dialog is displayed.
Customer confirms payment.
The charge request with the token is sent to Openpay.

Redirect flow.

The customer presses the Masterpass button on the web site.
The event that was previously initialized in the function OpenpayMasterpass.configureButton
Openpay returns the authentication result of your site.
The user is redirected to Masterpass.
The customer selects the card.
Masterpass redirects the user to the Url configured in the function OpenpayMasterpass.configureButton
The OpenpayMasterpass.getCheckoutDatafunction is launched, which sends to Openpay the information obtained from Masterpass in the previous step.
Openpay gets the selected card.
Masterpass returns the information of the card.
Openpay stores the information of the card and returns the token.
The payment confirmation dialog is displayed.
Customer confirms payment.
The charge request con token hacia Openpay

Integration.

To use the library for Openpay Masterpass follow the following steps:

Requirements and dependencies.

To use Masterpass is required include:

JQuery 1.10.2 o later (Masterpass.js Dependency)
Masterpass.js
Openpay.js
Create a test account at Masterpass

1) Add the JQuery library.

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>

2) Add the Masterpass library.

For testing use:

<script type="text/javascript" src="https://sandbox.static.masterpass.com/dyn/js/switch/integration/MasterPass.client.js"></script>

For production use:

<script type="text/javascript" src="https://static.masterpass.com/dyn/js/switch/integration/MasterPass.client.js"></script>

3) Add the Openpay library.

<script type='text/javascript' src="https://js.openpay.mx/openpay.v1.min.js"></script>

4) Add the js library from Openpay for Masterpass.

<script type="text/javascript" src="${yourContextPath}/js/openpay/masterpass/openpay-masterpass.js"></script>

Masterpass Button Configuration.

Configure your Openpay Api keys.

OpenPay.setId('mYourMerchantId');
OpenPay.setApiKey('pk_yourPublicKey');
OpenPay.setSandboxMode(true);// set false to go production

Add the Masterpass button with one of the Available Designs.
Also add the link "Learn more" which must be dynamic, using the Available links depending on the language and country of the user.

<div class="MasterPassBtnExample">
<a href="#"> <img src="https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_180x042px.png"></a>
</div>
<a href="https://www.mastercard.com/mc_us/wallet/learnmore/es/MX/">Learn More</a>

Add the configuration event for the button.

OpenpayMasterpass.configureButton(".MasterPassBtnExample a", {
      originUrl : 'https://myWebApp/demo/masterpass/main',
      callbackUrl : 'https://myWebApp/demo/masterpass/main',
      enableShippingAddress : true,
      successCallback : yourSuccessConfigureButtonCallback, // See an example below...
      failureCallback : yourFailureCallback,
      cancelCallback : yourCancelCallback,
      shoppingCart : {//Shopping cart
        currency: "MXN",  //Currency
        subtotal: "123.00",  //Total Amount
        items: [ //Optionally an array of items
          {
            description : "Pen", //Some description
            quantity : 2,
            value : "100.00", //Amount
            imageUrl : "https://cdn.pixabay.com/photo/2012/04/13/17/57/pen-33077_960_720.png" //Some image url
          },
          {
            description : "Pencil",
            quantity : 1,
            value : "23.00",
            imageUrl : "http://i50.twenga.com/suministros/lapiz/lapices-staedtler-noris-hb-tp_3981652568322654320f.jpg"
          }
        ]
      }
});

Parameter

Description

Required

originUrl

Url where the request is generated

No

callbackUrl

Masterpass will add the authentication parameters to this Url, which will be used to redirect the client after selecting a card. You must perform the Redirect Management to obtain the authentication parameters and make the request to Openpay using the function OpenpayMasterpass.getCheckoutData

Yes

enableShippingAddress

Indicator to enable delivery address selection

Yes

successCallback

This function will be launched when Masterpass successfully responds for the Ajax flow.

Yes

cancelCallback

Function that will be launched when the user cancels the card selection

Yes

failureCallback

Function to be thrown if Masterpass responds with error code

Yes

shoppingCart

Object related to the current purchase

No

shoppingCart object parameters:

Parameter

Description

Required

currency

Currency with which the transaction will be processed

Yes

subtotal

Total purchase price

Yes

items

Shopping Cart products array

No

Parameters of the object inside the array items:

Parameter

Description

Required

description

Description of the product

Yes

quantity

Number of products

Yes

value

Unit price

Yes

imageUrl

Url of the image of the product

No

OpenpayMasterpass.getCheckoutData function

The OpenpayMasterpass.getCheckoutData function is used to send the Masterpass response after the client selects a card.

OpenpayMasterpass.getCheckoutData parameters

Parameter

Description

Required

masterpassResponse

Answer returned by Masterpass which will be interpreted by Openpay

Yes

successCheckoutCallback

Function which will be launched when Openpay obtains the data of the card through Masterpass

Yes

failureCheckoutCallback

Function that will be executed if Openpay fails to obtain the data of the client card

Yes

Response handling by Ajax (Lightbox)

Adds the following function to handle the Masterpass response in case the lightbox mode is invoked, it must be passed to the parameter successCallback in the function OpenpayMasterpass.configureButton:

var successCallback = function(masterpassResponse) {
  OpenpayMasterpass.getCheckoutData(
    masterpassResponse, //this is required
    successCheckoutCallback, //You must implement this. See an example below...
    failureCheckoutCallback  //And this too!
  );
};

The previous function will be executed when confirming the selection of card in the modal "Lightbox":

Redirect response handling

You must take into account that masterpass could redirect to the user, so you must implement the following block of code which handles the masterpass response.

You can test this flow in sandbox omitting the parameter originUrl passed in the function object OpenpayMasterpass.configureButton

The attributes of the masterpassResponse object will be returned inside the URL when the user is redirected.

Function SuccessCheckoutCallBack

The SuccessCheckoutCallBack function is an example of how to handle the successful response of the function OpenpayMasterpass.getCheckoutData

  var successCheckoutCallback = function(response) {
  var data = response.data;
  console.log('DATA:');
  console.log(data);
  $("#tokenCard").val(data.id);//this is your openpay Token card to use in the charge request for Openpay
  var card = data.card;
  console.log(data.card);
  $("#holderName").text(card.holder_name);
  $("#cardNumber").text(card.card_number);
  $("#expirationDate").text(card.expiration_month + '/' +card.expiration_year);
  var customer = data.customer;
  $("#customerName").text(customer.name);
  $("#customerEmail").text(customer.email);
  $("#customerLastName").text(customer.last_name);
  $("#customerPhone").text(customer.phone_number);
  var sa = data.shipping_address;
  if (sa) {
    $("#postalCode").text(sa.postal_code);
    $("#country").text(sa.country_code);
    $("#saPhone").text(sa.phone_number);
    $("#recipient").text(sa.recipient);
    $("#line1").text(sa.line1);
    $("#line2").text(sa.line2);
    $("#line3").text(sa.line3);
    $("#state").text(sa.state);
    $("#city").text(sa.city);
  }
};

Openpay object response parameters

Parameter

Description

response.data.id

Token of the card which must be used in the charge request.

response.data.card

Card object. (Masked Card Number)

response.data.customer

Object with customer information

response.data.customer.name

Customer name

response.data.customer.last_name

Customer last name

response.data.customer.email

Customer E-mail

response.data.customer.phone_number

Customer's telephone number

data.shipping_address

Object with shipping address information

data.shipping_address.phone_number

Home phone number

data.shipping_address.line1

Address line 1

data.shipping_address.line2

Address line 2

data.shipping_address.line3

Address line 3

data.shipping_address.state

State

data.shipping_address.city

City

data.shipping_address.postal_code

Postal code

data.shipping_address.country_code

Country code

Demo.

In our Demo you can test and analyze the implementation of Masterpass described here: