PrimerCheckoutState

Sealed interface representing checkout session lifecycle states

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

Single observable snapshot of the checkout session. Covers the session lifecycle (Loading / Ready), client-session updates, and the terminal payment outcomes (Success / Failure). Observe via PrimerCheckoutController.state.

There is no separate event callback. Payment outcomes that earlier releases delivered through an onEvent lambda are now terminal states of this flow — observe Success and Failure here.

Definition

@Immutable
sealed interface PrimerCheckoutState {

    data object Loading : PrimerCheckoutState

    data class Ready(
        val clientSession: PrimerClientSession,
    ) : PrimerCheckoutState

    data object BeforeClientSessionUpdated : PrimerCheckoutState

    data class ClientSessionUpdated(
        val clientSession: PrimerClientSession,
    ) : PrimerCheckoutState

    data class Success(
        val checkoutData: PrimerCheckoutData,
    ) : PrimerCheckoutState

    data class Failure(
        val error: PrimerError,
    ) : PrimerCheckoutState
}

States

State	Description
Loading	SDK is initializing — fetching configuration and payment methods. Initial state and re-entered on refresh().
Ready	Checkout is fully initialized and ready for payment. Contains clientSession data.
BeforeClientSessionUpdated	The client session is about to be updated (e.g. after a billing-address change). Use it to show a loading indicator; ClientSessionUpdated fires when the update completes.
ClientSessionUpdated	The client session was updated. Contains the new clientSession — re-render totals, fees, surcharges, etc.
Success	Terminal — payment completed successfully (AUTO flow). Sticks until a new attempt starts.
Failure	Terminal — payment failed or an SDK error occurred. Sticks until a new attempt starts.

Ready / ClientSessionUpdated properties

Property	Type	Description
clientSession	PrimerClientSession	Session data containing order details, currency, and customer information

Success properties

Property	Type	Description
checkoutData	PrimerCheckoutData	Payment result containing the payment ID and order ID

Failure properties

Property	Type	Description
error	PrimerError	Error details including description, error code, and diagnostics ID

Observing state

val checkout = rememberPrimerCheckoutController(clientToken, settings)
val state by checkout.state.collectAsStateWithLifecycle()

when (val s = state) {
    is PrimerCheckoutState.Loading -> CircularProgressIndicator()
    is PrimerCheckoutState.Ready -> ShowPaymentMethods(s.clientSession)
    is PrimerCheckoutState.Success -> navigateToConfirmation(s.checkoutData)
    is PrimerCheckoutState.Failure -> showError(s.error)
    else -> Unit
}

PrimerClientSession

data class PrimerClientSession(
    val totalAmount: Int?,
    val currencyCode: String?,
    val customerId: String?,
    val orderId: String?,
)

Property	Type	Description
totalAmount	Int?	Total amount in minor currency units (e.g., 1000 = $10.00)
currencyCode	String?	ISO 4217 currency code (e.g., "USD", "EUR")
customerId	String?	Customer identifier from your system
orderId	String?	Order identifier from your system