```
**Implementation responsibility**
When using this approach:
* You must handle state management yourself through events
* You have complete freedom over the layout and user flow
* You're responsible for showing/hiding appropriate content based on checkout state
* You need to handle payment failure display, either with the `` component or by implementing custom error handling with events
Use `PrimerCheckoutHost` with a `content` lambda for full layout control. You compose child components freely inside the host.
```kotlin theme={"dark"}
val state by checkout.state.collectAsStateWithLifecycle()
PrimerCheckoutHost(checkout) {
if (state is PrimerCheckoutState.Ready) {
Column {
val vaultedController = rememberVaultedPaymentMethodsController(checkout)
PrimerVaultedPaymentMethods(vaultedController)
val paymentMethodsController = rememberPaymentMethodsController(checkout)
PrimerPaymentMethods(paymentMethodsController)
val cardFormController = rememberCardFormController(checkout)
PrimerCardForm(controller = cardFormController)
}
}
}
```
`PrimerCheckoutHost` does not have built-in error or success slots. React to outcomes by observing `checkout.state`:
```kotlin theme={"dark"}
val state by checkout.state.collectAsStateWithLifecycle()
LaunchedEffect(state) {
when (val s = state) {
is PrimerCheckoutState.Success -> showSuccessScreen(s.checkoutData)
is PrimerCheckoutState.Failure -> showErrorScreen(s.error)
else -> Unit
}
}
```
3DS and redirect flows are handled automatically via an internal overlay inside the host.
For full layout control, hold a `PrimerCheckoutSession` and compose the SDK's views inside your own layout, wiring them in with the `.primerCheckoutSession(_:onCompletion:)` modifier. The session injects the per-feature sessions into the environment, so views like `PrimerCardForm` and `PrimerPaymentMethods` resolve their state automatically.
```swift theme={"dark"}
struct CustomCheckout: View {
@StateObject private var session: PrimerCheckoutSession
init(clientToken: String) {
_session = StateObject(
wrappedValue: PrimerCheckoutSession(clientToken: clientToken)
)
}
var body: some View {
ScrollView {
VStack(spacing: 24) {
PrimerVaultedPaymentMethods()
PrimerPaymentMethods()
PrimerCardForm()
}
.padding()
}
.primerCheckoutSession(session) { state in
if case .failure(let error) = state {
print("Payment failed: \(error.localizedDescription)")
}
}
}
}
```
`PrimerCheckoutSession` does not have built-in error or success screens — handle all outcomes through the modifier's `onCompletion` closure, which delivers the terminal [`PrimerCheckoutState`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-state). 3DS challenges and redirect flows are handled automatically via internal overlays once the session is `.ready`. For the prebuilt, fully managed screens instead, use [`PrimerCheckout`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout).
When you compose your own layout, your views are responsible for all UI elements. The SDK still handles payment logic, validation, and state management, but you drive the UI through each view's `@ViewBuilder` slots and call the session methods (for example `session.submit()` on the [`PrimerCardFormSession`](/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-form-session) handed to a slot).
## Events
When implementing a custom layout, you need to listen for events to manage checkout states.
For comprehensive information on all available events, event payloads, and best practices, see the [Events Guide](/docs/checkout/primer-checkout/configuration/events).
```javascript theme={"dark"}
document
.querySelector('primer-checkout')
.addEventListener('primer:state-change', (event) => {
const state = event.detail;
if (state.isProcessing) {
// Show loading indicator
} else if (state.isSuccessful) {
// Show success message
} else if (state.primerJsError || state.paymentFailure) {
// Show error message
const errorMessage =
state.primerJsError?.message || state.paymentFailure?.message;
// Display error to user
}
});
```
* `primer:state-change` - Fired when checkout state changes
* `primer:methods-update` - Fired when available payment methods are loaded
* `primer:ready` - Fired when the SDK is ready
```kotlin theme={"dark"}
val state by checkout.state.collectAsStateWithLifecycle()
LaunchedEffect(state) {
when (val s = state) {
is PrimerCheckoutState.Success -> {
navController.navigate("confirmation/${s.checkoutData.payment.id}")
}
is PrimerCheckoutState.Failure -> {
showError(s.error.description)
}
else -> Unit
}
}
PrimerCheckoutHost(checkout = checkout) {
// Your custom layout
}
```
Android delivers payment outcomes as terminal cases of the single `PrimerCheckoutState` flow (`Success`, `Failure`), observed via `checkout.state`. All state updates are delivered reactively via `StateFlow`.
On iOS, observe state changes reactively by reading the `@Published` `state` on the session a slot hands you. Mark the session as `@ObservedObject` so SwiftUI re-renders when it changes:
```swift theme={"dark"}
PrimerCardForm(submitButton: { session in
Button("Pay") { session.submit() }
.disabled(!session.state.isValid || session.state.isLoading)
})
```
Payment outcomes are reported through the `onCompletion` closure on the `.primerCheckoutSession(_:onCompletion:)` modifier, which delivers the terminal [`PrimerCheckoutState`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-state):
```swift theme={"dark"}
.primerCheckoutSession(session) { state in
switch state {
case .success(let result):
print("Payment succeeded: \(result.paymentId)")
case .failure(let error):
print("Payment failed: \(error.localizedDescription)")
case .dismissed:
print("Checkout dismissed")
default:
break
}
}
```
iOS delivers a single terminal `PrimerCheckoutState` to `onCompletion` instead of multiple event listeners. State updates are delivered reactively via the `@Published` `state` on each session (`PrimerCardFormSession`, `PrimerSelectionSession`).
## Configuring payment methods
When customizing the payment method layout, you can include specific payment methods:
```html theme={"dark"}
```
The `type` attribute specifies which payment method to display. If a payment method isn't available in your Dashboard configuration, it simply won't render.
### Payment method filtering with `include`, `exclude` and `type`
The `primer-payment-method-container` component provides a declarative way to organize payment methods:
```html theme={"dark"}
```
This approach automatically filters available payment methods without requiring event listeners or manual state management. See the [Payment Method Container SDK Reference documentation](/docs/sdk/primer-checkout-web/components/primer-payment-method-container) for complete usage guide.
### Dynamic rendering with events
You can also dynamically render payment methods by listening to the `primer:methods-update` event:
```javascript theme={"dark"}
checkout.addEventListener('primer:methods-update', (event) => {
const availableMethods = event.detail.toArray();
const container = document.getElementById('payment-methods');
availableMethods.forEach((method) => {
const element = document.createElement('primer-payment-method');
element.setAttribute('type', method.type);
container.appendChild(element);
});
});
```
This approach ensures you only display payment methods that are actually available.
Use `rememberPaymentMethodsController()` to access the available payment methods as a reactive `StateFlow`:
```kotlin theme={"dark"}
val controller = rememberPaymentMethodsController(checkout)
val methods by controller.methods.collectAsStateWithLifecycle()
LazyColumn {
items(methods) { method ->
PaymentMethodCard(
name = method.paymentMethodName ?: method.paymentMethodType,
onClick = { controller.select(method) },
)
}
}
```
### Client-side filtering
There is no SDK API to filter or sort payment methods server-side. Filter the `methods` list client-side before rendering:
```kotlin theme={"dark"}
val controller = rememberPaymentMethodsController(checkout)
val methods by controller.methods.collectAsStateWithLifecycle()
val filtered = methods.filter {
it.paymentMethodType in listOf("PAYMENT_CARD", "PAYPAL")
}
```
The `StateFlow` updates automatically when `checkout.refresh()` is called.
Override the `method` slot on `PrimerPaymentMethods` to render your own row. The slot receives a `CheckoutPaymentMethod` and an `onSelect` closure — call `onSelect` to start that method's flow. The view resolves its [`PrimerSelectionSession`](/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/payment-methods-session) from the environment and renders one row per available method:
```swift theme={"dark"}
PrimerPaymentMethods(
method: { paymentMethod, onSelect in
Button(action: onSelect) {
HStack {
if let icon = paymentMethod.icon {
Image(uiImage: icon)
.resizable()
.scaledToFit()
.frame(width: 40, height: 28)
}
Text(paymentMethod.buttonText ?? paymentMethod.name)
Spacer()
}
.padding()
}
.buttonStyle(.plain)
}
)
```
### Client-side filtering
There is no SDK API to filter or sort payment methods server-side. To build a fully custom list, read the available methods from `session.state.paymentMethods` and filter them client-side before rendering, calling `session.select(_:)` on the [`PrimerSelectionSession`](/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/payment-methods-session) when a row is tapped:
```swift theme={"dark"}
struct CustomPaymentMethodList: View {
@ObservedObject var session: PrimerSelectionSession
var body: some View {
let methods = session.state.paymentMethods.filter {
["PAYMENT_CARD", "PAYPAL"].contains($0.type)
}
VStack {
ForEach(methods) { method in
Button { session.select(method) } label: {
HStack {
if let icon = method.icon {
Image(uiImage: icon).resizable().scaledToFit().frame(width: 40, height: 28)
}
Text(method.name)
Spacer()
}
.padding()
}
}
}
}
}
```
`state` is `@Published`, so the list updates automatically when the available methods change (for example after the [`PrimerCheckoutSession`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session) is refreshed via its `refresh()` method).
## Avoiding duplicate card forms
When customizing your checkout layout, be careful not to render duplicate card forms. This commonly happens when:
1. You create a custom card form using ``
2. You also include `` in your layout
```html theme={"dark"}
```
If you're using a custom card form implementation, you should **not** include the `PAYMENT_CARD` payment method in your layout.
**Important:** If you're using a custom card form, you should filter out the `PAYMENT_CARD` type to avoid duplicate card forms:
```javascript theme={"dark"}
checkout.addEventListener('primer:methods-update', (event) => {
let availableMethods = event.detail.toArray();
const container = document.getElementById('payment-methods');
if (document.querySelector('primer-card-form')) {
availableMethods = availableMethods.filter(
(method) => method.type !== 'PAYMENT_CARD',
);
}
availableMethods.forEach((method) => {
const element = document.createElement('primer-payment-method');
element.setAttribute('type', method.type);
container.appendChild(element);
});
});
```
On Android, this issue does not apply. `PrimerCardForm` and `PrimerPaymentMethods` are separate composables that don't conflict. When using `PrimerCheckoutHost`, you compose them independently:
```kotlin theme={"dark"}
PrimerCheckoutHost(checkout) {
Column {
PrimerCardForm(controller = rememberCardFormController(checkout))
PrimerPaymentMethods(rememberPaymentMethodsController(checkout))
}
}
```
If you want to exclude card payments from `PrimerPaymentMethods` (because you render `PrimerCardForm` separately), filter the methods list client-side:
```kotlin theme={"dark"}
val controller = rememberPaymentMethodsController(checkout)
val methods by controller.methods.collectAsStateWithLifecycle()
val nonCardMethods = methods.filter { it.paymentMethodType != "PAYMENT_CARD" }
```
On iOS, this issue does not apply. `PrimerCardForm` and `PrimerPaymentMethods` are separate views that don't conflict. When composing your own layout under `.primerCheckoutSession(_:)`, you place them independently:
```swift theme={"dark"}
ScrollView {
VStack(spacing: 24) {
PrimerCardForm()
PrimerPaymentMethods()
}
}
.primerCheckoutSession(session) { state in
handle(state)
}
```
If you want to exclude card payments from `PrimerPaymentMethods` (because you render `PrimerCardForm` separately), filter `session.state.paymentMethods` client-side when building a custom `method` slot:
```swift theme={"dark"}
let nonCardMethods = session.state.paymentMethods.filter { $0.type != "PAYMENT_CARD" }
```
## Best practices
1. **Listen for relevant events** - Handle checkout state through event listeners (Web) or by observing `checkout.state` (Android)
2. **Design responsively** - Ensure your layout works on all device sizes
3. **Test thoroughly** - Validate behavior across different payment methods and scenarios
4. **Prevent component flash** - Use CSS or JavaScript techniques to hide content until components are defined (Web), or observe `PrimerCheckoutState.Ready` before rendering (Android)
5. **Handle payment failures** - Either use the `` component (Web) or match on `PrimerCheckoutState.Failure` from `checkout.state` (Android)
## See also
Handle payment failures and display error messages
Complete reference for all checkout events