> ## 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.

# PrimerSettings

> SDK configuration: payment handling, payment method options, UI, and debug options

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

`PrimerSettings` is the SDK's top-level configuration object. Create it once and pass it to your checkout entry point, either as `primerSettings:` on [`PrimerCheckout`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout) or as `settings:` on [`PrimerCheckoutSession`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session).

## Definition

```swift theme={"dark"}
public final class PrimerSettings: Codable {
    public init(
        paymentHandling: PrimerPaymentHandling = .auto,
        localeData: PrimerLocaleData? = nil,
        paymentMethodOptions: PrimerPaymentMethodOptions? = nil,
        uiOptions: PrimerUIOptions? = nil,
        threeDsOptions: PrimerThreeDsOptions? = nil,
        debugOptions: PrimerDebugOptions? = nil,
        clientSessionCachingEnabled: Bool = false,
        apiVersion: PrimerApiVersion = .V2_4
    )
}
```

| Parameter                     | Type                          | Default | Description                                                                                               |
| ----------------------------- | ----------------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `paymentHandling`             | `PrimerPaymentHandling`       | `.auto` | Controls whether the SDK creates the payment automatically or returns a token for server-side processing. |
| `localeData`                  | `PrimerLocaleData?`           | `nil`   | Forces the SDK locale for translations and formatting. Defaults to the device locale.                     |
| `paymentMethodOptions`        | `PrimerPaymentMethodOptions?` | `nil`   | Payment method-specific configuration (Apple Pay, Klarna, 3DS, Stripe ACH, redirect scheme).              |
| `uiOptions`                   | `PrimerUIOptions?`            | `nil`   | UI behavior settings: which screens are shown, dismissal mechanisms, appearance mode, and theme.          |
| `threeDsOptions`              | `PrimerThreeDsOptions?`       | `nil`   | 3D Secure configuration. Can also be set inside `paymentMethodOptions`.                                   |
| `debugOptions`                | `PrimerDebugOptions?`         | `nil`   | Debug and development options.                                                                            |
| `clientSessionCachingEnabled` | `Bool`                        | `false` | Caches client session data to reduce network requests.                                                    |
| `apiVersion`                  | `PrimerApiVersion`            | `.V2_4` | Primer API version used for backend communication.                                                        |

<Note>
  Each option group is optional. Pass `nil` (the default) to use the SDK defaults, or supply a configured object to override behavior for that group.
</Note>

## Usage

```swift theme={"dark"}
let settings = PrimerSettings(
    paymentHandling: .auto,
    localeData: PrimerLocaleData(languageCode: "de", regionCode: "DE"),
    paymentMethodOptions: PrimerPaymentMethodOptions(
        urlScheme: "myapp://primer",
        applePayOptions: PrimerApplePayOptions(
            merchantIdentifier: "merchant.com.myapp",
            merchantName: nil
        )
    ),
    uiOptions: PrimerUIOptions(
        isInitScreenEnabled: false,
        dismissalMechanism: [.gestures, .closeButton],
        appearanceMode: .system
    )
)

PrimerCheckout(
    clientToken: clientToken,
    primerSettings: settings,
    onCompletion: { state in
        // Handle the checkout result
    }
)
```

<Tip>
  Define your settings outside the SwiftUI view body (for example, as a stored property) so they are not re-created on every render cycle.
</Tip>

```swift theme={"dark"}
private let primerSettings = PrimerSettings(paymentHandling: .auto)

struct CheckoutView: View {
    let clientToken: String

    var body: some View {
        PrimerCheckout(
            clientToken: clientToken,
            primerSettings: primerSettings
        )
    }
}
```

***

## PrimerPaymentHandling

Defines how payments are processed after the payment method has been tokenized.

```swift theme={"dark"}
public enum PrimerPaymentHandling: String, Codable {
    case auto   = "AUTO"
    case manual = "MANUAL"
}
```

| Case      | Description                                                                                                                                                                          |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `.auto`   | The SDK creates the payment after tokenization. The simplest integration. Results are delivered through the completion handler. Recommended.                                         |
| `.manual` | After tokenization, your backend receives the payment method token and is responsible for creating the payment via the Primer API. Use for additional control over the payment flow. |

See [Handle the payment result](/docs/sdk/ios-checkout/v3.0.0-beta/guides/handle-payment-result) for how each mode surfaces results.

***

## PrimerLocaleData

Forces the SDK locale instead of inheriting the device locale.

```swift theme={"dark"}
public struct PrimerLocaleData: Codable, Equatable {
    public let languageCode: String
    public let localeCode: String
    public let regionCode: String?

    public init(languageCode: String? = nil, regionCode: String? = nil)
}
```

| Property       | Type      | Description                                                                                            |
| -------------- | --------- | ------------------------------------------------------------------------------------------------------ |
| `languageCode` | `String`  | ISO 639-1 language code (for example `"en"`, `"de"`, `"fr"`). Defaults to the device language.         |
| `localeCode`   | `String`  | Combined `language-region` code (for example `"en-US"`). Computed from the language and region codes.  |
| `regionCode`   | `String?` | ISO 3166-1 alpha-2 region code (for example `"US"`, `"GB"`). `nil` when only the language is provided. |

<Warning>
  v3.0 breaking change: in v2.x, providing `languageCode` without `regionCode` defaulted to the device region (for example `"de-US"`). In v3.0, `regionCode` is `nil` when not explicitly provided, producing `"de"` instead.
</Warning>

***

## PrimerPaymentMethodOptions

Payment method-specific configuration. Set `urlScheme` for any flow that redirects to a third-party app (3DS, Klarna).

```swift theme={"dark"}
public final class PrimerPaymentMethodOptions {
    public init(
        urlScheme: String? = nil,
        applePayOptions: PrimerApplePayOptions? = nil,
        klarnaOptions: PrimerKlarnaOptions? = nil,
        threeDsOptions: PrimerThreeDsOptions? = nil,
        stripeOptions: PrimerStripeOptions? = nil
    )
}
```

| Parameter         | Type                     | Default | Description                                                                                                        |
| ----------------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `urlScheme`       | `String?`                | `nil`   | Deep link scheme for returning from third-party apps (for example `"myapp://primer"`). Must be a valid URL scheme. |
| `applePayOptions` | `PrimerApplePayOptions?` | `nil`   | Apple Pay configuration. Required when using Apple Pay.                                                            |
| `klarnaOptions`   | `PrimerKlarnaOptions?`   | `nil`   | Klarna configuration. Required when using Klarna.                                                                  |
| `threeDsOptions`  | `PrimerThreeDsOptions?`  | `nil`   | 3D Secure configuration.                                                                                           |
| `stripeOptions`   | `PrimerStripeOptions?`   | `nil`   | Stripe ACH configuration. Required when using Stripe ACH.                                                          |

### 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"`).                                  |
| `merchantName`                     | `String?`          | —       | **Deprecated.** Provide the merchant name through the [client session](/docs/checkout/client-session) instead. |
| `isCaptureBillingAddressEnabled`   | `Bool`             | `false` | **Deprecated.** Use `billingOptions` to configure required billing fields instead.                        |
| `showApplePayForUnsupportedDevice` | `Bool`             | `true`  | When `false`, hides Apple Pay on devices that do not support 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.                                                                            |
| `billingOptions`                   | `BillingOptions?`  | `nil`   | Required billing contact fields.                                                                          |

`ShippingOptions` and `BillingOptions` collect required Apple Pay contact fields:

```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
}
```

See [Apple Pay integration](/docs/sdk/ios-checkout/v3.0.0-beta/guides/apple-pay-integration) for end-to-end setup.

### PrimerKlarnaOptions

```swift theme={"dark"}
public final class PrimerKlarnaOptions: Codable {
    public init(recurringPaymentDescription: String)
}
```

| Parameter                     | Type     | Description                                      |
| ----------------------------- | -------- | ------------------------------------------------ |
| `recurringPaymentDescription` | `String` | Description shown for recurring Klarna payments. |

### PrimerStripeOptions

```swift theme={"dark"}
public final class PrimerStripeOptions: Codable, Equatable {
    public enum MandateData: Codable, Equatable {
        case fullMandate(text: String)
        case templateMandate(merchantName: String)
    }

    public init(publishableKey: String, mandateData: MandateData? = nil)
}
```

| Parameter        | Type           | Default | Description                                                                                                                |
| ---------------- | -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `publishableKey` | `String`       | —       | Stripe publishable key.                                                                                                    |
| `mandateData`    | `MandateData?` | `nil`   | ACH mandate text. Use `.templateMandate(merchantName:)` for a standard template, or `.fullMandate(text:)` for custom text. |

### PrimerThreeDsOptions

```swift theme={"dark"}
public struct PrimerThreeDsOptions: Codable, Equatable {
    public init(threeDsAppRequestorUrl: String? = nil)
}
```

| Parameter                | Type      | Default | Description                                |
| ------------------------ | --------- | ------- | ------------------------------------------ |
| `threeDsAppRequestorUrl` | `String?` | `nil`   | App requestor URL for 3DS2 authentication. |

***

## PrimerUIOptions

Controls checkout UI behavior: which screens are shown, how the sheet is dismissed, appearance mode, and theme.

```swift theme={"dark"}
public final class PrimerUIOptions {
    public internal(set) var isInitScreenEnabled: Bool
    public internal(set) var isSuccessScreenEnabled: Bool
    public internal(set) var isErrorScreenEnabled: Bool
    public internal(set) var dismissalMechanism: [DismissalMechanism]
    public internal(set) var cardFormUIOptions: PrimerCardFormUIOptions?
    public internal(set) var appearanceMode: PrimerAppearanceMode
    public var theme: PrimerTheme

    public init(
        isInitScreenEnabled: Bool? = nil,
        isSuccessScreenEnabled: Bool? = nil,
        isErrorScreenEnabled: Bool? = nil,
        dismissalMechanism: [DismissalMechanism]? = [.gestures],
        cardFormUIOptions: PrimerCardFormUIOptions? = nil,
        appearanceMode: PrimerAppearanceMode? = nil,
        theme: PrimerTheme? = nil
    )
}
```

| Parameter                | Type                       | Default         | Description                                                                                                     |
| ------------------------ | -------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------- |
| `isInitScreenEnabled`    | `Bool?`                    | `true`          | Shows a loading screen while the checkout initializes.                                                          |
| `isSuccessScreenEnabled` | `Bool?`                    | `true`          | Shows a success screen after the payment completes.                                                             |
| `isErrorScreenEnabled`   | `Bool?`                    | `true`          | Shows an error screen when a payment fails.                                                                     |
| `dismissalMechanism`     | `[DismissalMechanism]?`    | `[.gestures]`   | How the user can dismiss the checkout modal.                                                                    |
| `cardFormUIOptions`      | `PrimerCardFormUIOptions?` | `nil`           | Card form-specific UI options.                                                                                  |
| `appearanceMode`         | `PrimerAppearanceMode?`    | `.system`       | Appearance mode for the UI.                                                                                     |
| `theme`                  | `PrimerTheme?`             | `PrimerTheme()` | Visual theme for all SDK components. See [PrimerTheme](/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/primer-theme). |

### DismissalMechanism

```swift theme={"dark"}
public enum DismissalMechanism: String, Codable {
    case gestures = "GESTURES"
    case closeButton = "CLOSE_BUTTON"
}
```

| Case           | Description                                    |
| -------------- | ---------------------------------------------- |
| `.gestures`    | Dismiss the modal with swipe-down gestures.    |
| `.closeButton` | Display a close button in the navigation area. |

### PrimerAppearanceMode

```swift theme={"dark"}
public enum PrimerAppearanceMode: String, Codable {
    case system = "SYSTEM"
    case light = "LIGHT"
    case dark = "DARK"
}
```

| Case      | Description                                     |
| --------- | ----------------------------------------------- |
| `.system` | Follows the device appearance setting. Default. |
| `.light`  | Forces light appearance.                        |
| `.dark`   | Forces dark appearance.                         |

### PrimerCardFormUIOptions

```swift theme={"dark"}
public struct PrimerCardFormUIOptions: Codable {
    public let payButtonAddNewCard: Bool

    public init(payButtonAddNewCard: Bool = false)
}
```

| Parameter             | Type   | Default | Description                                                                     |
| --------------------- | ------ | ------- | ------------------------------------------------------------------------------- |
| `payButtonAddNewCard` | `Bool` | `false` | When `true`, the card form button shows "Add new card" instead of "Pay \$X.XX". |

***

## PrimerDebugOptions

```swift theme={"dark"}
public struct PrimerDebugOptions: Codable {
    public init(is3DSSanityCheckEnabled: Bool? = nil)
}
```

| Parameter                 | Type    | Default | Description                                                          |
| ------------------------- | ------- | ------- | -------------------------------------------------------------------- |
| `is3DSSanityCheckEnabled` | `Bool?` | `true`  | Enables 3DS security sanity checks. Disable only during development. |

***

## PrimerApiVersion

```swift theme={"dark"}
public enum PrimerApiVersion: String, Codable {
    case V2_4 = "2.4"

    public static let latest: PrimerApiVersion = .V2_4
}
```

| Case   | Description                      |
| ------ | -------------------------------- |
| `V2_4` | Primer API version 2.4 (latest). |

***

## See also

<CardGroup cols={2}>
  <Card title="PrimerCheckout" icon="square-check" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout">
    The managed checkout view that accepts these settings
  </Card>

  <Card title="PrimerCheckoutPresenter" icon="window-maximize" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-presenter">
    Present checkout from UIKit with PrimerSettings
  </Card>

  <Card title="PrimerError" icon="triangle-exclamation" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-error">
    Error type surfaced through the completion handler
  </Card>

  <Card title="PrimerTheme" icon="palette" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/primer-theme">
    Theme the checkout UI via uiOptions.theme
  </Card>
</CardGroup>