Apple Pay is an easy, secure, and private way to check out using Safari on macOS and iOS with Face ID or Touch ID.
Apple Pay is not available on Android devices, and web browsers other than Safari on Mac, iPhone or iPad.
With Primer’s native Apple Pay integration, you can begin accepting payments across Web and iOS with any card processor in a few simple steps.

​
Get started with Apple Pay

​
Before you begin

If this is your first payment method, make sure to follow the Get started guide to begin processing payments with Primer.

​
Configure in the Dashboard

  1. Add a card processor to your Dashboard
    Go to the Integrations section of the Dashboard and look for a card processor such as Stripe, Adyen, Braintree, and many others.
    Follow the instructions to connect the processor account to your Primer Dashboard.
  2. Add Apple Pay to your Dashboard
    Go to the Integrations section of the Dashboard and look for Apple Pay.
    Follow the instructions to connect your Apple Pay processor account to your Primer Dashboard.
  3. Activate Apple Pay on the Checkout
    Go to the Checkout section of the Dashboard and activate the Apple Pay payment method.
  4. Configure a Workflow to process payments with Apple Pay
    Go to the Workflow section and make sure one of your card processors is used to process Apple Pay payments.

​
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
⚠️ Important Note on Apple Pay MPAN Generation in Sandbox The Apple Pay sandbox environment is strictly limited to DPAN-based payment testing. Merchant tokens (MPANs) are not generated or tested in sandbox. It supports basic provisioning and transaction flows only. For payment scenarios involving MPAN (e.g., recurring payments, deferred charges and automatic reloads), you must test in a production environment with a valid Apple Pay wallet and a merchant token-enabled issuer/network. 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.

​
Add Apple Pay into your website or mobile app

Drop-in UI

Use our customizable drop-in UI to quickly add payment methods to your checkout.

Headless Checkout

Have the freedom to build your own UI using our headless checkout.