Deprecated
This component is deprecated. See below for guidance about what to use instead.
Square Payment Form: Add Digital Wallets

Add a Secure Remote Commerce Button

Warning

The "Square Payment Form" is deprecated. Please use the Web Payments SDK to take payments on a web client.

This guide provides step-by-step instructions for enabling Masterpass (now Mastercard Click to Pay) with the Square payment form object (SqPaymentForm) using Secure Remote Commerce.

Note

The names of SqPaymentForm Secure Remote Commerce (SRC) objects have not changed from the original Masterpass to minimize the amount of recoding that you must do to support SRC.

After completing the steps in this guide, your payment form includes a Mastercard Click to pay button like the following example.

NewMasterpass

Migrate your existing Masterpass code Permalink Get a link to this section

The Secure Remote Commerce background image is set by calling the SqPaymentForm.masterpassImageUrl function.

If your application uses a CSS class property to set the Secure Remote Commerce button background image, you should migrate your application to use the masterpassImageUrl function. To migrate your code, complete step 2 and step 4.

Prerequisites and assumptions Permalink Get a link to this section

To use Secure Remote Commerce with SqPaymentForm, the following must be true:

  • You are using HTTPS. SRC payments can be tested with SqPaymentForm on localhost without using HTTPS, but you must use HTTPS to accept payments in production.

  • Secure Remote Commerce is only available for Square accounts based in Canada, the United Kingdom and the United States.

This guide also makes the following assumptions:

  • You have read the introductory review of this API.

  • You have followed the required steps in the Payment Form Setup Guide. This guide focuses specifically on customizing SqPaymentForm with Secure Remote Commerce and does not give instructions for the setup of SqPaymentForm.

Step 1: Add the Secure Remote Commerce placeholder to your payment page Permalink Get a link to this section

If you are using the payment form with digital wallet support templates, the Secure Remote Commerce placeholder is included by default.

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

Step 2: Customize the Secure Remote Commerce button size Permalink Get a link to this section

Mastercard provides a range of image resources to choose from if you want to customize the Secure Remote Commerce button.

Add the button-src class to the mysqpaymentform.css file if it is not present.

Note

If you are migrating your code to use the masterpassImageUrl function, remove the background-image property from the button-masterpass class.

/* Indicates how SRC button will appear */
.button-src {
  min-width: 200px;
  min-height: 40px;
  max-height: 40px;
  padding: 0;
  margin: 10px;
  background-color: black;
  background-size: 100% 100%;
  background-repeat: no-repeat;
  background-position: 50% 50%;
  border-radius: 5px;
  border-color: rgb(255, 255, 255);
  cursor:pointer;
  display: none;
}

Step 3: Enable Secure Remote Commerce in the SqPaymentForm object Permalink Get a link to this section

Enable the Secure Remote Commerce 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 Secure Remote Commerce parameter is enabled by default.

// Create and initialize a payment form object
var paymentForm = new SqPaymentForm({

  ...

  // Initialize Masterpass placeholder ID
  masterpass: {
    elementId: 'sq-src'
  },

  ...
});

Step 4: Update the methodsSupported callback function Permalink Get a link to this section

  1. Make the Secure Remote Commerce button visible by adding code to set the style.display to inline-block.

  1. Set the background image URL of the Secure Remote Commerce button by setting the value of masterpassBtn.style.backgroundImage to the URL returned by the masterpassImageUrl function.

    
      methodsSupported(methods, unsupportedReason) {
        console.log(methods);
        const srcBtn = document.getElementById('sq-src');
    
        // Only show the button if src is enabled
        if (methods.masterpass === true) {
          srcBtn.style.display = 'inline-block';
          //Set button background image provided by the masterpassImageUrl function
          srcBtn.style.backgroundImage   =`url(${paymentForm.masterpassImageUrl()})`
        } else {
          console.log(unsupportedReason);
        }
      },
    
  2. Delete the HTML for the visual placeholder (if it exists):

    <div id="sq-src-label" class="wallet-not-enabled">SRC not enabled</div>
    

Step 5: Customize the createPaymentRequest callback function Permalink Get a link to this section

To process payments, you 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.

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 more information about the expected structure of a payment request object, see sqPaymentForm Object Model.

// Create and initialize a payment form object
var paymentForm = new SqPaymentForm({

  ...

  // SqPaymentForm callback functions
  callbacks: {

    ...

    /*
     * callback function: createPaymentRequest
     * Triggered when: a digital wallet payment button is clicked.
     */
    /*
     * callback function: createPayment Request
     * Triggered when: a digital wallet payment button is clicked.
     */
   createPaymentRequest: function () {
      return {
        requestShippingAddress: true,
        requestBillingInfo: true,
        shippingContact: {
          familyName: "CUSTOMER LAST NAME",
          givenName: "CUSTOMER FIRST NAME",
          email: "mycustomer@example.com",
          country: "USA",
          region: "CA",
          city: "San Francisco",
          addressLines: [
            "1455 Market St #600"
          ],
          postalCode: "94103",
          phone:"14255551212"
        },
        currencyCode: "USD",
        countryCode: "US",
        total: {
          label: "MERCHANT NAME",
          amount: "85.00",
          pending: false
        },
        lineItems: [
          {
            label: "Subtotal",
            amount: "60.00",
            pending: false
          },
          {
            label: "Shipping",
            amount: "19.50",
            pending: true
          },
          {
            label: "Tax",
            amount: "5.50",
            pending: false
          }
        ]
      },

    ...
  }
});