> ## 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.8).
> The API is subject to change before the stable release.

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` | Asks the shopper for a shipping address in the Google Pay sheet (has `phoneNumberRequired`). When you register `onShippingAddressChange` ([Express Checkout shipping](https://primer.io/docs/checkout/primer-checkout/guides-and-recipes/express-checkout-shipping.md)), the SDK asks for the address itself, and this only adds the phone number. |
| `requireShippingMethod` | `Boolean` | `false` | Not needed with the [Express Checkout shipping](https://primer.io/docs/checkout/primer-checkout/guides-and-recipes/express-checkout-shipping.md) handlers. When you register `onShippingAddressChange`, the SDK ignores this setting. Registering `onShippingOptionChange` as well shows the shipping method selector. If you set this to `true` without `onShippingAddressChange`, the sheet has no shipping options to show, and the SDK logs a warning. |
| `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) |


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