​
Before you begin

This guide assumes that you know how to

​
Accept payments with Apple Pay

​
Prepare the client session

Apple Pay leverages the following parameters to process a payment.

Pass them when creating the client session.

Parameter NameRequiredDescription
currencyCode✓3-letter currency code in ISO 4217 format, e.g. USD for US dollars
order
↳ lineItems		✓Details of the line items of the order
order
↳ countryCode		✓The country in which the order is created
paymentMethod
↳ options
↳ APPLE_PAY
↳ merchantName		For payments using the Apple Pay payment method, use this field to override the default merchant name for the Primer account from showing on the Apple Pay flow. For example, if your merchant name on your account is “Company X” but you want to display a specific store name on the Apple Pay flow, you can set the merchantName to “Store name A”.
paymentMethod
↳ options
↳ APPLE_PAY
↳ recurringPaymentRequest		Required for recurring payments. Include to specify that the payment is a recurring payment, typically for subscriptions.
paymentMethod
↳ options
↳ APPLE_PAY
↳ deferredPaymentRequest		Required for deferred payments. Include to specify that payment will be charged at a future date, such as hotel bookings or pre-orders.
paymentMethod
↳ options
↳ APPLE_PAY
↳ automaticReloadRequest		Required for automatic reload payments. Include to enable automatic top-ups when account balance falls below a threshold, such as transit cards or loyalty programs.

​
Apple Pay MPAN Configuration

Apple Pay Merchant Tokens (MPANs) provide better payment continuity across devices compared to Device Primary Account Numbers (DPANs). Primer enables you to request MPANs from Apple Pay according to Apple’s guidelines, though Apple Pay may still return DPANs if the issuer doesn’t support MPAN generation.

For stored payment methods (vaultOnSuccess: true):

Use the appropriate MPAN request configuration based on your payment use case.

firstPaymentReasonMPAN Request TypeUse CasesRequired
RecurringRecurring PaymentsSubscriptions, memberships, scheduled billingrecurringPaymentRequest
UnscheduledDeferred PaymentsBuy-now-pay-later, layaway, delayed billingdeferredPaymentRequest
UnscheduledAutomatic ReloadWallet top-ups, account reloadsautomaticReloadRequest

For one-time payments (vaultOnSuccess: false):

  • Standard Apple Pay flow is used
  • No MPAN request configuration needed since tokens aren’t stored

For detailed configuration examples and parameter references, see the Apple Pay API reference.

​
Prepare the SDK for payments

Show Universal Checkout
Apple Pay is automatically presented to the customer when calling Primer.showUniversalCheckout.

Typescript
try {
  await Primer.showUniversalCheckout(clientToken, {
    container: '#checkout-container',
    options,
    onCheckoutComplete({ payment }) {
      console.log('Checkout complete.', payment)
    },
  })
} catch (e) {
  // handle error
}

Customization
Check the Customization Guide to learn how to customize payment method buttons.

Additionally, you can style the Apple Pay button by passing the following options:

Typescript
const options = {
    /* Other options... */
    applePay: {
        buttonType: 'plain', // 'plain' (default) | 'buy' | 'set-up' | 'donate' | 'check-out' | 'book' | 'subscribe'
        buttonStyle: 'black', // 'black' (default) | 'white' | 'white-outline',
    }
}

Capture billing address

By default, Apple Pay does not capture the user’s billing address.

You can ask to capture the billing address by setting the option captureBillingAddress. The billing address is added to the client session before the payment is made.

Typescript
const options = {
    /* Other options... */
    applePay: {
        captureBillingAddress: true,
    }
}

​
Limitations

  • Apple Pay is only supported on Apple Devices and Safari Browser. For more info take a look at the Apple support page.
  • Until iOS 16, Apple Pay does not appear on in-app webviews.
  • Apple Pay only appears if the website is using HTTPS.
  • Our current implementation of Apple Pay does not support the card networks mir, girocard, bancomat, and bancontact.

​
Troubleshooting

Apple Pay button is not presented

If the Apple Pay button is not presented, check that:

  • The browser is Safari
  • The website is using HTTPS
  • The domain has been registered in the Dashboard
  • The order details and country code have been passed to the client session

​
Test

Check out Apple Pay’s Sandbox Testing guide to make payments with Apple Pay on sandbox.

​
Go live

You don’t need to do anything particular to go live — just make sure to use production credentials.