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

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

    The code shown above will render this payment sheet.

    Screenshot of 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.

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

    The code shown above will render this payment sheet.

    Shipping methods

    More Resources

    Questions?

    We're always happy to help with code or other questions you might have! Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.