Add the Apple Pay on the Web Button

This guide provides step-by-step instructions for enabling Apple Pay on the Web with the Square payment form object (SqPaymentForm). After completing the following steps, your payment form includes an Apple Pay button.

Prerequisites and assumptions

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

• Apple Pay is supported on Apple Safari browsers.

• You are using HTTPS and have a Square account. Apple Pay payments cannot be tested with HTTP or from localhost.

• You use the payment form in a Safari browser that is:

  • 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 have a MacBook Pro with Touch ID.

• Apple Pay 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 followed the required steps in Walkthrough: Integrate Square Payments in a Website.

• You are not integrating Apple Pay with the single-element payment form (beta).

• You test your Apple Pay integration in the Square Sandbox.

Step 1: Configure a payment form for the Sandbox

In index.html, set the SqPaymentForm reference URL to:

<script type="text/javascript" src="https://js.squareupsandbox.com/v2/paymentform">
</script>

Step 2: Register your Sandbox domain with Apple

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

To register a Sandbox domain for Apple Pay in the Square Sandbox:

Step 3: Add a style class for the Apple Pay button

In your CSS file, add a class that sets the dimensions, background color, and background image for the Apple Pay button. The following class conforms to the requirements of Apple:

/* Customize the Apple Pay on the Web button */
/* CSS */
@supports (-webkit-appearance: -apple-pay-button) { 
    .apple-pay-button {
        display: inline-block;
        -webkit-appearance: -apple-pay-button;
    }
    .apple-pay-button-black {
        -apple-pay-button-style: black;
    }
    .apple-pay-button-white {
        -apple-pay-button-style: white;
    }
    .apple-pay-button-white-with-line {
        -apple-pay-button-style: white-outline;
    }
}

@supports not (-webkit-appearance: -apple-pay-button) {
    .apple-pay-button {
        display: inline-block;
        background-size: 100% 60%;
        background-repeat: no-repeat;
        background-position: 50% 50%;
        border-radius: 5px;
        padding: 0px;
        box-sizing: border-box;
        min-width: 200px;
        min-height: 32px;
        max-height: 64px;
    }
    .apple-pay-button-black {
        background-image: -webkit-named-image(apple-pay-logo-white);
        background-color: black;
    }
    .apple-pay-button-white {
        background-image: -webkit-named-image(apple-pay-logo-black);
        background-color: white;
    }
    .apple-pay-button-white-with-line {
        background-image: -webkit-named-image(apple-pay-logo-black);
        background-color: white;
        border: .5px solid black;
    } 
}

For more information about customizing the Apple Pay button, see Displaying Apple Pay Buttons.

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

In index.html, add a button element for Apple Pay:

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

Step 5: Configure the SqPaymentForm object

Step 6: Update the methodsSupported callback function

The methodsSupported callback function provides a place for your application to react to the availability of Apple Pay for the buyer. When Apple Pay is supported, your application must display the Apple Pay button and hide any label you might be showing in place of the button.

Step 7: 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:

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

Test Apple Pay and put into production

To test your Apple Pay integration, you must register a valid credit card in your Apple Pay Wallet.

Testing your Apple Pay integration involves the following steps:

The nonce generated for Apple Pay can be used to take a payment with the Payments API in the Sandbox environment.

Production configuration

When your application is ready for production, do the following: