iOS SDK PrimerSettings

Primer’s SDK will need to be configured with a PrimerSettings object, no matter whether you’re using the drop-in or headless integration, auto or manual flow. This object greatly depends on your payment methods configuration.

Parameters

Hide Properties

paymentHandling

enum PrimerPaymentHandling

Use this to set you payment handling flow. Defaults to .auto.

Hide Cases

auto

default

Primer SDK will create the payment and handle the flow.

manual

If you use the manual flow, make sure you add the primerDidTokenizePaymentMethod(_:decisionHandler:) delegate function of PrimerDelegate, create a payment on your backend and call the decisionHandler of the delegate function once you receive your backend’s response.

localeData

PrimerLocaleData

Forces some payment methods’ locale.

Hide Properties

languageCode

String

required

Forces the language code (e.g. en). Defaults on your app’s language code if available.

regionCode

String

Forces the language code (e.g. US). Defaults on your app’s region code if available.

paymentMethodOptions

PrimerPaymentMethodOptions

Hide Properties

urlScheme

String

⚠️ Required for some payment methods (e.g. PayPal).

This option sets the deeplink schema used when redirecting back from 3rd party applications to your app.

applePayOptions

PrimerApplePayOptions

⚠️ Required when using Apple Pay in your integration.

Hide Properties

merchantIdentifier

String

required

Set it to the merchant identifier as it is shown in your Apple Pay certificate.

merchantName

String

deprecated

Set it to the merchant name that you want to be shown on the Apple Pay screen. Deprecated, use ClientSession instead.

isCaptureBillingAddressEnabled

Bool

Defaults to false. Set to true to let Apple Pay capture the customer’s billing address.Use BillingOptions to configure required billing fields.

showApplePayForUnsupportedDevice

Bool

If in some cases you don’t want to present ApplePay option if the device is not supporting it set this to false. The default value is true.Default value is true. Set to false if you do not want to present Apple Pay option on unsupported devices.

checkProvidedNetworks

Bool

Flag introduced to enable the initiation of the ApplePay flow even when no cards are present in the Wallet. To enable the feature, set this to false. The default value true.Default value is true. This flag supports the old behavior where Apple Pay flow might not present if there are no cards in the Wallet.

shippingOptions

ShippingOptions

Configure shipping options for Apple Pay.

Hide Properties

shippingContactFields

Array of RequiredContactField

Specify which contact fields are required for shipping.

requireShippingMethod

Bool

Indicate if a shipping method is required.

billingOptions

BillingOptions

Configure billing options for Apple Pay.

Hide Properties

requiredBillingContactFields

Array of RequiredContactField

Specify which contact fields are required for billing.

klarnaOptions

PrimerKlarnaOptions

⚠️ Required when using Klarna in your integration.

Hide Properties

recurringPaymentDescription

String

required

Set the payment description that will be shown on the Klarna screen.

threeDsOptions

PrimerThreeDsOptions

Hide Properties

threeDsAppRequestorUrl

String

Set the iOS Universal Link that’s used to call your app after an out-of-band (OOB) authentication. Supported in 3D Secure protocol versions 2.2.0 and after.

stripeOptions

PrimerStripeOptions

⚠️ Required when using Stripe ACH in your integration.

Hide Properties

publishableKey

String?

Set the Stripe publishable key.

mandateData

MandateData?

One of:

Hide Options

fullMandate(text:)

MandateData

The full text that you would like to be displayed to the user before they accept/decline the mandate.

templateMandate(merchantName:)

MandateData

A merchantName that will be used as part of our predefined mandate template.

uiOptions

PrimerUIOptions

Set the uiOptions for custom UI options of the Primer SDK.

Hide Properties

isInitScreenEnabled

Bool

Set to false to hide the loading screen before the Universal Checkout or the Vault Manager. Defaults to true.

isSuccessScreenEnabled

Bool

Set to false to hide the screen after a successful payment, or tokenization on the vault flow. Defaults to true.

isErrorScreenEnabled

Bool

Set to false to hide the error screen when an error occurs. Defaults to true.

dismissalMechanism

enum DismissalMechanism

Set the mechanism for dismissing Universal Checkout. Options are:

gestures: The dialog can be dismissed by tapping outside or by swiping down.
closeButton: A close button is provided, allowing users to dismiss the dialog manually.

theme

PrimerTheme

Set a custom theme for Primer SDK.

appearanceMode

enum PrimerAppearanceMode

Control the SDK’s appearance mode independently of the system setting. This allows apps to force light or dark mode regardless of the device’s appearance setting.

Hide Cases

system

default

Follow the system’s appearance setting (default behavior).

light

Force light mode appearance regardless of system setting.

dark

Force dark mode appearance regardless of system setting.

cardFormUIOptions

PrimerCardFormUIOptions?

Configure the card form UI options.

Hide Properties

payButtonAddNewCard

Bool

When set to true, the Drop-In’s card form pay button will show “Add new card”; otherwise it will show “Pay $x.xx”.

debugOptions

PrimerDebugOptions

Hide Properties

is3DSSanityCheckEnabled

Bool

required

clientSessionCachingEnabled

Bool

Default: false

Before enabling the flag to true it’s recommended to reach out to Primer support for additional verification since there are edge cases where it’s not advised.

Indicates whether client session caching is enabled.When set to true, responses from the server will be cached on the client side, allowing for faster subsequent access to the same data within the cache duration. When set to false, every request to the server will be processed without utilizing any client-side cache, ensuring that the client always receives the most up-to-date data.

apiVersion

PrimerApiVersion

Default: PrimerApiVersion.V2_4

Indicates the API version to use when interacting with the Primer backend. Options are:

PrimerApiVersion.V2_4 - will use ApiVersion 2.4

Note that this is optional, if a value is not supplied, ApiVersion V2.4 will be used by default.

Example

Create a settings object.

SWIFT

// 👇 Add this
import PrimerSDK

class MyViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        // 👇 Create your settings
        let settings = PrimerSettings(
            paymentHandling: .auto,
            localeData: PrimerLocaleData(
                languageCode: "en",
                regionCode: "US"),
            paymentMethodOptions: PrimerPaymentMethodOptions(
                urlScheme: "URL_SCHEME://",
                applePayOptions: PrimerApplePayOptions(
                    merchantIdentifier: "MERCHANT_IDENTIFIER",
                    merchantName: "MERCHANT_NAME",
                    isCaptureBillingAddressEnabled: true,
                    showApplePayForUnsupportedDevice: true,
                    checkProvidedNetworks: true,
                    shippingOptions: PrimerApplePayOptions.ShippingOptions(
                        shippingContactFields: [.name, .emailAddress],
                        requireShippingMethod: true
                    ),
                    billingOptions: PrimerApplePayOptions.BillingOptions(
                        requiredBillingContactFields: [.postalAddress]
                    )
                ),
                klarnaOptions: PrimerKlarnaOptions(
                    recurringPaymentDescription: "RECURRING_PAYMENT_DESCRIPTION"),
                stripeOptions: PrimerStripeOptions(
                    publishableKey: "STRIPE_PUBLISHABLE_KEY")),
            uiOptions: PrimerUIOptions(
                isInitScreenEnabled: false,
                isSuccessScreenEnabled: false,
                isErrorScreenEnabled: false,
                appearanceMode: .light), // Force light mode regardless of system setting
            debugOptions: PrimerDebugOptions(is3DSSanityCheckEnabled: false),
            clientSessionCachingEnabled: false)
    }
}

Appearance Mode Configuration

You can control the SDK’s appearance mode independently of the system setting using the appearanceMode property in PrimerUIOptions. This is particularly useful for apps that implement their own theme management.

SWIFT

// Force light mode regardless of system setting
let uiOptions = PrimerUIOptions(
    appearanceMode: .light  // Options: .system (default), .light, .dark
)

let settings = PrimerSettings(
    paymentHandling: .auto,
    uiOptions: uiOptions
)

// Configure Primer with the settings
Primer.shared.configure(settings: settings, delegate: self)

This feature is especially helpful when:

Your app has a “Always Light” or “Always Dark” mode setting
You want to maintain consistent appearance across the payment flow
You need to override the system’s dark mode setting for specific user preferences

iOS SDK

​Parameters

​Example

​Appearance Mode Configuration

Parameters

Example

Appearance Mode Configuration