Apple Pay

Accept Apple Pay for fast, secure checkout on Safari and iOS devices.
View as Markdown

Apple Pay lets customers pay using cards saved to their Apple Wallet with a single tap or glance.

Prerequisites

Apple Pay requires a two-step prepare/submit flow. Before the customer clicks the Apple Pay button, you must call prepareApplePay to initialize the payment session. This is required because Apple Pay sessions must be created in response to a user gesture (browser security requirement).

Add Stripe.js to your page:

1<script src="https://js.stripe.com/v3/"></script>

Setup

1<script src="https://unpkg.com/@payment-kit-js/vanilla/dist/cdn/paymentkit.min.js"></script>
2<script>
3 const paymentKit = PaymentKit.default({
4 environment: 'production',
5 secureToken: 'your_secure_token',
6 paymentMethods: [PaymentKit.PaymentMethods.applePay]
7 });
8</script>

Prepare Apple Pay

Before showing the Apple Pay button, call prepareApplePay to check availability and pre-initialize the session. This must happen before the user clicks the button.

1import { prepareApplePay, isApplePayPrepared, clearPreparedApplePay } from '@payment-kit-js/vanilla/payment-methods/apple-pay';
2
3const result = await prepareApplePay(
4 'https://app.paymentkit.com', // API base URL
5 'your_secure_token',
6 {
7 processorId: 'proc_abc123',
8 processorType: 'airwallex', // Required for Airwallex processors
9 customerInfo: {
10 first_name: 'Jane',
11 last_name: 'Smith'
12 },
13 country: 'US'
14 },
15 'production' // environment
16);
17
18if (result.success) {
19 // Show Apple Pay button
20}

Airwallex processors: You must pass processorType: 'airwallex' in both prepareApplePay and submit options. Without this, the SDK will route the payment through the Stripe flow instead of Airwallex, causing a backend error. Stripe processors work without processorType.

Submit payment

1document.getElementById('apple-pay-button').addEventListener('click', () => {
2 paymentKit.submit({
3 fields: {
4 customer_name: 'Jane Smith',
5 customer_email: 'jane@example.com',
6 customer_country: 'US',
7 customer_zip_code: '94102'
8 },
9 paymentMethod: 'apple_pay',
10 options: {
11 processorId: 'proc_abc123',
12 processorType: 'airwallex', // Required for Airwallex processors
13 customerInfo: {
14 first_name: 'Jane',
15 last_name: 'Smith'
16 },
17 country: 'US'
18 },
19 onSuccess: (result) => {
20 console.log('Transaction ID:', result.transaction_id);
21 console.log('Checkout Session:', result.checkout_session_id);
22 window.location.href = '/success';
23 },
24 onError: (errors) => {
25 if (errors.apple_pay === 'Apple Pay not available') {
26 // Hide button, show card form instead
27 }
28 }
29 });
30});

Cleanup

When unmounting your checkout component or navigating away, clear the prepared state:

1clearPreparedApplePay();

Options

prepareApplePay options

OptionTypeDescription
processorIdstringRequired. Your processor ID with Apple Pay enabled
processorType"stripe" | "airwallex"Required for Airwallex. Set to "airwallex" when using an Airwallex processor
customerInfo.first_namestringRequired. Customer’s first name
customerInfo.last_namestringRequired. Customer’s last name
countrystringRequired. Two-letter country code (e.g., "US")
amountnumberAmount in atomic units (cents) for the Apple Pay sheet display
currencystringCurrency code (e.g., "usd")
merchantNamestringMerchant display name shown on the Apple Pay sheet
mockScenarioApplePayMockScenarioTesting only. Use "success" or "cancelled" to simulate Apple Pay flows without a real device

Submit options

OptionTypeDescription
processorIdstringRequired. Your processor ID with Apple Pay enabled
processorType"stripe" | "airwallex"Required for Airwallex. Must match the value passed to prepareApplePay
customerInfo.first_namestringRequired. Customer’s first name
customerInfo.last_namestringRequired. Customer’s last name
countrystringRequired. Two-letter country code (e.g., "US")
amountnumberAmount in atomic units (cents) for the Apple Pay sheet display
currencystringCurrency code (e.g., "usd")
merchantNamestringMerchant display name shown on the Apple Pay sheet
mockScenarioApplePayMockScenarioTesting only. Use "success" or "cancelled"

Browser support

Apple Pay works on:

  • Safari on macOS (with Touch ID or a paired iPhone/Apple Watch)
  • Safari on iOS and iPadOS (with Face ID, Touch ID, or passcode)

Apple Pay requires Safari. For Stripe processors, PaymentKit.js uses Stripe’s Payment Request API, which also only surfaces Apple Pay in Safari. For Airwallex processors, the native ApplePaySession API is used directly, which is Safari-only. Always provide card payments as a fallback.

Error handling

ErrorCause
Processor ID is requiredMissing processorId in options
Apple Pay not available on this device (requires Safari)Airwallex: device or browser does not support Apple Pay (non-Safari)
Apple Pay not available on this deviceAirwallex: canMakePayment() returned false — no cards in wallet or hardware restriction
Apple Pay is not available on this device or Stripe accountStripe: prepareApplePay could not confirm Apple Pay availability via Payment Request API
Stripe.js not loaded. Add <script src="https://js.stripe.com/v3/"></script> to your page.Stripe.js script not present when initializing the Stripe adapter
Apple Pay cancelled by userCustomer dismissed the Apple Pay sheet
Failed to start Apple PayAPI call to the /apple-pay/start endpoint failed
Apple Pay failedAirwallex payment sheet returned a non-cancelled failure
3DS authentication failedAirwallex 3DS challenge completed without success
Too many authentication attempts. Please try again.Airwallex 3DS loop exceeded the maximum retry limit
Payment failedConfirm or verify endpoint returned a non-success charge status
Apple Pay error: {message}Unexpected exception during the payment flow