Streamline Checkout with Shipping Options in Apple Pay

A little over a year ago, we added support for Apple Pay on the Web in our Online Payments APIs to help developers easily integrate Apple Pay into their websites. However, we know eCommerce checkouts don’t stop with payments — you also need to collect additional details for fulfilling and shipping orders.

Specifically, you need to collect a shipping address and offer different shipping options based on that address. You might provide a free shipping option and a paid shipping option, for those who need a faster delivery. Even though our Online Payments APIs supported collecting a shipping address from within Apple Pay, you had to handle shipping options outside the Apple Pay experience.

With today’s update, Square’s API now supports the entire checkout experience for Apple Pay on the Web, including support for shipping options. You can take payments, ask for and validate the shipping address, and provide various shipping options, all within Apple Pay’s web experience. This speeds up checkout, which in turn increases conversions, with easy to use checkout flows via Apple Pay on web.

How Apple Pay Shipping Options Work:

Add shipping options

You can define any number of shipping options in the PaymentRequest object. The first shipping option will be the default value shown.

...  
createPaymentRequest = function () {
    return {
      requestShippingAddress: true,
      currencyCode: "USD",
      countryCode: "US",
      total: {
        label: "MERCHANT NAME",
        amount: "100",
        pending: false
      },
      lineItems: [
        {
          label: "Widget",
          amount: "90.00",
          pending: false
        }
      ],
      shippingOptions: [
        {
          id: "1",
          label: "Free Shipping",
          amount: "0.00"
        },
        {
          id: "2",
          label: "Expedited Shipping",
          amount: "10.00"
        }
      ]
    }
  };

Validate a shipping address

When your customer chooses a shipping address, the shippingContactChanged callback will be invoked. You can use this callback to validate the shipping address, add new fees and/or taxes based on the shipping address, and update the shipping options.

Errors shown when a shipping address isn’t supported by that merchant

Shipping options and taxes are updated when they choose a Canadian address

shippingContactChanged = function (shippingContact, done) {
 // Shipping address unserviceable.
 if (shippingContact.country !== 'US' &&  shippingContact.country !== 'CA') {
   done({error: 'Shipping to outside of the U.S. and Canada is not available.'});
   return;
 }

 // Update total, lineItems, and shippingOptions for Canadian address.
 if (shippingContact.country === 'CA') {
   done({
     total: {
       label: "MERCHANT NAME",
       amount: "103.00",
       pending: false
     },
     lineItems: [
       {
         label: "Widget",
         amount: "90.00",
         pending: false
       },
       {
         label: "CA Sales Tax",
         amount: "8.00",
         pending: false
       },
       {
         label: "Shipping",
         amount: "5.00",
         pending: false
       },

     ],
     shippingOptions: [
       {
         id: "1",
         label: "CA Post Regular",
         amount: "5.00"
       },
       {
         id: "2",
         label: "CA Post Express",
         amount: "10.00"
       }
     ]
   });
 }

 // Everything looks good and nothing to update
 done();
};

Once a shipping option has been selected, you will also get a chance to update the line items and the total through the shippingOptionChanged callback. Finally, once the payment has been authorized, you will get the final shipping address and the final shipping option in the cardNonceResponseReceived callback.

cardNonceResponseReceived: function (errors, nonce, cardData, billingContact, shippingContact, shippingOption)
{
// shippingContact and shippingOption are the final shipping address and shipping option selected by the buyer 
}

We are excited with this release and we look forward to seeing you implement this in your web applications. You can read more about our support for shipping options in Apple Pay on our documentation. To learn more about Square’s developer platform visit https://squareup.com/developers or join our community at squ.re/slack.

Note: Square supports Apple Pay only for USD transactions.

Additional Reading:

• Integrate with SqPaymentForm

• Integrate with Checkout API

If you want to keep up to date with the rest of our content, be sure to follow this blog & our Twitter account, and sign up for our developer newsletter! We also have a Slack community for connecting with and talking to other developers implementing Square APIs.