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

`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`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout) or as `settings:` on [`PrimerCheckoutSession`](https://primer.io/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` | Keep the default. Primer Checkout creates the payment after tokenization. `.manual` fails the checkout at start, see [PrimerPaymentHandling](#primerpaymenthandling). |
| `localeData` | `PrimerLocaleData?` | `nil` | Locale used to format amounts. Its `localeCode` is also sent with Klarna, redirect, QR code, form redirect and Stripe ACH payment requests. Defaults to the device locale. It does not change the language of the SDK's own UI text, which follows the app's language. |
| `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, and appearance mode. |
| `threeDsOptions` | `PrimerThreeDsOptions?` | `nil` | Ignored. The SDK does not read this parameter. Set 3D Secure options through `paymentMethodOptions: PrimerPaymentMethodOptions(threeDsOptions:)` instead. |
| `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.

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

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

Primer Checkout supports `.auto` only. The SDK tokenizes the payment method, creates the payment, and delivers the result through the completion handler.

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

| Case | Description |
| - | - |
| `.auto` | The SDK creates the payment after tokenization. Results are delivered through the completion handler. |
| `.manual` | Not supported in Primer Checkout. The checkout fails at start with a `PrimerError` whose `errorId` is `invalid-value`, before the shopper sees any payment method. |

> [!WARNING]
>
> The `.manual` case exists because `PrimerSettings` is shared with the Drop-In and Headless SDKs. Primer Checkout does not support it, and the checkout fails at start. To pass an idempotency key or to abort a payment before the SDK creates it, use `idempotencyKey` or `onBeforePaymentCreate` on [`PrimerCheckoutSession`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session).

See [Handle the payment result](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/guides/handle-payment-result.md) for how results reach your app.

***

## PrimerLocaleData

Sets the locale that formats amounts, instead of the device locale. The SDK also sends its `localeCode` with Klarna, redirect, QR code, form redirect and Stripe ACH payment requests. It does not change the language of the SDK's own UI text, which follows the app's language.

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

> [!NOTE]
>
> If you pass only `languageCode`, `regionCode` is `nil` and `localeCode` is the language code alone, for example `"de"`. Pass `regionCode` as well to get a `language-region` code.

***

## PrimerPaymentMethodOptions

Payment method-specific configuration. Set `urlScheme` for flows that leave your app and return to it: PayPal, redirect-based payment methods, Adyen Klarna and Stripe ACH. Without a valid scheme, these flows fail with a `PrimerError` whose `errorId` is `invalid-value`. 3D Secure returns to your app through `threeDsOptions.threeDsAppRequestorUrl` instead.

```swift theme={"dark"}
public final class PrimerPaymentMethodOptions: Codable {
    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 for recurring Klarna sessions. Not needed for Klarna payments in Primer Checkout, which creates one-off Klarna sessions. |
| `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: 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
    )
}

public enum CardType: String, Codable {
    case credit, debit
}
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `merchantIdentifier` | `String` | — | Your Apple Pay merchant identifier (for example `"merchant.com.myapp"`). |
| `merchantName` | `String?` | — | Fallback merchant name for the Apple Pay sheet. The merchant name from the [client session](https://primer.io/docs/checkout/client-session.md) takes precedence. Pass `nil` if the client session provides it. |
| `isCaptureBillingAddressEnabled` | `Bool` | `false` | When `true` and `billingOptions` sets no fields, the sheet requests the billing postal address. Use `billingOptions` to configure required billing fields. |
| `showApplePayForUnsupportedDevice` | `Bool` | `true` | Not used by Primer Checkout. Apple Pay is always listed when it is configured. On a device that cannot pay, selecting it shows an "Apple Pay Unavailable" screen. |
| `checkProvidedNetworks` | `Bool` | `true` | Whether to verify the device can pay using the provided networks before presenting Apple Pay. |
| `shippingOptions` | `ShippingOptions?` | `nil` | Extra shipping contact fields to request on the Apple Pay sheet. `requireShippingMethod` has no effect in Primer Checkout. |
| `billingOptions` | `BillingOptions?` | `nil` | Required billing contact fields. |
| `allowedCardTypes` | `[CardType]?` | `nil` | Card funding types the Apple Pay sheet offers (`.credit`, `.debit`). `nil` or empty allows all types. |

`PrimerApplePayOptions.ShippingOptions` and `PrimerApplePayOptions.BillingOptions` are nested types that set the contact fields the Apple Pay sheet asks for. When the Express Checkout shipping handlers run, the SDK requests the postal address itself. Use `ShippingOptions` only to request extra shipping contact fields.

```swift theme={"dark"}
public final class PrimerApplePayOptions: Codable {
    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](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/guides/apple-pay-integration.md) for end-to-end setup.

### PrimerKlarnaOptions

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

| Parameter | Type | Description |
| - | - | - |
| `recurringPaymentDescription` | `String` | Description sent for recurring Klarna sessions. Primer Checkout creates one-off Klarna payments and does not read it. |

### 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 shown before the shopper confirms. Required for Stripe ACH: without it, the ACH payment fails at the mandate step. Use `.templateMandate(merchantName:)` for the standard template, or `.fullMandate(text:)` for your own text. |

### PrimerThreeDsOptions

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

| Parameter | Type | Default | Description |
| - | - | - | - |
| `threeDsAppRequestorUrl` | `String?` | `nil` | URL that an out-of-band 3DS challenge, such as a banking app, uses to return to your app. Must start with `https`, typically a universal link of your app. Set it through `paymentMethodOptions.threeDsOptions`. Used for 3DS protocol versions above 2.1. Without a usable URL, the SDK logs a warning and the challenge cannot redirect back. |

***

## PrimerUIOptions

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

```swift theme={"dark"}
public final class PrimerUIOptions: Codable {
    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` | Managed checkout only (`PrimerCheckout`, `PrimerCheckoutPresenter`). Shows the splash screen while payment methods load, and holds it for at least 0.5 s. With `false`, the SDK skips the pause and shows an empty screen while payment methods load. The splash screen always shows while the SDK initializes. The inline `.primerCheckoutSession` integration never shows a splash and never pauses. |
| `isSuccessScreenEnabled` | `Bool?` | `true` | Shows a success screen after the payment completes. |
| `isErrorScreenEnabled` | `Bool?` | `true` | Shows the SDK error screen when a payment or the checkout initialization fails. After a failed payment attempt the screen offers a retry and can offer to choose another payment method. A failed initialization shows a retry. A failure before any payment attempt, such as a load failure, shows no retry. With `false`, the SDK shows no error view. It reports the failure only through `onCompletion` as `.failure`. With `PrimerCheckoutPresenter`, it reports through `primerCheckoutPresenterDidFailWithError(_:checkoutData:)` and closes the sheet. |
| `dismissalMechanism` | `[DismissalMechanism]?` | `[.gestures]` | How the user can dismiss the checkout modal. |
| `cardFormUIOptions` | `PrimerCardFormUIOptions?` | `nil` | Card form-specific UI options. |
| `appearanceMode` | `PrimerAppearanceMode?` | `.system` | Sets the color scheme of the SDK UI. With `.light` or `.dark`, the SDK screens, sheets, and design tokens use that scheme. Light mode reads `colors` from `PrimerCheckoutTheme`, and dark mode reads `darkColors`. With the inline `.primerCheckoutSession` modifier, your own views keep their color scheme. With `.system`, the SDK follows the color scheme of the host view. Klarna's payment view also follows this setting. |
| `theme` | `PrimerTheme?` | `PrimerTheme()` | Drop-In theme. Primer Checkout ignores it. Style the checkout with [`PrimerCheckoutTheme`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/primer-theme), passed as `primerTheme:` on `PrimerCheckout` / `PrimerCheckoutPresenter` or `theme:` on `.primerCheckoutSession`. |

### DismissalMechanism

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

| Case | Description |
| - | - |
| `.gestures` | Lets the shopper swipe down to dismiss the sheet that `PrimerCheckoutPresenter` presents, and shows the sheet's grabber. Without it, the presenter hides the grabber and disables the swipe. This option has no effect when you present `PrimerCheckout` or the inline flow in your own SwiftUI sheet. The SDK blocks swipe dismissal while the processing screen is shown. |
| `.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 color scheme of the host view, which is the device appearance setting unless your app overrides it. 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 button of the SDK card form screen reads "Add card" instead of "Pay". This applies in `PrimerCheckout`, `PrimerCheckoutPresenter` and the sheet that `.primerCheckoutSession` opens for card. The button of a composable `PrimerCardForm` is not affected. |

***

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

> [card] [PrimerCheckout](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout.md)
>
> The managed checkout view that accepts these settings

> [card] [PrimerCheckoutPresenter](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-presenter.md)
>
> Present checkout from UIKit with PrimerSettings

> [card] [PrimerError](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-error.md)
>
> Error type surfaced through the completion handler

> [card] [PrimerCheckoutTheme](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/primer-theme.md)
>
> Theme the checkout UI with design tokens via primerTheme


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