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

> [!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.

## Definition

```kotlin theme={"dark"}
@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`](https://primer.io/docs/sdk/android-checkout/v3.0.0-beta/api/common/primer-error) | 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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.