PrimerCheckoutState

Primer Checkout Android SDK is currently in beta (v3.0.0-beta.8). 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 class Success(
        val checkoutData: PrimerCheckoutData,
    ) : PrimerCheckoutState

    data class Failure(
        val primerError: PrimerError,
        val checkoutData: PrimerCheckoutData? = null,
    ) : 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. Emitted again with the updated `clientSession` after each client-session update.
`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 properties

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

Client-session updates

When the client session changes during checkout (for example after a billing-address change or setVaultOnSuccess), the state goes from Ready with the old session to Ready with the updated one. Read totals, fees, and surcharges from Ready.clientSession. To show progress while the update is in flight, use isLoading on the card form state (rememberCardFormController(checkout).state).

Success properties

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

Failure properties

Property	Type	Description
`primerError`	`PrimerError`	Error details including description, error code, and diagnostics ID
`checkoutData`	`PrimerCheckoutData?`	Payment ID and order ID when the payment was created before failing, e.g. a decline. `null` when the failure happened before a payment existed

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.primerError)
    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

​Definition

​States

​Ready properties

​Client-session updates

​Success properties

​Failure properties

​Observing state

​PrimerClientSession

Definition

States

Ready properties

Client-session updates

Success properties

Failure properties

Observing state

PrimerClientSession