How Apple Pay JS API Enables One-Touch Checkout in Safari

This article provides a comprehensive overview of how the Apple Pay JS API facilitates a seamless, one-touch checkout experience within the Safari web browser across macOS, iOS, and iPadOS. It covers the essential technical steps of the transaction lifecycle, from detecting device compatibility and validating the merchant to leveraging native biometric authentication and processing encrypted payment tokens securely.

1. Detecting Device Compatibility

Before displaying an Apple Pay button, a website must verify that the user is browsing with Safari on a compatible Apple device. The Apple Pay JS API injects the ApplePaySession object into the browser's window.

Developers use the ApplePaySession.canMakePayments() method to check if the device has the necessary hardware—specifically the Secure Element chip—and is running a supported version of macOS, iOS, or iPadOS. If this returns true, the website renders the Apple Pay checkout button, ensuring unsupported browsers never see the option.

2. Initiating the Payment Request

The one-touch experience begins the moment the user taps or clicks the Apple Pay button. The website instantly constructs a payment request in JavaScript, which contains the merchant's capabilities, supported card networks (like Visa or Mastercard), the currency, and the total price.

Additionally, the request can ask for shipping and billing addresses. Because this information is already stored in the user's Apple Wallet, the user does not need to manually type out forms, eliminating the biggest friction point in web checkouts. The website then initializes a new ApplePaySession with this data and calls the begin() method to present the native Apple Pay payment sheet over the webpage.

3. Secure Merchant Validation

As soon as the payment sheet appears, Safari initiates a background security check by firing the onvalidatemerchant event. This prevents unauthorized websites from spoofing the Apple Pay interface.

To pass this check, the website's server must communicate directly with Apple’s servers using a verified Merchant Identity Certificate. Apple returns a secure session object, which the website passes into the completeMerchantValidation() method. This cryptographic handshake happens in milliseconds, completely invisible to the user.

4. Dynamic Adjustments and Biometric Authentication

With the sheet validated and displayed, the user sees their default payment card, shipping address, and shipping options. If the user changes their address on the sheet, the API triggers events like onshippingcontactselected, allowing the website to recalculate taxes and shipping costs dynamically before the user approves the final amount.

To authorize the payment, the API relies on the device's native hardware:

• iOS and iPadOS: The user authenticates directly using Face ID or Touch ID.
• macOS (with Touch ID): The user places their finger on the Mac's Touch ID sensor.
• macOS (without Touch ID): Safari uses Apple's Continuity feature over Bluetooth and Wi-Fi to wake a nearby iPhone or Apple Watch, allowing the user to authorize the web transaction on their mobile device.

5. Tokenization and Payment Processing

Once biometric authentication succeeds, the device's Secure Element generates a unique, encrypted payment token. The Apple Pay JS API never exposes the user's actual credit card number to the website or Safari.

Instead, Safari triggers the onpaymentauthorized event and hands the encrypted token and the selected shipping information to the website's JavaScript. The website forwards this token to its backend payment processor (such as Stripe, Adyen, or Braintree) to finalize the charge.

Once the processor confirms the transaction, the website calls completePayment(ApplePaySession.STATUS_SUCCESS). Safari then plays the familiar confirmation chime, displays a checkmark on the payment sheet, and redirects the user to the order confirmation page.