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

Prerequisites

PaymentKit.js prepares Apple Pay automatically when it initializes — the recommended flow has no manual prepare step. You reveal your button once the SDK reports Apple Pay is ready (see Show the express button), and the customer’s tap submits the payment directly.

Add the browser script for your processor:

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>

Choose the wallet processor

By default the SDK auto-selects your account’s express-checkout processor for each wallet. If you have more than one account (Stripe or Airwallex) and want a specific one to handle a wallet, pass processorIds when you construct PaymentKit — a map of payment method to processor id. The SDK then mints and charges that wallet on the exact account you name (Stripe PaymentMethods are account-scoped, so mint and charge must be the same account — this keeps them aligned).

Pass ids only; the processor family (Stripe/Airwallex) is resolved from the account. Apple Pay and Google Pay are set independently:

1
const paymentKit = PaymentKit({
2
  environment: 'production',
3
  secureToken: 'your_secure_token',
4
  paymentMethods: [ApplePayPaymentMethod],
5
  processorIds: {
6
    applePay: 'proc_prod_1e769fc8bf77493c', // EU account
7
  },
8
});

processorIds is read once, when PaymentKit is constructed, and applies for that instance’s lifetime. To steer wallets per checkout — e.g. the EU account for EU shoppers, the US account for US shoppers — compute the id and pass it when you initialize PaymentKit for that session. A single instance reused across checkouts keeps its original value until you re-init.

1
const paymentKit = PaymentKit({
2
  environment: 'production',
3
  secureToken: 'your_secure_token',
4
  paymentMethods: [ApplePayPaymentMethod],
5
  processorIds: {
6
    applePay: isEuShopper
7
      ? 'proc_prod_1e769fc8bf77493c'  // EU account
8
      : 'proc_prod_53cd0b7dbdc4449e', // US account
9
  },
10
});

Show the express button

The SDK prepares Apple Pay automatically as soon as it initializes — you no longer need to call prepareApplePay yourself. Use onApplePayReady to show or hide your express button based on whether Apple Pay is available, and notifyAmountChanged to re-prepare whenever the amount changes.

React to readiness

Register a callback with onApplePayReady. It fires immediately with the current state, then again on every change (for example when a re-prepare starts or finishes). Register as many callbacks as you need — none are overwritten.

1
paymentKit.apple_pay.onApplePayReady((isReady) => {
2
  applePayButton.hidden = !isReady;
3
});

While the SDK is re-preparing (see below), it reports isReady: false, then true again once the new session is ready — so the same callback naturally disables the button during the gap.

Re-prepare after the amount changes

Apple Pay sessions are pinned to a specific amount. Whenever the cart total changes — a coupon is applied, quantity is updated, shipping is added — call notifyAmountChanged() so the SDK clears the stale session and prepares a fresh one. It returns a promise that resolves once the new session is ready.

1
await paymentKit.apple_pay.notifyAmountChanged();

Your onApplePayReady callback fires across the re-prepare (false while in flight, then true), so the button hides and reappears on its own. Calling it again while a prepare is already running coalesces the calls — the promise resolves once the latest prepare completes.

Prepare Apple Pay (legacy)

If you opt into the legacy manual flow, call prepareApplePay before showing the Apple Pay button to check availability and pre-initialize the session — this must happen before the user clicks. With auto-prepare (the recommended flow above), you don’t call this at all.

1
import { prepareApplePay, isApplePayPrepared, clearPreparedApplePay } from '@payment-kit-js/vanilla/payment-methods/apple-pay';
2
3
const 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
18
if (result.success) {
19
  // Show Apple Pay button
20
}

Submit payment

Attach submit to the same button you reveal with onApplePayReady. In the auto-prepare flow the SDK fills processorId, processorType, and country from the prepared session, and the Apple Pay sheet supplies the final payer details — so you don’t pass them.

1
applePayButton.addEventListener('click', () => {
2
  paymentKit.submit({
3
    fields: {},
4
    paymentMethod: 'apple_pay',
5
    options: {
6
      customerInfo: {
7
        first_name: 'Jane',
8
        last_name: 'Smith'
9
      }
10
    },
11
    onSuccess: (result) => {
12
      console.log('Transaction ID:', result.transaction_id);
13
      console.log('Checkout Session:', result.checkout_session_id);
14
      window.location.href = '/success';
15
    },
16
    onError: (errors) => {
17
      if (errors.apple_pay) {
18
        // Surface the error or fall back to the card form
19
      }
20
    }
21
  });
22
});

Cleanup

In the auto-prepare flow the SDK manages prepared state per instance, so no manual cleanup call is required. If you use the legacy prepareApplePay flow, clear the prepared state when unmounting or navigating away:

1
clearPreparedApplePay();

Options

Submit options

In the auto-prepare flow, processorId, processorType, and country are filled from the prepared session — you only pass them if you use the legacy manual flow.

prepareApplePay options (legacy)

These apply only to the deprecated manual prepareApplePay flow.

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)

Error handling

In the auto-prepare flow, availability problems surface through onApplePayReady(false) — the button never appears — rather than as submit errors. Processor ID is required means the checkout session has no express-checkout processor configured.