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

# PrimerCheckoutSheet

> Modal bottom sheet composable with built-in navigation and customizable screen slots

> [!WARNING]
>
> Primer Checkout Android SDK is currently in **beta** (v3.0.0-beta.8).
> The API is subject to change before the stable release.

Modal bottom sheet composable with built-in navigation between screens (splash, loading, payment methods, card form, success, error). Each screen is a slot parameter you can override.

## Signature

```kotlin theme={"dark"}
@Composable
fun PrimerCheckoutSheet(
    checkout: PrimerCheckoutController,
    modifier: Modifier = Modifier,
    onDismiss: () -> Unit = {},
    theme: PrimerTheme = PrimerTheme(),
    splash: @Composable () -> Unit = { PrimerCheckoutSheetDefaults.Splash() },
    loading: @Composable () -> Unit = { PrimerCheckoutSheetDefaults.Loading() },
    paymentMethodSelection: @Composable () -> Unit = {
        PrimerCheckoutSheetDefaults.PaymentMethodSelection(checkout)
    },
    cardForm: @Composable () -> Unit = {
        val controller = rememberCardFormController(checkout)
        PrimerCardForm(controller = controller)
    },
    success: @Composable (PrimerCheckoutData) -> Unit = { data ->
        PrimerCheckoutSheetDefaults.Success(data)
    },
    error: @Composable (PrimerError, PrimerCheckoutData?) -> Unit = { primerError, _ ->
        PrimerCheckoutSheetDefaults.Error(primerError)
    },
    beforePaymentCreate: (@Composable (handler: PrimerPaymentCreationDecisionHandler) -> Unit)? = null,
)
```

> [!NOTE]
>
> There is no `onEvent` callback. The built-in `success` / `error` slots render the
> in-sheet result screens; to react programmatically (navigate, log, refresh your
> cart), observe [`checkout.state`](https://primer.io/docs/sdk/android-checkout/v3.0.0-beta/api/primer-checkout-state)
> for `PrimerCheckoutState.Success` / `PrimerCheckoutState.Failure`.

## Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `checkout` | `PrimerCheckoutController` | Required | Checkout controller that drives the sheet lifecycle |
| `modifier` | `Modifier` | `Modifier` | Modifier applied to the bottom sheet container |
| `onDismiss` | `() -> Unit` | `{}` | Called on swipe down, back press, or auto-dismiss after result screen |
| `theme` | [`PrimerTheme`](https://primer.io/docs/sdk/android-checkout/v3.0.0-beta/api/theming/primer-theme) | `PrimerTheme()` | Design tokens applied to all components within the sheet |
| `splash` | `@Composable () -> Unit` | `Defaults.Splash()` | Slot displayed briefly when the sheet first opens |
| `loading` | `@Composable () -> Unit` | `Defaults.Loading()` | Slot displayed during payment processing |
| `paymentMethodSelection` | `@Composable () -> Unit` | `Defaults.PaymentMethodSelection(checkout)` | Slot for payment method selection screen |
| `cardForm` | `@Composable () -> Unit` | `PrimerCardForm(...)` | Slot for card payment form screen |
| `success` | `@Composable (PrimerCheckoutData) -> Unit` | `Defaults.Success(data)` | Slot after successful payment. Auto-dismisses after 3 seconds. |
| `error` | `@Composable (PrimerError, PrimerCheckoutData?) -> Unit` | `Defaults.Error(primerError)` | Slot after payment failure. Shows retry and "try other methods" options. `checkoutData` carries the payment id and order id when the payment was created before failing. |
| `beforePaymentCreate` | `(@Composable (PrimerPaymentCreationDecisionHandler) -> Unit)?` | `null` | Optional gate shown right before payment creation — run last-minute checks or set an idempotency key, then call `handler.continuePaymentCreation(idempotencyKey)` or `handler.abortPaymentCreation(message)`. Omit to let the SDK proceed automatically. |

## PrimerCheckoutSheetDefaults

Pre-built composable implementations for each screen slot.

```kotlin theme={"dark"}
object PrimerCheckoutSheetDefaults {
    @Composable fun Splash()
    @Composable fun Loading()
    @Composable fun Success(checkoutData: PrimerCheckoutData)
    @Composable fun Error(error: PrimerError)
    @Composable fun PaymentMethodSelection(checkout: PrimerCheckoutController)
    @Composable fun VaultedMethods(checkout: PrimerCheckoutController)
    @Composable fun PaymentMethods(checkout: PrimerCheckoutController)
}
```

| Function | Description |
| - | - |
| `Splash()` | Brief splash screen with Primer logo and loading animation |
| `Loading()` | Centered circular progress indicator during payment processing |
| `Success(checkoutData)` | Checkmark animation and payment confirmation. Auto-dismisses after 3 seconds. |
| `Error(error)` | Error message with retry and "try other methods" options |
| `PaymentMethodSelection(checkout)` | Vaulted methods (if any) + available payment methods |
| `VaultedMethods(checkout)` | Saved payment methods section only |
| `PaymentMethods(checkout)` | Available payment methods section only (excluding vaulted) |

## PrimerCheckoutSheet vs PrimerCheckoutHost

| Feature | PrimerCheckoutSheet | PrimerCheckoutHost |
| - | - | - |
| Presentation | Modal bottom sheet | Inline in your layout |
| Navigation | Built-in screen transitions | You manage navigation |
| Dismissal | Swipe, back press, auto-dismiss | You control visibility |
| Success/error screens | Built-in slots (customizable) | You build your own |
| 3DS/redirect flows | Handled within the sheet | Overlay sheet appears on top |


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