Learn how to take Apple Pay payments in a web client with the Web Payments SDK.
Web Payments SDK

Take an Apple Pay Payment

Learn how to add Apple Pay to the application you built in Take a Card Payment with the Web Payments SDK, using the Quickstart project sample. To see whether digital wallets are supported in your country, see Supported Payment Methods by Country.

Overview Permalink Get a link to this section

The steps in this topic add code to the Quickstart project sample. If you have not created an application using the Quickstart, you need to do so before completing the following steps.

The following shows the Apple Pay sheet rendered by the Web Payments SDK.

A graphic showing the Apple Pay sheet rendered by the Web Payments SDK.

You can find a complete example of the Apple Pay code in GitHub.

Prerequisites and assumptions Permalink Get a link to this section

The Square Web Payments SDK adheres to Apple's development requirements for Apple Pay on the Web. To take an Apple Pay payment, 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.

      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 1: Register your Sandbox domain with Apple Permalink Get a link to this section

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:

  1. Open the Developer Dashboard.

  2. Choose the application associated with your Web Payments SDK implementation.

  3. Set the Developer Dashboard to Sandbox mode.

  4. In the left pane, choose Apple Pay for the selected application.

  5. Choose the Add Sandbox Domain link and follow the instructions.

    • Apple Merchant ID. 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.

    • Domain association folder. If you are using the server provided by the Quickstart application, put the .well-known/apple-developer-merchantid-domain-association folder and file under the public directory.

Warning

For Sandbox testing or production, the domain where you use Apple Pay must be an HTTPS domain. You cannot use a localhost or an HTTP URL with Apple Pay.

Step 2: Attach Apple Pay to the page Permalink Get a link to this section

The Apple Pay payment method needs information about the buyer and the payment amount before it can open the Apple Pay sheet. Your application creates a PaymentRequest object to provide that information and then gets a new ApplePay object initialized with it.

The following code creates the payment request and attaches the ApplePay method to the page:

  1. Add an HTML element to the prerequisite walkthrough form with an ID of apple-pay-button. The HTML for the body of index.html should look like the following:

  2. Add the following style tag to the <head> tag. To see additional button styles, see Styling the Apple Pay Button Using CSS.

  3. Add the following functions to the script tag:

  4. In the DOMContentLoaded eventListener, add the following code after you initialize the ApplePay method:

Test the application

Navigate to your registered HTTPS sandbox domain for Apple Pay in your browser.

A graphic showing a typical payment card input and Apple Pay layout for Web Payments SDK integrations.

Success

You should see the Apple Pay button rendered on your page.

Step 3: Get the payment token from the Apple Pay payment method Permalink Get a link to this section

  1. Add the following code after // Checkpoint 2 in the DOMContentLoaded eventListener function:

Test the application

  1. Navigate to your registered HTTPS sandbox domain for Apple Pay in your browser.

  2. Choose the Apple Pay button.

  3. Use your own personal card. This card is not charged or stored in the Sandbox environment.

    An animation showing Apply Pay being used to pay $1.00.

Success

You should be able to load the Apple Pay form and create a payment.

Payment request details Permalink Get a link to this section

Before your application can request a digital wallet payment, it must provide payment request details that the digital wallet page shows to the buyer. The previous examples showed a payment request with a specified country, currency, and payment amount. In production use, your application might need to declare payment requests that include more detail and with added event listeners. To learn more about advanced payment requests, see Payment Requests.

Step 4: Put your integration into production Permalink Get a link to this section

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

Important

Apple does not allow 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.

Production configuration Permalink Get a link to this section

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

  1. Register a domain for Apple Pay in production:

    1. Open the Developer Dashboard.

    2. Choose the application associated with your Web Payments SDK implementation.

    3. Set the Developer Dashboard to Production mode.

    4. In the left pane, choose Apple Pay for the selected application.

    5. Choose the Add Domain link and follow the instructions.

  2. Change your payment page script tag that references the Web Payments SDK to the following:

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

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.