Square Payment Form: Add Digital Wallets

Add the Masterpass Button

Enable Masterpass functionality in the Square payment form.

Mobile Web
Client Side

This document provides step-by-step instructions for enabling Masterpass with the Square payment form object (SqPaymentForm).

When you have completed the steps in this guide, your payment form will include a button like this button.

The Masterpass digital wallet button


This guide makes the following assumptions:

  • You have read the Payment Form Overview article. Enable Masterpass is a how-to guide and does not cover general functionality of the payment form.
  • You have followed the required steps from the Payment Form Setup Guide. This guide focuses specifically on customizing SqPaymentForm with Masterpass and does not general setup for SqPaymentForm.


To use Masterpass with SqPaymentForm, the following must be true:

  • You are using HTTPS. Masterpass payments may be tested with SqPaymentForm on localhost without using HTTPS, but you must use HTTPS to accept payments in production.
  • Masterpass is only available for Square accounts based in the United States.

Step 1: Add the Masterpass placeholder to your payment page

If you are using the Payment form with digital wallet support templates, the Masterpass placeholder is included by default.

<button id="sq-masterpass" class="button-masterpass"></button>

Step 2: Customize the Masterpass button size

Mastercard provides a range of image resources to choose from if you would like to customize the Masterpass button.

  1. Visit the Mastercard Developers Digital Assets page and copy the URL of the button you want to use. Then update your CSS file with the new background image URL and dimensions for min-width, min-height, and max-height:

    If you are using the Payment form with digital wallet support templates, the Masterpass button CSS class is already present and configured to be 147 pixels x 34 pixels.

2 Add the button.masterpass class to the sqpaymentform.css file if it is not present.

 1/* Indicates how Masterpass button will appear */
 2.button-masterpass {
 3  min-width: 200px;
 4  min-height: 40px;
 5  max-height: 40px;
 6  padding: 0;
 7  margin: 10px;
 8  background-image: url(https://static.masterpass.com/dyn/img/btn/global/mp_chk_btn_147x034px.svg);
 9  background-color: black;
10  background-size: 100% 100%;
11  background-repeat: no-repeat;
12  background-position: 50% 50%;
13  border-radius: 5px;
14  border-color: rgb(255, 255, 255);
15  cursor:pointer;
16  display: none;

Step 3: Enable Masterpass in the SqPaymentForm Object

Enable the Masterpass parameter by initializing it with the HTML placeholder ID you set in the previous step:

If you are using the Payment form with digital wallet support template, the Masterpass parameter is enabled by default.

 1// Create and initialize a payment form object
 2var paymentForm = new SqPaymentForm({
 4  ...
 6  // Initialize Masterpass placeholder ID
 7  masterpass: {
 8    elementId: 'sq-masterpass'
 9  },
11  ...

Step 4: Update the methodsSupported callback function

  1. Delete references to the visual placeholder, masterpassLabel in methodsSupported:

    The Payment form with digital wallet support template includes a visual placeholder for Masterpass that is set by the methodsSupported callback to simplify development and testing. This functionality should be removed before putting the payment form in production.

 2  methodsSupported: function (methods) {
 3    ...
 4    var masterpassLabel = document.getElementById('sq-masterpass-label');
 5    var masterpassBtn = document.getElementById('sq-masterpass');
 7    if (methods.masterpass === true) {
 8      masterpassBtn.style.display = 'inline-block';
 9      masterpassLabel.style.display = 'none';
10    }
11  },
  1. Delete the HTML for the visual placeholder (if it exists):
<div id="sq-masterpass-label" class="wallet-not-enabled">Masterpass not enabled</div>

Removing the HTML placeholder without updating the methodsSupported function will cause a JavaScript error.

Step 5: Customize the createPaymentRequest callback function

To process payments, you will need to customize the createPaymentRequest callback function to create a JSON block that defines a payment request object based on the customer's purchase totals:

 1// Create and initialize a payment form object
 2var paymentForm = new SqPaymentForm({
 4  ...
 6  // SqPaymentForm callback functions
 7  callbacks: {
 9    ...
11    /*
12     * callback function: createPaymentRequest
13     * Triggered when: a digital wallet payment button is clicked.
14     */
15    /*
16     * callback function: createPayment Request
17     * Triggered when: a digital wallet payment button is clicked.
18     */
19   createPaymentRequest: function () {
20      return {
21        requestShippingAddress: true,
22        requestBillingInfo: true,
23        shippingContact: {
24          familyName: "CUSTOMER LAST NAME",
25          givenName: "CUSTOMER FIRST NAME",
26          email: "mycustomer@example.com",
27          country: "USA",
28          region: "CA",
29          city: "San Francisco",
30          addressLines: [
31            "1455 Market St #600"
32          ],
33          postalCode: "94103",
34          phone:"14255551212"
35        },
36        currencyCode: "USD",
37        countryCode: "US",
38        total: {
39          label: "MERCHANT NAME",
40          amount: "85.00",
41          pending: false
42        },
43        lineItems: [
44          {
45            label: "Subtotal",
46            amount: "60.00",
47            pending: false
48          },
49          {
50            label: "Shipping",
51            amount: "19.50",
52            pending: true
53          },
54          {
55            label: "Tax",
56            amount: "5.50",
57            pending: false
58          }
59        ]
60      },
62    ...
63  }

Digital wallet services expect payment requests in a specific format. The result is that the object created in createPaymentRequest is functionally different from Square's internal data types. For example, monetary amounts are provided as floats rather than integers.

For details on the expected structure of a payment request object, see sqPaymentForm PaymentRequest Objects.

Optional: Disable the Masterpass button

You may want to disable the Masterpass button temporarily. Maybe you want to enable or disable the button based on a runtime condition. In either case, you probably want to leave all of the button configuration code in place so that you can enable or disable a digital wallet button with a few lines of JavaScript.

< Digital Wallet Setup Guides
Take a payment >

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow