Skip to main content
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
    )
}
ParameterTypeDefaultDescription
paymentHandlingPrimerPaymentHandling.autoControls whether the SDK creates the payment automatically or returns a token for server-side processing.
localeDataPrimerLocaleData?nilForces the SDK locale for translations and formatting. Defaults to the device locale.
paymentMethodOptionsPrimerPaymentMethodOptions?nilPayment method-specific configuration (Apple Pay, Klarna, 3DS, Stripe ACH, redirect scheme).
uiOptionsPrimerUIOptions?nilUI behavior settings: which screens are shown, dismissal mechanisms, appearance mode, and theme.
threeDsOptionsPrimerThreeDsOptions?nil3D Secure configuration. Can also be set inside paymentMethodOptions.
debugOptionsPrimerDebugOptions?nilDebug and development options.
clientSessionCachingEnabledBoolfalseCaches client session data to reduce network requests.
apiVersionPrimerApiVersion.V2_4Primer 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"
}
CaseDescription
.autoThe SDK creates the payment after tokenization. The simplest integration. Results are delivered through the completion handler. Recommended.
.manualAfter 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)
}
PropertyTypeDescription
languageCodeStringISO 639-1 language code (for example "en", "de", "fr"). Defaults to the device language.
localeCodeStringCombined language-region code (for example "en-US"). Computed from the language and region codes.
regionCodeString?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
    )
}
ParameterTypeDefaultDescription
urlSchemeString?nilDeep link scheme for returning from third-party apps (for example "myapp://primer"). Must be a valid URL scheme.
applePayOptionsPrimerApplePayOptions?nilApple Pay configuration. Required when using Apple Pay.
klarnaOptionsPrimerKlarnaOptions?nilKlarna configuration. Required when using Klarna.
threeDsOptionsPrimerThreeDsOptions?nil3D Secure configuration.
stripeOptionsPrimerStripeOptions?nilStripe 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
    )
}
ParameterTypeDefaultDescription
merchantIdentifierStringYour Apple Pay merchant identifier (for example "merchant.com.myapp").
merchantNameString?Deprecated. Provide the merchant name through the client session instead.
isCaptureBillingAddressEnabledBoolfalseDeprecated. Use billingOptions to configure required billing fields instead.
showApplePayForUnsupportedDeviceBooltrueWhen false, hides Apple Pay on devices that do not support it.
checkProvidedNetworksBooltrueWhether to verify the device can pay using the provided networks before presenting Apple Pay.
shippingOptionsShippingOptions?nilShipping contact requirements.
billingOptionsBillingOptions?nilRequired 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)
}
ParameterTypeDescription
recurringPaymentDescriptionStringDescription 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)
}
ParameterTypeDefaultDescription
publishableKeyStringStripe publishable key.
mandateDataMandateData?nilACH 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)
}
ParameterTypeDefaultDescription
threeDsAppRequestorUrlString?nilApp 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
    )
}
ParameterTypeDefaultDescription
isInitScreenEnabledBool?trueShows a loading screen while the checkout initializes.
isSuccessScreenEnabledBool?trueShows a success screen after the payment completes.
isErrorScreenEnabledBool?trueShows an error screen when a payment fails.
dismissalMechanism[DismissalMechanism]?[.gestures]How the user can dismiss the checkout modal.
cardFormUIOptionsPrimerCardFormUIOptions?nilCard form-specific UI options.
appearanceModePrimerAppearanceMode?.systemAppearance mode for the UI.
themePrimerTheme?PrimerTheme()Visual theme for all SDK components. See PrimerTheme.

DismissalMechanism

public enum DismissalMechanism: String, Codable {
    case gestures = "GESTURES"
    case closeButton = "CLOSE_BUTTON"
}
CaseDescription
.gesturesDismiss the modal with swipe-down gestures.
.closeButtonDisplay a close button in the navigation area.

PrimerAppearanceMode

public enum PrimerAppearanceMode: String, Codable {
    case system = "SYSTEM"
    case light = "LIGHT"
    case dark = "DARK"
}
CaseDescription
.systemFollows the device appearance setting. Default.
.lightForces light appearance.
.darkForces dark appearance.

PrimerCardFormUIOptions

public struct PrimerCardFormUIOptions: Codable {
    public let payButtonAddNewCard: Bool

    public init(payButtonAddNewCard: Bool = false)
}
ParameterTypeDefaultDescription
payButtonAddNewCardBoolfalseWhen true, the card form button shows “Add new card” instead of “Pay $X.XX”.

PrimerDebugOptions

public struct PrimerDebugOptions: Codable {
    public init(is3DSSanityCheckEnabled: Bool? = nil)
}
ParameterTypeDefaultDescription
is3DSSanityCheckEnabledBool?trueEnables 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
}
CaseDescription
V2_4Primer API version 2.4 (latest).

See also

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