Square Payment Form: Add Digital Wallets

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: Apple Pay Mark RGB SMALL 052318

Prerequisites and assumptions
Permalink Get a link to this section

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:

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 1: Configure payment form for v2 Sandbox
Permalink Get a link to this section

In index.html, set the SqPaymentForm reference URL to:


<script type="text/javascript" src="https://js.squareupsandbox.com/v2/paymentform">
</script>

Step 2: Register your sandbox domain with Apple
Permalink Get a link to this section

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:

  1. Open the Application Dashboard.

  2. Select the application associated with your SqPaymentForm implementation.

  3. Set the Application Dashboard to Sandbox Settings mode.

  4. Click on the Apple Pay tab for the selected application.

  5. 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 3: Add the Apple Pay placeholder to your payment page
Permalink Get a link to this section

In index.html, Add a button element for Apple Pay:

  <button id="sq-apple-pay" class="button-apple-pay"></button>

Step 4: Configure the SqPaymentForm object
Permalink Get a link to this section

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.

  1. Copy your Application ID from the Credentials page.

  2. Copy a location ID from the Locations page.

  3. Enable the applePay configuration 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
Permalink Get a link to this section

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.

  1. 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);
      }
    }
,
  1. 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
Permalink Get a link to this section

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
Permalink Get a link to this section

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
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 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:

  1. Open your payment page in a Safari browser and verify the Apple Pay button renders like the following button: Apple Pay Mark RGB SMALL 052318

  2. Click the Apple Pay button and complete the payment sheet that opens

  3. Verify that you are receiving a nonce in the cardNonceResponseReceived callback.

The nonce generated for Apple Pay can be used to take a payment with the Payments API in the v2 Sandbox environment.

Production configuration
Permalink Get a link to this section

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

  1. Register a domain for Web Apple Pay in production :

    1. Open the Application Dashboard.

    2. Select the application associated with your SqPaymentForm implementation.

    3. Set the Application Dashboard to Production Settings mode.

    4. Click on the Apple Pay tab for the selected application.

    5. Click on the "Add Domain" link and follow the onscreen instructions.

  2. Change your payment page script tag that references the payment form library to:

     https://js.squareup.com/v2/paymentform
    
  3. Replace 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.