> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

**Properties**

**paymentHandling** `enum PrimerPaymentHandling`

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

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

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

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

**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](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/create-a-client-session.md) 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.

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

**Properties**

**requiredBillingContactFields** `Array of RequiredContactField`

Specify which contact fields are required for billing.

**allowedCardTypes** `Array of CardType`

Restrict the card types Apple Pay offers. Supported values: `.credit`, `.debit`. When omitted or empty, all card types are offered.

**klarnaOptions** `PrimerKlarnaOptions`

⚠️ Required when using Klarna in your integration.

**Properties**

**recurringPaymentDescription** `String` *required*

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

**threeDsOptions** `PrimerThreeDsOptions`

**Properties**

**threeDsAppRequestorUrl** `String`

Set the [iOS Universal Link](https://developer.apple.com/ios/universal-links/) 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.

**Properties**

**publishableKey** `String?`

Set the [Stripe publishable key](https://docs.stripe.com/keys#obtain-api-keys/).

**mandateData** `MandateData?`

One of:

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

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

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

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

**Properties**

**is3DSSanityCheckEnabled** `Bool` *required*

**clientSessionCachingEnabled** `Bool`

> [!WARNING]
>
> 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`

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 SWIFT theme={"dark"}
// 👇 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 SWIFT theme={"dark"}
// 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.