Primer Checkout Android SDK is currently in beta (v3.0.0-beta.2).
The API is subject to change before the stable release.
Configuration class for SDK behavior. Pass to rememberPrimerCheckoutController().
Definition
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
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.
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 |
| 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).
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) |