PrimerCheckoutController

Main checkout session controller for state observation and session management

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

Central interface for managing a checkout session. Create with rememberPrimerCheckoutController().

Creation

@Composable
fun rememberPrimerCheckoutController(
    clientToken: String,
    settings: PrimerSettings = PrimerSettings(),
): PrimerCheckoutController

Parameter	Type	Default	Description
clientToken	String	Required	Short-lived token from the Client Session API
settings	PrimerSettings	PrimerSettings()	SDK configuration including payment handling mode

Interface

@Stable
interface PrimerCheckoutController {
    val state: StateFlow<PrimerCheckoutState>
    fun refresh()
    fun dismiss()
}

Property

Property	Type	Description
state	StateFlow<PrimerCheckoutState>	Unified checkout state — session lifecycle plus terminal payment outcomes (Success / Failure). Collect with collectAsStateWithLifecycle(). See PrimerCheckoutState.

Methods

Method	Description
refresh()	Reinitializes the checkout session. State transitions back to Loading while refetching configuration.
dismiss()	Programmatically dismisses the checkout UI. Closes the bottom sheet or triggers cleanup for inline host.

Idempotency key

Set the X-Idempotency-Key header from the beforePaymentCreate gate on PrimerCheckoutSheet or PrimerCheckoutHost. The gate runs once per attempt — just before the SDK creates the payment — and the value you pass to continuePaymentCreation(idempotencyKey) is sent on POST /payments and every subsequent POST /payments/{id}/resume for that attempt. A retry after failure runs the gate again, producing a fresh key.

val checkout = rememberPrimerCheckoutController(clientToken, settings)

PrimerCheckoutSheet(
    checkout = checkout,
    beforePaymentCreate = { handler ->
        LaunchedEffect(Unit) {
            handler.continuePaymentCreation(idempotencyKey = UUID.randomUUID().toString())
        }
    },
)

Extension function

formatAmount

fun PrimerCheckoutController.formatAmount(amountInCents: Int): String

Formats an amount in minor units (cents) into a locale-aware currency string based on the current session (e.g., "$10.00", "10,00 EUR").

Parameter	Type	Description
amountInCents	Int	Amount in minor currency units (e.g., 1000 for $10.00 USD)