Add the Apple Pay on the Web Button
This document provides step-by-step instructions for enabling Apple Pay on the Web with the Square payment form object (SqPaymentForm). When you have completed the steps in this guide, your payment form will include an Apple Pay button like the one below:
Process overview
Prerequisites and assumptions
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:
Apple Pay for the Web is supported on Apple Safari Browsers.
You are using HTTPS and have a Square account. Web Apple Pay payments cannot be tested with HTTP or from
localhost.You will use the payment form in a Safari browser and:
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.
This guide also makes the following assumptions:
You have followed the required steps from Walkthrough: Integrate Square Payments In a Website.
You are not integrating Apple Pay with the Single-element payment form (beta)
You will test your Apple Pay integration in v2 Sandbox.
Important
If you are developing on a MacBook Pro, it may be necessary to activate Apple Pay and Touch ID then restart Safari to pick up the changes.
Step 2: Register your sandbox 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 sandbox domain for Web Apple Pay in v2 Sandbox:
Open the Application Dashboard.
Select the application associated with your SqPaymentForm implementation.
Set the Application Dashboard to Sandbox Settings mode.
Click on the Apple Pay tab for the selected application.
Click on the "Add Sandbox Domain" link and follow the onscreen instructions.
Note
Square triggers domain validation with Apple Pay when the payment page loads, so you do not need to create an Apple Merchant ID or call Apple's APIs to enable the functionality.
Step 4: Configure the SqPaymentForm object
Important
For testing an app in the v2 Sandbox: In your app Application Dashboard, set the dashboard to Sandbox Settings mode before completing the following instructions in this step.
Copy your Application ID from the Credentials page.
Copy a location ID from the Locations page.
Enable the
applePayconfiguration field by initializing it with the HTML placeholder ID (sq-apple-pay) you set in the previous step.
// Create and initialize a payment form object
var paymentForm = new SqPaymentForm({
applicationId: "REPLACE_WITH_APPLICATION_ID",
locationId: "REPLACE_WITH_LOCATION_ID",
...
// Initialize Web Apple Pay placeholder ID
applePay: {
elementId: 'sq-apple-pay'
},
...
});
Step 5: Update the methodsSupported callback function
The methodsSupported callback function provides a place for your app to react to the availability of Apple Pay for the buyer. When Apple Pay is supported, your app must display the Apple Pay button and hide any label you may be showing in place of the button.
Copy the methodsSupported function into the payment form initialization block inside of the callbacks configuration field.
methodsSupported: function (methods, unsupportedReason) {
console.log(methods);
var applePayBtn = document.getElementById('sq-apple-pay');
// Only show the button if Apple Pay on the Web is enabled
// Otherwise, display the wallet not enabled message.
if (methods.applePay === true) {
applePayBtn.style.display = 'inline-block';
} else {
console.log(unsupportedReason);
}
}
,
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>
Step 6: 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:
// Create and initialize a payment form object
var paymentForm = new SqPaymentForm({
...
// SqPaymentForm callback functions
callbacks: {
...
/*
* callback function: createPayment Request
* Triggered when: a digital wallet payment button is clicked.
* returns a PaymentRequestObject from your custom helper function
*/
createPaymentRequest: function () {
//a PaymentRequestObject is returned from this
//helper
return myCreatePaymentRequestHelperFunction();
}
});
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.
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.
Important
Apple does not allow v2 Sandbox Test credit card values . You must use a valid credit card from your Apple Pay Wallet. The card is not charged for test payments as long as you are testing in the v2 Sandbox.
Testing your Apple Pay integration involves the following steps:
Open your payment page in a Safari browser and verify the Apple Pay button renders like the following button:
Click the Apple Pay button and complete the payment sheet that opens
Verify that you are receiving a nonce in the
cardNonceResponseReceivedcallback.
The nonce generated for Apple Pay can be used to take a payment with the Payments API in the v2 Sandbox environment.
Production configuration
When your app is ready for production, do the following:
Register a domain for Web Apple Pay in production :
Open the Application Dashboard.
Select the application associated with your SqPaymentForm implementation.
Set the Application Dashboard to Production Settings mode.
Click on the Apple Pay tab for the selected application.
Click on the "Add Domain" link and follow the onscreen instructions.
Change your payment page script tag that references the payment form library to:
https://js.squareup.com/v2/paymentformReplace the sandbox application ID and location ID in your payment page JavaScript with production application and location IDs. Note: You can also get a production location ID in the Square Dashboard Locations page for a Square Account.