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

Once you're done getting started integrating Apple Pay on your website, you can tweak your code to display and request additional information via the Apple Pay dialog. Just three ways you can tweak it include:

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.

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: 'Stripe.com',
      amount: '19.99'
    }
  };
  var session = Stripe.applePay.buildSession(paymentRequest,
    function(result, completion) {
    console.log(result.token.id);
    completion(true);
  });
  session.begin();
});
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: 'Stripe.com',
      amount: '19.99'
    }
  };
  var session = Stripe.applePay.buildSession(paymentRequest,
    function(result, completion) {
    console.log(result.token.id);
    completion(true);
  });
  session.begin();
});

The code shown above will render this payment sheet.

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.

document.getElementById('apple-pay-button').addEventListener('click', function() {
  var paymentRequest = {
    requiredBillingContactFields: ['postalAddress'],
    requiredShippingContactFields: ['phone'],
    countryCode: 'US',
    currencyCode: 'USD',
    total: {
      label: 'Stripe.com',
      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();
});
document.getElementById('apple-pay-button').addEventListener('click', function() {
  var paymentRequest = {
    requiredBillingContactFields: ['postalAddress'],
    requiredShippingContactFields: ['phone'],
    countryCode: 'US',
    currencyCode: 'USD',
    total: {
      label: 'Stripe.com',
      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();
});

The code shown above will render this payment sheet.

Screenshot of billing and shipping address collection

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.

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

  // We'll write some helper functions to clean things up.
  function buildTotal(selectedShippingMethod) {
    return {
      label: 'Stripe.com',
      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();
});
document.getElementById('apple-pay-button').addEventListener('click', function() {

  // We'll write some helper functions to clean things up.
  function buildTotal(selectedShippingMethod) {
    return {
      label: 'Stripe.com',
      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();
});

The code shown above will render this payment sheet.

Specifying custom line items on the payment sheet

Collecting your user's billing and shipping address

Offering different shipping methods to your user

More Resources