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 example

This JSON object is an example of an object that conforms to the payment request interface

          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"
          currencyCode: "USD",
          countryCode: "US",
          total: {
            label: "MERCHANT NAME",
            amount: "1130.00",
            pending: false
          lineItems: [
              label: "Subtotal",
              amount: "1000.00",
              pending: false
              label: "Shipping",
              amount: "49.99",
              pending: true
              label: "Tax",
              amount: "80.01",
              pending: false

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 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.

Optional: Disable the Apple Pay button

You may want to disable the Apple Pay 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.

Optional: Programmatically register multiple domains

You can use our RegisterDomain endpoint to activate multiple domains and subdomains.

Bulk registering domains can save you time if you are using SqPaymentForm as a part of a platform where payments are processed on multiple subdomains. For example, you might be building a shop platform (platform.com), where users can create their own shops and take payments ( shoes.platform.com, plants.platform.com). All of these individual subdomains need to be registered to enable Web Apple Pay with Square.

To programmatically register a client domain:

  1. Download Square's copy of Apple's merchant domain verification file.
  2. Host the verification file at: https://{{CLIENT DOMAIN}}/.well-known/apple-developer-merchantid-domain-association
  3. Use the RegisterDomain endpoint of Square's ApplePay API to register and validate the domain. Here's an example using our PHP SDKs.
//Replace with your access token and domain name.
$accessToken = '{REPLACE_ME}';
$domain = '{REPLACE_ME}';

// Include the Square Connect API resources
require_once(__DIR__ . '/local/path/to/Square/Connect/SDK/autoload.php');

// Create and configure a new API client object
$defaultApiConfig = new \SquareConnect\Configuration();

$defaultApiClient = new \SquareConnect\ApiClient($defaultApiConfig);
$apiInstance = new SquareConnect\Api\ApplePayApi($defaultApiClient);

// Create a request object.
$request = new \SquareConnect\Model\RegisterDomainRequest();
// Set the domain field in the request object.
// Send the request. This will print the results for testing purposes.
try {
    $result = $apiInstance->registerDomain($request);
catch (Exception $e) {
    echo 'Exception when calling the RegisterDomain endpoint ',
    $e->getMessage(), PHP_EOL;

Or you can use a cURL command:

curl https://connect.squareup.com/v2/apple-pay/domains  \
  -H 'Authorization: Bearer {ACCESS_TOKEN}'             \
  -H 'Content-Type: application/json'                   \
  -d '{ "domain_name" : "{{CLIENT DOMAIN}}" }'
< Digital Wallet Setup Guides
Take a payment >

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