PrimerSettings

Primer Checkout iOS SDK is currently in beta (v3.0.0-beta.1). 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`	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.

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

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

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 for how each mode surfaces results.

PrimerLocaleData

Forces the SDK locale instead of inheriting the device locale.

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.

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.

PrimerPaymentMethodOptions

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

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

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

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 shown for recurring Klarna payments.

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. Use `.templateMandate(merchantName:)` for a standard template, or `.fullMandate(text:)` for custom text.

PrimerThreeDsOptions

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.

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.

DismissalMechanism

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

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

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

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

PrimerTheme

Theme the checkout UI via uiOptions.theme

​Definition

​Usage

​PrimerPaymentHandling

​PrimerLocaleData

​PrimerPaymentMethodOptions

​PrimerApplePayOptions

​PrimerKlarnaOptions

​PrimerStripeOptions

​PrimerThreeDsOptions

​PrimerUIOptions

​DismissalMechanism

​PrimerAppearanceMode

​PrimerCardFormUIOptions

​PrimerDebugOptions

​PrimerApiVersion

​See also

PrimerCheckout

PrimerCheckoutPresenter

PrimerError

PrimerTheme

Definition

Usage

PrimerPaymentHandling

PrimerLocaleData

PrimerPaymentMethodOptions

PrimerApplePayOptions

PrimerKlarnaOptions

PrimerStripeOptions

PrimerThreeDsOptions

PrimerUIOptions

DismissalMechanism

PrimerAppearanceMode

PrimerCardFormUIOptions

PrimerDebugOptions

PrimerApiVersion

See also