Take an Apple Pay Payment

Applies to: Web Payments SDK

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

Link to section


You can add Apple Pay to the application you built in Web Payments SDK Quickstart using the Quickstart project sample. To see whether digital wallets are supported in your country, see Digital wallet payments.

The following steps add code to the quickstart project sample. If you haven't created an application using the quickstart, you need to do so before completing these 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 on GitHub.

Link to section

Requirements and limitations

The 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're 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 or later - Apple Pay JavaScript is supported on all iOS devices with a Secure Element. It's supported in both Safari and SFSafariViewController objects.

    • macOS 10.12 or 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.


      If you're developing on a MacBook Pro, it might be necessary to activate Apple Pay and Touch ID, and then restart Safari.

Link to section

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


You must configure the Terms and Conditions certificate to download when the buyer visits the URL. Otherwise, your application won't be able to validate the agreement. Also, if the certificate gets a file extension added to it by your server, the validation won't work.

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 don't need to create an Apple merchant ID or call the Apple APIs to enable the functionality.

    • Domain association folder - If you're using the server provided by the quickstart application, put the .well-known/apple-developer-merchantid-domain-association folder and file under the public directory. The domain verification file works only with Square as the domain.


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.

Link to section

2. Attach Apple Pay to the page

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:

    <form id="payment-form"> <!-- Add the below element --> <div id="apple-pay-button"></div> <div id="card-container"></div> <button id="card-button" type="button">Pay $1.00</button> </form> <div id="payment-status-container"></div>
  2. Add a style element and button style properties in the <head> tag. For a reference of Apple Pay button styles, see Styling the Apple Pay Button Using CSS.

  3. Add the following functions to the script tag:

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

    let applePay; try { applePay = await initializeApplePay(payments); } catch (e) { console.error('Initializing Apple Pay failed', e); // There are a number of reason why Apple Pay might not be supported. // (such as Browser Support, Device Support, Account). Therefore you should // handle // initialization failures, while still loading other applicable payment // methods. }

Test the application

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


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

  2. At this point, return to your code and find the handlePaymentMethodSubmission function call to continue.

Link to section

3. Get the payment token from the Apple Pay payment method

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

    if (applePay !== undefined) { const applePayButton = document.getElementById('apple-pay-button'); applePayButton.addEventListener('click', async function (event) { await handlePaymentMethodSubmission(event, applePay); }); }

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 isn't charged or stored in the Sandbox environment.

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


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

Link to section

Payment request details

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.

Link to section

4. Put your integration into production

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


Apple doesn't allow Sandbox test credit card values. You must use a valid credit card from your Apple Pay Wallet. The card isn't charged for test payments as long as you're testing in the Square Sandbox.

Link to section

Production configuration

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 Developer Dashboard Locations page for a Square account.