Apple Pay integration

Primer Checkout iOS SDK is currently in beta (v3.0.0-beta.8). The API is subject to change before the stable release.

Apple Pay is configured through PrimerSettings — there is no separate Apple Pay view or scope to wire up. When Apple Pay is enabled on your Primer Dashboard, it appears automatically. It surfaces as a CheckoutPaymentMethod (with type == "APPLE_PAY") in PrimerPaymentMethods, or as one of the managed screens in PrimerCheckout. The merchant identifier you provide in paymentMethodOptions is required to pay. Without it, selecting Apple Pay fails with a PrimerError.

Apple Pay requires a physical device with a card in the Wallet, the Apple Pay capability enabled in your app, and a configured merchant identifier. The iOS Simulator can list Apple Pay, but you cannot complete a payment there.

Setup overview

There are three steps to accept Apple Pay, in order:

1. Apple Pay capability

Add the Apple Pay capability to your app target in Xcode.

2. Merchant ID

Create a merchant identifier in the Apple Developer portal.

3. PrimerSettings

Pass the merchant identifier to the SDK via PrimerApplePayOptions.

1. Enable the Apple Pay capability

In Xcode, select your app target, open the Signing & Capabilities tab, and add the Apple Pay capability. This generates the com.apple.developer.in-app-payments entitlement and lets you attach merchant identifiers to the app.

2. Create a merchant identifier

In the Apple Developer portal, create a merchant identifier (for example merchant.com.myapp). Then return to Xcode and select that merchant identifier under the Apple Pay capability you added in step 1.

You also need a payment processing certificate associated with the merchant identifier, and Apple Pay must be configured for the processor on your Primer Dashboard. See the Apple Pay payment method documentation for backend configuration.

3. Configure PrimerSettings

Provide the merchant identifier through PrimerApplePayOptions, nested inside paymentMethodOptions on PrimerSettings. The merchantIdentifier must exactly match the identifier you created in step 2.

import PrimerSDK

let settings = PrimerSettings(
  paymentMethodOptions: PrimerPaymentMethodOptions(
    applePayOptions: PrimerApplePayOptions(
      merchantIdentifier: "merchant.com.myapp",
      merchantName: nil
    )
  )
)

Set the merchant name through the client session. The SDK uses merchantName only when the client session sets none, so you can pass nil.

PrimerApplePayOptions

public final class PrimerApplePayOptions: Codable {
  public init(
    merchantIdentifier: String,
    merchantName: String?,
    isCaptureBillingAddressEnabled: Bool = false,
    showApplePayForUnsupportedDevice: Bool = true,
    checkProvidedNetworks: Bool = true,
    shippingOptions: ShippingOptions? = nil,
    billingOptions: BillingOptions? = nil,
    allowedCardTypes: [CardType]? = nil
  )
}

Parameter	Type	Default	Description
`merchantIdentifier`	`String`	—	Your Apple Pay merchant identifier (for example `"merchant.com.myapp"`). Must match the identifier configured in Xcode.
`merchantName`	`String?`	—	Merchant name shown on the Apple Pay sheet when the client session sets none. Prefer the client session.
`isCaptureBillingAddressEnabled`	`Bool`	`false`	Requests the billing postal address when `billingOptions` sets no required billing fields. Prefer `billingOptions` to declare required billing fields.
`showApplePayForUnsupportedDevice`	`Bool`	`true`	Not used by Primer Checkout: Apple Pay stays in the payment method list on every device. If the device cannot present Apple Pay, selecting it shows an “Apple Pay Unavailable” screen with the reason. The screen has a “Choose Another Payment Method” button that returns to the payment method list. If the shopper has no other payment method and no saved one, the button does nothing.
`checkProvidedNetworks`	`Bool`	`true`	Whether to verify the device can pay using the provided networks before presenting Apple Pay.
`shippingOptions`	`ShippingOptions?`	`nil`	Shipping contact requirements collected on the Apple Pay sheet.
`billingOptions`	`BillingOptions?`	`nil`	Required billing contact fields collected on the Apple Pay sheet.
`allowedCardTypes`	`[CardType]?`	`nil`	Card types the Apple Pay sheet accepts: `.credit`, `.debit`, or both. `nil` or an empty array accepts all card types.

Collecting contact details

Use ShippingOptions and BillingOptions to require contact fields on the Apple Pay sheet. Both accept RequiredContactField values. ShippingOptions also takes a required requireShippingMethod argument. Primer Checkout ignores it, so pass false unless you share these settings with Drop-In.

To price shipping from the address the shopper enters, see Express Checkout shipping. When you set the shipping handlers, the SDK turns shipping on and requests the postal address itself. requireShippingMethod has no effect. If you set ShippingOptions to request other contact fields, pass requireShippingMethod: false, because the parameter has no default.

let applePayOptions = PrimerApplePayOptions(
  merchantIdentifier: "merchant.com.myapp",
  merchantName: nil,
  shippingOptions: PrimerApplePayOptions.ShippingOptions(
    shippingContactFields: [.name, .postalAddress],
    requireShippingMethod: false
  ),
  billingOptions: PrimerApplePayOptions.BillingOptions(
    requiredBillingContactFields: [.name, .postalAddress]
  )
)

public struct ShippingOptions: Codable {
  public let shippingContactFields: [RequiredContactField]?
  public let requireShippingMethod: Bool

  public init(shippingContactFields: [RequiredContactField]? = nil,
              requireShippingMethod: Bool)
}

public struct BillingOptions: Codable {
  public let requiredBillingContactFields: [RequiredContactField]?

  public init(requiredBillingContactFields: [RequiredContactField]? = nil)
}

public enum RequiredContactField: String, Codable {
  case name, emailAddress, phoneNumber, postalAddress
}

Case	Description
`.name`	Collect the contact’s name.
`.emailAddress`	Collect the contact’s email address.
`.phoneNumber`	Collect the contact’s phone number.
`.postalAddress`	Collect the contact’s postal address.

Showing Apple Pay

Once configured, Apple Pay appears wherever payment methods are rendered. You do not present or initiate the Apple Pay sheet yourself — selecting the method starts the SDK-managed flow.

Managed checkout

With PrimerCheckout, pass the settings and the SDK renders Apple Pay among its default screens.

import SwiftUI
import PrimerSDK

struct CheckoutView: View {
  let clientToken: String

  private let settings = PrimerSettings(
    paymentMethodOptions: PrimerPaymentMethodOptions(
      applePayOptions: PrimerApplePayOptions(
        merchantIdentifier: "merchant.com.myapp",
        merchantName: nil
      )
    )
  )

  var body: some View {
    PrimerCheckout(
      clientToken: clientToken,
      primerSettings: settings
    ) { state in
      // Handle the checkout result.
    }
  }
}

Composable checkout

When you build your own UI, pass the same settings into PrimerCheckoutSession. Apple Pay then appears as a CheckoutPaymentMethod in PrimerPaymentMethods, alongside the other available methods.

import SwiftUI
import PrimerSDK

struct CheckoutScreen: View {
  @StateObject private var session: PrimerCheckoutSession

  init(clientToken: String) {
    let settings = PrimerSettings(
      paymentMethodOptions: PrimerPaymentMethodOptions(
        applePayOptions: PrimerApplePayOptions(
          merchantIdentifier: "merchant.com.myapp",
          merchantName: nil
        )
      )
    )
    _session = StateObject(
      wrappedValue: PrimerCheckoutSession(clientToken: clientToken, settings: settings)
    )
  }

  var body: some View {
    ScrollView {
      PrimerPaymentMethods()
    }
    .primerCheckoutSession(session) { state in
      // Handle the checkout result.
    }
  }
}

The default method slot renders Apple Pay as Apple’s native Apple Pay button. The button follows light and dark mode and has its own VoiceOver label. To single out Apple Pay in a custom layout, override the method slot on PrimerPaymentMethods and branch on paymentMethod.type == "APPLE_PAY". In that branch, call PaymentMethodsDefaults.method so the shopper still sees the native button. Selecting it starts the Apple Pay flow, and the SDK presents the Apple Pay sheet for you.

PrimerPaymentMethods(
  method: { paymentMethod, onSelect in
    if paymentMethod.type == "APPLE_PAY" {
      VStack(spacing: 8) {
        PaymentMethodsDefaults.method(paymentMethod, onSelect: onSelect)
        Text("Fastest checkout")
          .font(.footnote)
          .foregroundColor(.secondary)
      }
    } else {
      PaymentMethodsDefaults.method(paymentMethod, onSelect: onSelect)
    }
  }
)

Troubleshooting

Symptom	Likely cause
Apple Pay does not appear	Apple Pay is not enabled for your processor on the Primer Dashboard, so the client session does not include it. The SDK lists the methods your client session returns.
Selecting Apple Pay ends in a failure	`PrimerSettings` has no `PrimerApplePayOptions`, or the client session has no `order.countryCode`. If your app is not entitled to the merchant identifier in Xcode, the SDK cannot present the Apple Pay sheet.
Selecting Apple Pay shows “Apple Pay Unavailable”	The device does not support Apple Pay, or `checkProvidedNetworks` is `true` and the Wallet has no card on a supported network. To present the sheet whenever the device supports Apple Pay, set `checkProvidedNetworks` to `false`.
Apple Pay payments cannot be completed in the Simulator	Use a physical device with a card in the Wallet and the Apple Pay capability enabled.

Apple Pay failures are reported through the standard result handling path. See Handle the payment result and PrimerError.

PrimerSettings

Where Apple Pay options live, alongside the other SDK settings.

PrimerPaymentMethods

Render Apple Pay as a method row in a custom layout.

PrimerCheckout

The managed flow that shows Apple Pay automatically.

Express Checkout shipping

Price shipping from the address the shopper enters in the sheet.

Handle the payment result

Consume the checkout outcome after an Apple Pay payment.

​Setup overview

1. Apple Pay capability

2. Merchant ID

3. PrimerSettings

​1. Enable the Apple Pay capability

​2. Create a merchant identifier

​3. Configure PrimerSettings

​PrimerApplePayOptions

​Collecting contact details

​Showing Apple Pay

​Managed checkout

​Composable checkout

​Troubleshooting

​See also

PrimerSettings

PrimerPaymentMethods

PrimerCheckout

Express Checkout shipping

Handle the payment result

Setup overview

1. Enable the Apple Pay capability

2. Create a merchant identifier

3. Configure PrimerSettings

PrimerApplePayOptions

Collecting contact details

Showing Apple Pay

Managed checkout

Composable checkout

Troubleshooting

See also