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

# PrimerCheckoutController

> Main checkout session controller for state observation and session management

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

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

## Creation

```kotlin theme={"dark"}
@Composable
fun rememberPrimerCheckoutController(
    clientToken: String,
    settings: PrimerSettings = PrimerSettings(),
): PrimerCheckoutController
```

| Parameter     | Type                                                                             | Default            | Description                                                               |
| ------------- | -------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------- |
| `clientToken` | `String`                                                                         | Required           | Short-lived token from the [Client Session API](/docs/checkout/client-session) |
| `settings`    | [`PrimerSettings`](/docs/sdk/android-checkout/v3.0.0-beta/api/common/primer-settings) | `PrimerSettings()` | SDK configuration including payment handling mode                         |

## Interface

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

## 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`](/docs/sdk/android-checkout/v3.0.0-beta/api/primer-checkout-sheet)
or [`PrimerCheckoutHost`](/docs/sdk/android-checkout/v3.0.0-beta/api/primer-checkout-host).
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.

```kotlin theme={"dark"}
val checkout = rememberPrimerCheckoutController(clientToken, settings)

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

## Extension function

### formatAmount

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