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

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