Customize your website's Apple Pay integration with Stripe.js v2

This reference covers the Apple Pay integration using Stripe.js v2, the previous version of our foundational JavaScript library. Our current version of Stripe.js includes support for Apple Pay using Elements, our prebuilt UI components. We recommend that users of Stripe.js v2 upgrade at their earliest convenience.

Once you’re done getting started integrating Apple Pay on your website, you can update your code to display and request additional information through the Apple Pay dialog:

Specifying custom line items on the payment sheet
Collecting your user’s billing and shipping address
Offering different shipping methods to your user

Specifying custom line items on the payment sheet

The Stripe.applePay.buildSession function introduced in our getting started guide is really just a thin wrapper around Apple’s ApplePaySession class. Specifically, it handles the onvalidatemerchant and onpaymentauthorized events for you. You can use the other available keys in your PaymentRequest, and the other available events on the ApplePaySession to collect your users’ shipping address and preferred shipping method, and to even offer them different shipping options and prices depending on their location.

You can set the lineItems key in the PaymentRequest you pass to buildSession, and the user will be shown a more detailed summary of their payment. Apple recommends that instead of a totally itemized receipt, you group all of the items a user is purchasing into one “subtotal” item, and then add additional items for shipping, tax, discounts, etc. as needed.

product.js

document.getElementById('apple-pay-button').addEventListener('click', function() {
  var paymentRequest = {
    countryCode: 'US',
    currencyCode: 'USD',
    lineItems: [
      {
        type: 'final',
        label: 'Fancy Hat',
        amount: '15.00'
      },
      {
        type: 'final',
        label: 'Shipping',
        amount: '10.00'
      },
      {
        type: 'final',
        label: 'Tax',
        amount: '0.99'
      },
      {
        type: 'final',
        label: 'Discount',
        amount: '-6.00'
      }
    ],
    total: {
      label: 'Rocketship Inc',
      amount: '19.99'
    }
  };
  var session = Stripe.applePay.buildSession(paymentRequest,
    function(result, completion) {
    console.log(result.token.id);
    completion(true);
  });
  session.begin();
});

Payment sheet with custom line items

Collecting your user’s billing and shipping address

If you specify the requiredBillingContactFields property on your PaymentRequest, the user will be prompted to choose their billing address before payment. Their address fields will then be available on the result.token object in the success callback you pass to buildSession. Similarly, you can specify the requiredShippingContactFields property on your PaymentRequest and it’ll be available as the result.shippingContact object in your success callback. The keys that will be present on the shippingContact can be found on Apple’s Developer docs.

product.js

document.getElementById('apple-pay-button').addEventListener('click', function() {
  var paymentRequest = {
    requiredBillingContactFields: ['postalAddress'],
    requiredShippingContactFields: ['phone'],
    countryCode: 'US',
    currencyCode: 'USD',
    total: {
      label: 'Rocketship Inc',
      amount: '19.99'
    }
  };
  var session = Stripe.applePay.buildSession(paymentRequest,
    function(result, completion) {
    console.log(result.token.card.address_line1); // 12 Main St
    console.log(result.shippingContact.phoneNumber); // 8885551212
    completion(true);
  });
  session.begin();
});

Screenshot of billing and shipping address collection

Payment sheet with billing address

Offering different shipping methods to your user

You can also offer your user a variety of shipping methods to choose from by setting the shippingMethods property on your PaymentRequest. You can then change the lineItems property on your session when the user selects one of them. Depending on the type of service your site offers, you can also set the shippingType key on your PaymentRequest to one of shipping, delivery, storePickup, or servicePickup to have Apple Pay style the sheet more appropriately.

product.js

document.getElementById('apple-pay-button').addEventListener('click', function() {

  // We'll write some helper functions to clean things up.
  function buildTotal(selectedShippingMethod) {
    return {
      label: 'Rocketship Inc',
      amount: (parseFloat(selectedShippingMethod.amount) + 19.99).toFixed(2)
    }
  }

  function buildLineItems(selectedShippingMethod) {
    return [
      {
        type: 'final',
        label: 'Fancy Hat',
        amount: '19.99'
      },
      {
        type: 'final',
        label: 'Shipping',
        amount: selectedShippingMethod.amount
      },
    ]
  }

  var shippingMethods = [
    {
      label: 'Ground Shipping',
      detail: 'Arrives 5-7 business days',
      amount: '5.00',
      identifier: 'ground'
    },
    {
      label: 'Express Shipping',
      detail: 'Arrives 2-3 business days',
      amount: '15.00',
      identifier: 'express'
    }
  ];

  var paymentRequest = {
    shippingMethods: shippingMethods,
    shippingType: 'shipping',
    countryCode: 'US',
    currencyCode: 'USD',
    // By default, the first shipping method will be selected.
    lineItems: buildLineItems(shippingMethods[0]),
    total: buildTotal(shippingMethods[0])
  };

  var session = Stripe.applePay.buildSession(paymentRequest,
    function(result, completion) {
    console.log(result.shippingMethod.label); // "Ground Shipping"
  });

  session.onshippingmethodselected = function(event) {
    // You can do work asynchronously here; just call
    // session.completeShippingMethodSelection when you're done.
    session.completeShippingMethodSelection(
      ApplePaySession.STATUS_SUCCESS,
      buildTotal(event.shippingMethod),
      buildLineItems(event.shippingMethod)
    )
  }

  session.begin();
});

Payment sheet with shipping method selection

Customize your website's Apple Pay integration with Stripe.js v2

Specifying custom line items on the payment sheet

Collecting your user’s billing and shipping address

Offering different shipping methods to your user

See also