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