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

> Configuration class for SDK behavior, UI options, and payment method settings

<Warning>
  Primer Checkout Android SDK is currently in **beta** (v3.0.0-beta.4).
  The API is subject to change before the stable release.
</Warning>

Configuration class for SDK behavior. Pass to `rememberPrimerCheckoutController()`.

## Definition

```kotlin theme={"dark"}
data class PrimerSettings(
    var paymentHandling: PrimerPaymentHandling = PrimerPaymentHandling.AUTO,
    var locale: Locale = Locale.getDefault(),
    var paymentMethodOptions: PrimerPaymentMethodOptions = PrimerPaymentMethodOptions(),
    var uiOptions: PrimerUIOptions = PrimerUIOptions(),
    var debugOptions: PrimerDebugOptions = PrimerDebugOptions(),
    var clientSessionCachingEnabled: Boolean = false,
    var apiVersion: PrimerApiVersion = PrimerApiVersion.V2_4,
)
```

| Property                      | Type                         | Default                        | Description                                                                           |
| ----------------------------- | ---------------------------- | ------------------------------ | ------------------------------------------------------------------------------------- |
| `paymentHandling`             | `PrimerPaymentHandling`      | `AUTO`                         | Controls whether the SDK processes payments automatically or delegates to your server |
| `locale`                      | `Locale`                     | `Locale.getDefault()`          | Forces the SDK locale for translations and formatting                                 |
| `paymentMethodOptions`        | `PrimerPaymentMethodOptions` | `PrimerPaymentMethodOptions()` | Payment method-specific configuration (Google Pay, Klarna, 3DS, Stripe)               |
| `uiOptions`                   | `PrimerUIOptions`            | `PrimerUIOptions()`            | UI behavior settings (screens, dismissal, theming)                                    |
| `debugOptions`                | `PrimerDebugOptions`         | `PrimerDebugOptions()`         | Debug and development options                                                         |
| `clientSessionCachingEnabled` | `Boolean`                    | `false`                        | Caches the client session to reduce network requests                                  |
| `apiVersion`                  | `PrimerApiVersion`           | `V2_4`                         | Primer API version used for backend communication                                     |

## Usage

```kotlin theme={"dark"}
val settings = PrimerSettings(
    locale = Locale.GERMANY,
    uiOptions = PrimerUIOptions(
        isInitScreenEnabled = false,
        dismissalMechanism = listOf(DismissalMechanism.CLOSE_BUTTON),
    ),
    paymentMethodOptions = PrimerPaymentMethodOptions(
        redirectScheme = "myapp://primer",
        googlePayOptions = PrimerGooglePayOptions(
            merchantName = "My Store",
            captureBillingAddress = true,
        ),
    ),
)

val checkout = rememberPrimerCheckoutController(
    clientToken = clientToken,
    settings = settings,
)
```

***

## PrimerUIOptions

Controls checkout UI behavior: which screens are shown, how the sheet is dismissed, and theming.

```kotlin theme={"dark"}
data class PrimerUIOptions(
    var isInitScreenEnabled: Boolean = true,
    var isSuccessScreenEnabled: Boolean = true,
    var isErrorScreenEnabled: Boolean = true,
    var dismissalMechanism: List<DismissalMechanism> = listOf(DismissalMechanism.GESTURES),
    var theme: PrimerTheme = PrimerTheme(),
    var cardFormUIOptions: PrimerCardFormUIOptions = PrimerCardFormUIOptions(),
)
```

| Property                 | Type                       | Default                     | Description                                           |
| ------------------------ | -------------------------- | --------------------------- | ----------------------------------------------------- |
| `isInitScreenEnabled`    | `Boolean`                  | `true`                      | Shows a loading screen while the checkout initializes |
| `isSuccessScreenEnabled` | `Boolean`                  | `true`                      | Shows a success screen after payment completes        |
| `isErrorScreenEnabled`   | `Boolean`                  | `true`                      | Shows an error screen when a payment fails            |
| `dismissalMechanism`     | `List<DismissalMechanism>` | `[GESTURES]`                | How the user can dismiss the checkout sheet           |
| `theme`                  | `PrimerTheme`              | `PrimerTheme.build()`       | Visual theme for all SDK components                   |
| `cardFormUIOptions`      | `PrimerCardFormUIOptions`  | `PrimerCardFormUIOptions()` | Card form-specific UI options                         |

### DismissalMechanism

| Value          | Description                                |
| -------------- | ------------------------------------------ |
| `GESTURES`     | Dismiss by tapping outside or swiping down |
| `CLOSE_BUTTON` | Shows a close button in the sheet header   |

### PrimerCardFormUIOptions

| Property              | Type      | Default | Description                                                                    |
| --------------------- | --------- | ------- | ------------------------------------------------------------------------------ |
| `payButtonAddNewCard` | `Boolean` | `false` | When `true`, the card form button shows "Add new card" instead of "Pay \$X.XX" |

***

## PrimerPaymentMethodOptions

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

```kotlin theme={"dark"}
data class PrimerPaymentMethodOptions(
    var redirectScheme: String? = null,
    var googlePayOptions: PrimerGooglePayOptions = PrimerGooglePayOptions(),
    var klarnaOptions: PrimerKlarnaOptions = PrimerKlarnaOptions(),
    var threeDsOptions: PrimerThreeDsOptions = PrimerThreeDsOptions(),
    var stripeOptions: PrimerStripeOptions = PrimerStripeOptions(),
)
```

| Property           | Type                     | Default                    | Description                                                                     |
| ------------------ | ------------------------ | -------------------------- | ------------------------------------------------------------------------------- |
| `redirectScheme`   | `String?`                | `null`                     | Deep link scheme for returning from third-party apps (e.g., `"myapp://primer"`) |
| `googlePayOptions` | `PrimerGooglePayOptions` | `PrimerGooglePayOptions()` | Google Pay configuration. Required when using Google Pay.                       |
| `klarnaOptions`    | `PrimerKlarnaOptions`    | `PrimerKlarnaOptions()`    | Klarna configuration. Required when using Klarna.                               |
| `threeDsOptions`   | `PrimerThreeDsOptions`   | `PrimerThreeDsOptions()`   | 3D Secure configuration                                                         |
| `stripeOptions`    | `PrimerStripeOptions`    | `PrimerStripeOptions()`    | Stripe ACH configuration. Required when using Stripe ACH.                       |

### PrimerGooglePayOptions

| Property                        | Type                                     | Default | Description                                                  |
| ------------------------------- | ---------------------------------------- | ------- | ------------------------------------------------------------ |
| `merchantName`                  | `String?`                                | `null`  | Merchant name displayed in the Google Pay sheet              |
| `buttonStyle`                   | `GooglePayButtonStyle`                   | —       | Button appearance: `WHITE` or `BLACK`                        |
| `captureBillingAddress`         | `Boolean`                                | `false` | Requests billing address from Google Pay                     |
| `existingPaymentMethodRequired` | `Boolean`                                | `false` | Only shows Google Pay if the user has a saved payment method |
| `shippingAddressParameters`     | `PrimerGoogleShippingAddressParameters?` | `null`  | Shipping address requirements (has `phoneNumberRequired`)    |
| `requireShippingMethod`         | `Boolean`                                | `false` | Requires a shipping method selection                         |
| `emailAddressRequired`          | `Boolean`                                | `false` | Requests email from Google Pay                               |
| `buttonOptions`                 | `GooglePayButtonOptions`                 | —       | Button customization (`buttonTheme`, `buttonType`)           |

### PrimerKlarnaOptions

| Property                      | Type      | Default | Description                                     |
| ----------------------------- | --------- | ------- | ----------------------------------------------- |
| `recurringPaymentDescription` | `String?` | `null`  | Description shown for recurring Klarna payments |
| `returnIntentUrl`             | `String?` | `null`  | Return URL after Klarna authorization           |

### PrimerThreeDsOptions

| Property                 | Type      | Default | Description                               |
| ------------------------ | --------- | ------- | ----------------------------------------- |
| `threeDsAppRequestorUrl` | `String?` | `null`  | App requestor URL for 3DS2 authentication |

### PrimerStripeOptions

| Property         | Type           | Default | Description                                                                                                                                                                 |
| ---------------- | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mandateData`    | `MandateData?` | `null`  | ACH mandate text. Use `TemplateMandateData(merchantName)` for a standard template, or `FullMandateStringData(value)` / `FullMandateData(@StringRes value)` for custom text. |
| `publishableKey` | `String?`      | `null`  | Stripe publishable key                                                                                                                                                      |

***

## PrimerDebugOptions

| Property                  | Type      | Default | Description                                                          |
| ------------------------- | --------- | ------- | -------------------------------------------------------------------- |
| `is3DSSanityCheckEnabled` | `Boolean` | `true`  | Enables 3DS security sanity checks. Disable only during development. |

***

## PrimerPaymentHandling

| Value  | Description                                                            |
| ------ | ---------------------------------------------------------------------- |
| `AUTO` | SDK processes payment end-to-end. Emits `Success` or `Failure` events. |

***

## PrimerApiVersion

| Value  | Description                     |
| ------ | ------------------------------- |
| `V2_4` | Primer API version 2.4 (latest) |