> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PrimerCheckoutState

> Sealed interface representing checkout session lifecycle states

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

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`.

<Note>
  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.
</Note>

## Definition

```kotlin theme={"dark"}
@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`](/docs/sdk/android-checkout/v3.0.0-beta/api/common/primer-error) | Error details including description, error code, and diagnostics ID |

## Observing state

```kotlin theme={"dark"}
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

```kotlin theme={"dark"}
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                             |