PrimerCheckoutSheet

Modal bottom sheet composable with built-in navigation and customizable screen slots

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

Modal bottom sheet composable with built-in navigation between screens (splash, loading, payment methods, card form, success, error). Each screen is a slot parameter you can override.

Signature

@Composable
fun PrimerCheckoutSheet(
    checkout: PrimerCheckoutController,
    modifier: Modifier = Modifier,
    onDismiss: () -> Unit = {},
    theme: PrimerTheme = PrimerTheme(),
    splash: @Composable () -> Unit = { PrimerCheckoutSheetDefaults.Splash() },
    loading: @Composable () -> Unit = { PrimerCheckoutSheetDefaults.Loading() },
    paymentMethodSelection: @Composable () -> Unit = {
        PrimerCheckoutSheetDefaults.PaymentMethodSelection(checkout)
    },
    cardForm: @Composable () -> Unit = {
        val controller = rememberCardFormController(checkout)
        PrimerCardForm(controller = controller)
    },
    success: @Composable (PrimerCheckoutData) -> Unit = { data ->
        PrimerCheckoutSheetDefaults.Success(data)
    },
    error: @Composable (PrimerError) -> Unit = { error ->
        PrimerCheckoutSheetDefaults.Error(error)
    },
    beforePaymentCreate: (@Composable (handler: PrimerPaymentCreationDecisionHandler) -> Unit)? = null,
)

There is no onEvent callback. The built-in success / error slots render the in-sheet result screens; to react programmatically (navigate, log, refresh your cart), observe checkout.state for PrimerCheckoutState.Success / PrimerCheckoutState.Failure.

Parameters

Parameter	Type	Default	Description
checkout	PrimerCheckoutController	Required	Checkout controller that drives the sheet lifecycle
modifier	Modifier	Modifier	Modifier applied to the bottom sheet container
onDismiss	() -> Unit	{}	Called on swipe down, back press, or auto-dismiss after result screen
theme	PrimerTheme	PrimerTheme()	Design tokens applied to all components within the sheet
splash	@Composable () -> Unit	Defaults.Splash()	Slot displayed briefly when the sheet first opens
loading	@Composable () -> Unit	Defaults.Loading()	Slot displayed during payment processing
paymentMethodSelection	@Composable () -> Unit	Defaults.PaymentMethodSelection(checkout)	Slot for payment method selection screen
cardForm	@Composable () -> Unit	PrimerCardForm(...)	Slot for card payment form screen
success	@Composable (PrimerCheckoutData) -> Unit	Defaults.Success(data)	Slot after successful payment. Auto-dismisses after 3 seconds.
error	@Composable (PrimerError) -> Unit	Defaults.Error(error)	Slot after payment failure. Shows retry and “try other methods” options.
beforePaymentCreate	(@Composable (PrimerPaymentCreationDecisionHandler) -> Unit)?	null	Optional gate shown right before payment creation — run last-minute checks or set an idempotency key, then call handler.continuePaymentCreation(idempotencyKey) or handler.abortPaymentCreation(message). Omit to let the SDK proceed automatically.

PrimerCheckoutSheetDefaults

Pre-built composable implementations for each screen slot.

object PrimerCheckoutSheetDefaults {
    @Composable fun Splash()
    @Composable fun Loading()
    @Composable fun Success(checkoutData: PrimerCheckoutData)
    @Composable fun Error(error: PrimerError)
    @Composable fun PaymentMethodSelection(checkout: PrimerCheckoutController)
    @Composable fun VaultedMethods(checkout: PrimerCheckoutController)
    @Composable fun PaymentMethods(checkout: PrimerCheckoutController)
}

Function	Description
Splash()	Brief splash screen with Primer logo and loading animation
Loading()	Centered circular progress indicator during payment processing
Success(checkoutData)	Checkmark animation and payment confirmation. Auto-dismisses after 3 seconds.
Error(error)	Error message with retry and “try other methods” options
PaymentMethodSelection(checkout)	Vaulted methods (if any) + available payment methods
VaultedMethods(checkout)	Saved payment methods section only
PaymentMethods(checkout)	Available payment methods section only (excluding vaulted)

PrimerCheckoutSheet vs PrimerCheckoutHost

Feature	PrimerCheckoutSheet	PrimerCheckoutHost
Presentation	Modal bottom sheet	Inline in your layout
Navigation	Built-in screen transitions	You manage navigation
Dismissal	Swipe, back press, auto-dismiss	You control visibility
Success/error screens	Built-in slots (customizable)	You build your own
3DS/redirect flows	Handled within the sheet	Overlay sheet appears on top