> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Apple Pay integration

> Configure and accept Apple Pay in the Primer Checkout iOS SDK

> [!WARNING]
>
> 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`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-settings) — 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`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/primer-payment-methods), or as one of the managed screens in [`PrimerCheckout`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout). The merchant identifier you provide in `paymentMethodOptions` is required to pay. Without it, selecting Apple Pay fails with a `PrimerError`.

> [!NOTE]
>
> 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:

> [card] 1. Apple Pay capability
>
> Add the Apple Pay capability to your app target in Xcode.

> [card] 2. Merchant ID
>
> Create a merchant identifier in the Apple Developer portal.

> [card] 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](https://developer.apple.com/account/resources/identifiers/list/merchant), 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.

> [!NOTE]
>
> 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](https://primer.io/docs/index.md) for backend configuration.

## 3. Configure PrimerSettings

Provide the merchant identifier through [`PrimerApplePayOptions`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-settings#primerapplepayoptions), nested inside `paymentMethodOptions` on [`PrimerSettings`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-settings). The `merchantIdentifier` must exactly match the identifier you created in step 2.

```swift theme={"dark"}
import PrimerSDK

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

> [!WARNING]
>
> Set the merchant name through the [client session](https://primer.io/docs/checkout/client-session.md). The SDK uses `merchantName` only when the client session sets none, so you can pass `nil`.

### PrimerApplePayOptions

```swift theme={"dark"}
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](https://primer.io/docs/checkout/client-session.md). |
| `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.

> [!NOTE]
>
> To price shipping from the address the shopper enters, see [Express Checkout shipping](https://primer.io/docs/checkout/primer-checkout/guides-and-recipes/express-checkout-shipping.md). 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.

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

```swift theme={"dark"}
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`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout), pass the settings and the SDK renders Apple Pay among its default screens.

```swift theme={"dark"}
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`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session). Apple Pay then appears as a `CheckoutPaymentMethod` in [`PrimerPaymentMethods`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/primer-payment-methods), alongside the other available methods.

```swift theme={"dark"}
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.
    }
  }
}
```

> [!TIP]
>
> 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.

```swift theme={"dark"}
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. |

> [!NOTE]
>
> Apple Pay failures are reported through the standard result handling path. See [Handle the payment result](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/guides/handle-payment-result.md) and [PrimerError](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-error.md).

## See also

> [card] [PrimerSettings](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-settings.md)
>
> Where Apple Pay options live, alongside the other SDK settings.

> [card] [PrimerPaymentMethods](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/primer-payment-methods.md)
>
> Render Apple Pay as a method row in a custom layout.

> [card] [PrimerCheckout](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout.md)
>
> The managed flow that shows Apple Pay automatically.

> [card] [Express Checkout shipping](https://primer.io/docs/checkout/primer-checkout/guides-and-recipes/express-checkout-shipping.md)
>
> Price shipping from the address the shopper enters in the sheet.

> [card] [Handle the payment result](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/guides/handle-payment-result.md)
>
> Consume the checkout outcome after an Apple Pay payment.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.