> ## 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.1).
  The API is subject to change before the stable release.
</Warning>

Apple Pay is configured through [`PrimerSettings`](/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-settings) — 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`](/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/primer-payment-methods), or as one of the managed screens in [`PrimerCheckout`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout).

<Info>
  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.
</Info>

## Setup overview

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

<CardGroup cols={3}>
  <Card title="1. Apple Pay capability" icon="square-plus">
    Add the Apple Pay capability to your app target in Xcode.
  </Card>

  <Card title="2. Merchant ID" icon="id-card">
    Create a merchant identifier in the Apple Developer portal.
  </Card>

  <Card title="3. PrimerSettings" icon="gear">
    Pass the merchant identifier to the SDK via PrimerApplePayOptions.
  </Card>
</CardGroup>

## 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) for backend configuration.
</Note>

## 3. Configure PrimerSettings

Provide the merchant identifier through [`PrimerApplePayOptions`](/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-settings#primerapplepayoptions), nested inside `paymentMethodOptions` on [`PrimerSettings`](/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>
  `merchantName` is deprecated. Prefer setting the merchant name through the [client session](/docs/checkout/client-session) instead of passing it here.
</Warning>

### PrimerApplePayOptions

```swift theme={"dark"}
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](/docs/checkout/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.

```swift theme={"dark"}
let applePayOptions = PrimerApplePayOptions(
  merchantIdentifier: "merchant.com.myapp",
  merchantName: nil,
  shippingOptions: PrimerApplePayOptions.ShippingOptions(
    shippingContactFields: [.name, .postalAddress],
    requireShippingMethod: true
  ),
  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`](/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`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session). Apple Pay then appears as a `CheckoutPaymentMethod` in [`PrimerPaymentMethods`](/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>
  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.
</Tip>

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

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

## See also

<CardGroup cols={2}>
  <Card title="PrimerSettings" icon="gear" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-settings">
    Where Apple Pay options live, alongside the other SDK settings.
  </Card>

  <Card title="PrimerPaymentMethods" icon="list" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/primer-payment-methods">
    Render Apple Pay as a method row in a custom layout.
  </Card>

  <Card title="PrimerCheckout" icon="square-check" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout">
    The managed flow that shows Apple Pay automatically.
  </Card>

  <Card title="Handle the payment result" icon="diagram-project" href="/docs/sdk/ios-checkout/v3.0.0-beta/guides/handle-payment-result">
    Consume the checkout outcome after an Apple Pay payment.
  </Card>
</CardGroup>