PrimerSettings

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 or as settings: on PrimerCheckoutSession.

Definition

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

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

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

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

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.

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.

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.

See Handle the payment result 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.

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.

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.

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

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

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 for end-to-end setup.

PrimerKlarnaOptions

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

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

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.

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`, passed as `primerTheme:` on `PrimerCheckout` / `PrimerCheckoutPresenter` or `theme:` on `.primerCheckoutSession`.

DismissalMechanism

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

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

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

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

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

PrimerCheckout

The managed checkout view that accepts these settings

PrimerCheckoutPresenter

Present checkout from UIKit with PrimerSettings

PrimerError

Error type surfaced through the completion handler

PrimerCheckoutTheme

Theme the checkout UI with design tokens via primerTheme

​Definition

​Usage

​PrimerPaymentHandling

​PrimerLocaleData

​PrimerPaymentMethodOptions

​PrimerApplePayOptions

​PrimerKlarnaOptions

​PrimerStripeOptions

​PrimerThreeDsOptions

​PrimerUIOptions

​DismissalMechanism

​PrimerAppearanceMode

​PrimerCardFormUIOptions

​PrimerDebugOptions

​PrimerApiVersion

​See also

PrimerCheckout

PrimerCheckoutPresenter

PrimerError

PrimerCheckoutTheme

Definition

Usage

PrimerPaymentHandling

PrimerLocaleData

PrimerPaymentMethodOptions

PrimerApplePayOptions

PrimerKlarnaOptions

PrimerStripeOptions

PrimerThreeDsOptions

PrimerUIOptions

DismissalMechanism

PrimerAppearanceMode

PrimerCardFormUIOptions

PrimerDebugOptions

PrimerApiVersion

See also