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.
On this page
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.
Migrate your existing Masterpass code
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
To use Secure Remote Commerce with SqPaymentForm, the following must be true:
You are using HTTPS. SRC payments can be tested with
SqPaymentFormon 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
SqPaymentFormwith Secure Remote Commerce and does not give instructions for the setup ofSqPaymentForm.
Step 1: Add the Secure Remote Commerce placeholder to your payment page
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
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
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'
},
...
});
Set the background image URL of the Secure Remote Commerce button by setting the value of
masterpassBtn.style.backgroundImageto 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); } },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
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
}
]
},
...
}
});