Apple Pay integration

Primer Checkout iOS SDK is currently in beta (v3.0.0-beta.1). 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. Once you provide a merchant identifier in paymentMethodOptions, Apple Pay is enabled on the backend client session and surfaces automatically as a CheckoutPaymentMethod (with type == "APPLE_PAY") in PrimerPaymentMethods, or as one of the managed screens in PrimerCheckout.

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. It does not appear in the iOS Simulator.

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
    )
  )
)

merchantName is deprecated. Prefer setting the merchant name through the client session instead of passing it here.

PrimerApplePayOptions

public final class PrimerApplePayOptions {
  public init(
    merchantIdentifier: String,
    merchantName: String?,
    isCaptureBillingAddressEnabled: Bool = false,
    showApplePayForUnsupportedDevice: Bool = true,
    checkProvidedNetworks: Bool = true,
    shippingOptions: ShippingOptions? = nil,
    billingOptions: BillingOptions? = 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?`	—	Deprecated. Merchant name shown on the Apple Pay sheet. Prefer the client session.
`isCaptureBillingAddressEnabled`	`Bool`	`false`	Deprecated. Requests the billing address. Prefer `billingOptions` to declare required billing fields.
`showApplePayForUnsupportedDevice`	`Bool`	`true`	When `false`, hides Apple Pay on devices that cannot present it.
`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.

Collecting contact details

Use ShippingOptions and BillingOptions to require contact fields on the Apple Pay sheet. Both accept RequiredContactField values.

let applePayOptions = PrimerApplePayOptions(
  merchantIdentifier: "merchant.com.myapp",
  merchantName: nil,
  shippingOptions: PrimerApplePayOptions.ShippingOptions(
    shippingContactFields: [.name, .postalAddress],
    requireShippingMethod: true
  ),
  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.
    }
  }
}

To single out Apple Pay in a custom layout, override the method slot on PrimerPaymentMethods and branch on paymentMethod.type == "APPLE_PAY". Call the provided onSelect closure to start the Apple Pay flow — the SDK presents the Apple Pay sheet for you.

PrimerPaymentMethods(
  method: { paymentMethod, onSelect in
    if paymentMethod.type == "APPLE_PAY" {
      Button(action: onSelect) {
        HStack {
          Image(systemName: "apple.logo")
          Text(paymentMethod.buttonText ?? paymentMethod.name)
        }
        .frame(maxWidth: .infinity)
        .frame(height: 50)
        .background(.black)
        .foregroundColor(.white)
        .cornerRadius(10)
      }
      .buttonStyle(.plain)
    } else {
      PaymentMethodsDefaults.method(paymentMethod, onSelect: onSelect)
    }
  }
)

Troubleshooting

Symptom	Likely cause
Apple Pay does not appear	No `merchantIdentifier` in `PrimerApplePayOptions`, the merchant identifier does not match Xcode, or Apple Pay is not configured for your processor on the Primer Dashboard.
Apple Pay is hidden on a device	The device cannot present Apple Pay and `showApplePayForUnsupportedDevice` is `false`, or the Wallet has no eligible card and `checkProvidedNetworks` is `true`.
Apple Pay never appears in the Simulator	Apple Pay only runs on a physical device with the 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.

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

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