Primer Checkout Android SDK is currently in beta (v3.0.0-beta.8).
The API is subject to change before the stable release.
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 |
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. SetredirectScheme 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 | Asks the shopper for a shipping address in the Google Pay sheet (has phoneNumberRequired). When you register onShippingAddressChange (Express Checkout shipping), the SDK asks for the address itself, and this only adds the phone number. |
requireShippingMethod | Boolean | false | Not needed with the Express Checkout shipping 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) |