New
Web Payments SDK

Take an Apple Pay Payment

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

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: web-payments : apple pay : hero

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. Select the application associated with your Web Payments SDK implementation.

  3. Set the Developer Dashboard to Sandbox mode.

  4. Choose the Apple Pay tab 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 either sandbox testing or production, the domain where you will use Apple Pay must be an HTTPS domain. You cannot use a localhost or 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 then 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 the following style tag to the <head> tag. To see additional button styles, see Styling the Apple Pay button with css.

     <style>
       #apple-pay-button {
         height: 48px;
         width: 100%;
         display: inline-block;
         -webkit-appearance: -apple-pay-button;
         -apple-pay-button-type: plain;
         -apple-pay-button-style: black;
       }
     </style>
    
  3. Add the following functions to the script tag:

     function buildPaymentRequest(payments) {
       return payments.paymentRequest({
         countryCode: 'US',
         currencyCode: 'USD',
         total: {
           amount: '1.00',
           label: 'Total',
         },
       });
     }
    
     async function initializeApplePay(payments) {
       const paymentRequest = buildPaymentRequest(payments)
       const applePay = await payments.applePay(paymentRequest);
       // Note: You do not need to `attach` applePay.
       return applePay;
     }
    
  1. In the DOMContentLoaded eventListener, 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 may not be supported
      // (e.g. Browser Support, Device Support, Account). Therefore you should
      // handle
      // initialization failures, while still loading other applicable payment
      // methods.
    }
    

Test the application

  1. Navigate to http://localhost:3000/ in your browser.

    web payments : apple pay : button

Checkpoint 1: You should now 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:

     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 http://localhost:3000/ 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. web payments : apple pay : checkpoint 2

Checkpoint 2: 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. Select the application associated with your Web Payments SDK implementation.

    3. Set the Developer Dashboard to Production mode.

    4. Choose the Apple Pay tab 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:

     https://web.squarecdn.com/v0.1/square.js
    
  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.