Square Payment Form: Add Digital Wallets

Add the Apple Pay on the Web Button

Enable Apple Pay on the Web in the Square Payment Form.

Mobile Web
Client Side

This document provides step-by-step instructions for enabling Apple Pay on the Web with the Square payment form object (SqPaymentForm).

You may be able to try out the Apple Pay button right here. Since this is a demo, you will not be charged.

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

Apple pay mark rgb small 052318
The ApplePay digital wallet button


This guide makes the following assumptions:

  • You have read the Payment form Overview. Enable Apple Pay on the Web 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 payment form with Apple Pay and does not general setup for payment form.


The Square payment form adheres to Apple's development requirements for Web Apple Pay. To use Web Apple Pay with payment form, the following must be true:

  • You are using HTTPS and a production Square account. Web Apple Pay payments cannot be tested with HTTP, from localhost, or with Square Sandbox credentials.
  • You will use the payment form in a supported client:
    • iOS 10 and later — Apple Pay JavaScript is supported on all iOS devices with a Secure Element. It is supported both in Safari and SFSafariViewController objects.
    • MacOS 10.12 and later — Apple Pay JavaScript is supported in Safari. The user must have an iPhone or Apple Watch to authorize the payment, or a MacBook Pro with Touch ID.
  • Apple Pay on the Web is only available for Square accounts based in the United States.

Step 1: Register your domain with Apple

By registering your domain to use Web Apple Pay and the Apple Pay Platform, you agree to the Apple Pay Platform Web Merchant Terms and Conditions.

To register a domain for Web Apple Pay:

  1. Open the Application Dashboard.
  2. Select the application associated with your SqPaymentForm implementation.
  3. Click on the Apple Pay tab for the selected application.
  4. Click on the "Add a new domain" link and follow the onscreen instructions.

To programmatically register multiple domains at once, use the RegisterDomain endpoint of the ApplePay API.

Step 2: Add the Apple Pay placeholder to your payment page

Add the following HTML to your payment page:

  <button id="sq-apple-pay" class="button-apple-pay"></button>

If you are using the payment form with digital wallet support, the Apple Pay placeholder is included by default.

To make your testing easier, the digital wallet support templates include the <div> highlighted in the 3rd line. This div is rendered when SqPaymentForm cannot replace the Apple Pay button when Apple Pay on the Web is not enabled for your web app.

1  <div id="sq-walletbox">
2    Pay with a digital wallet
3    <div id="sq-apple-pay-label" class="wallet-not-enabled">Apple Pay on the Web not enabled</div>
4    <!-- Placeholder for Apple Pay on the Web button -->
5    <button id="sq-apple-pay" class="button-apple-pay"></button>
6  </div>

If desired, you can also modify the Apple Pay on the Web CSS class the Apple Pay button as long as those changes are in line with Apple's Human Interface Guidelines.

Step 3: Enable the Apple Pay parameter in the SqPaymentForm object

Enable the Apple Pay 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, the Apple Pay parameter is enabled by default.

 1// Create and initialize a payment form object
 2var paymentForm = new SqPaymentForm({
 4  // Initialize the payment form elements
 5  applicationId: applicationId,
 6  locationId: locationId,
 7  inputClass: 'sq-input',
 9  ...
11  // Initialize Web Apple Pay placeholder ID
12  applePay: {
13    elementId: 'sq-apple-pay'
14  },
15  ...

Step 4: Update the methodsSupported callback function

Delete references to the visual placeholder, applePayLabel in methodsSupported:

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

 1    methodsSupported: function (methods) {
 3      ...
 4      var applePayLabel = document.getElementById('sq-apple-pay-label');
 6      if (methods.applePay === true) {
 7        applePayBtn.style.display = 'inline-block';
 8        applePayLabel.style.display = 'none' ;
 9      }
10      ...
11    },

Then delete the HTML for the visual placeholder (if it exists):

<div id="sq-apple-pay-label" class="wallet-not-enabled">Apple Pay 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: createPayment Request
13     * Triggered when: a digital wallet payment button is clicked.
14     * returns a PaymentRequestObject from your custom helper function
15     */
16   createPaymentRequest: function () {
18     //a PaymentRequestObject is returned from this
19     //helper
20     return myCreatePaymentRequestHelperFunction();
21  }

Payment request object format

Digital wallet services expect payment requests in a specific format. The result is that the object created in createPaymentRequest is functionally different from internal Square data types. For example, monetary amounts are provided as strings rather than integers. One thousand dollars US is represented by the string "1000.00"

For details on the expected structure of a payment request object, see sqPaymentForm PaymentRequest Objects in the Payment Form Technical Reference.

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