Square Payment Form: Add Digital Wallets

Add the Apple Pay on the Web Button

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

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: Configure a payment form for the 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 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 SqPaymentForm 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.

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

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

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

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.

  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 6: Update the methodsSupported callback function Permalink Get a link to this section

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.

  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);
      }
    }
,

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

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 () {

     //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 about the expected structure of a payment request object, see sqPaymentForm Object Model.

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

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

  2. Choose 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 Sandbox environment.

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