Add the Apple Pay on the Web Button
Warning
The Square payment form is deprecated. Use the Web Payments SDK to take payments on a web client.
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 in both 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.
Important
If you are developing on a MacBook Pro, it might be necessary to activate Apple Pay and Touch ID, and then restart Safari.
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:
Open the Developer Dashboard.
Select the application associated with your
SqPaymentFormimplementation.At the top of the page, choose Sandbox mode.
In the navigation pane, choose Apple Pay for the selected application.
Choose the Add Sandbox Domain link and follow the instructions.
Note
Because Square generates domain validation with Apple Pay when the payment page loads, you do not need to create an Apple Merchant ID or call the Apple APIs to enable the functionality.
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
Important
To test an application in the Square Sandbox, go to the Developer Dashboard and set the dashboard to the Sandbox 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 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.
Copy the
methodsSupportedfunction 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 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.
// 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 () {
var paymentRequestJson = {
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
}
],
shippingOptions: [
{
id: "1",
label: "SHIPPING LABEL",
amount: "SHIPPING COST"
}
]
};
return paymentRequestJson;
}
});
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.
Important
Apple does not allow 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 Square Sandbox.
Testing your Apple Pay integration involves the following steps:
Open your payment page in a Safari browser and verify that the Apple Pay button renders as shown:
Choose the Apple Pay button and complete the payment sheet that opens.
Verify that you are receiving a payment token in the
cardNonceResponseReceivedcallback.
The payment token 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:
Register a domain for Apple Pay in production:
Open the Developer Dashboard.
Select the application associated with your
SqPaymentFormimplementation.At the top of the page, choose Production mode.
In the navigation pane, choose Apple Pay for the selected application.
Choose the Add Domain link and follow the instructions.
Change your payment page script tag that references the payment form library to the following:
https://js.squareup.com/v2/paymentformReplace the Sandbox application ID and location ID in your payment page JavaScript with your production application ID and location ID. You can also get a production location ID from the Square Developer Dashboard Locations page for a Square account.