Layout with Event Handling

This guide covers advanced layout customization techniques for when you need complete control over your checkout experience.

Fully custom implementation

Web
Android
iOS

For complete control, you can bypass <primer-main> entirely and provide your own implementation.Choose one error display approach:Option A: Built-in error container

<primer-checkout client-token="your-token">
  <div slot="main" id="custom-checkout">
    <div id="payment-methods">
      <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>

      <!-- Pre-built component handles payment failure display automatically -->
      <primer-error-message-container></primer-error-message-container>
    </div>
  </div>
</primer-checkout>

Option B: Custom error element

<primer-checkout client-token="your-token">
  <div slot="main" id="custom-checkout">
    <div id="payment-methods">
      <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>

      <!-- Your own error element — requires event handling in JavaScript -->
      <div id="my-custom-error" class="custom-error-message"></div>
    </div>
  </div>
</primer-checkout>

Implementation responsibilityWhen 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 <primer-error-message-container> 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.

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:

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.

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

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

Web
Android
iOS

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
    }
  });

Key events to listen for

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

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:

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:

.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

Web
Android
iOS

When customizing the payment method layout, you can include specific payment methods:

<div slot="payments">
  <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>
  <primer-payment-method type="PAYPAL"></primer-payment-method>
</div>

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:

<!-- Sectioned layout example -->
<div slot="payments">
  <!-- Quick pay options -->
  <primer-payment-method-container
    include="APPLE_PAY,GOOGLE_PAY"
  ></primer-payment-method-container>

  <!-- Alternative methods -->
  <primer-payment-method-container
    exclude="PAYMENT_CARD,APPLE_PAY,GOOGLE_PAY"
  ></primer-payment-method-container>

  <!-- Card form -->
  <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>
</div>

This approach automatically filters available payment methods without requiring event listeners or manual state management. See the Payment Method Container SDK Reference documentation for complete usage guide.

Dynamic rendering with events

You can also dynamically render payment methods by listening to the primer:methods-update event:

Example: Dynamic payment method rendering

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:

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:

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 from the environment and renders one row per available method:

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 when a row is tapped:

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 is refreshed via its refresh() method).

Avoiding duplicate card forms

Web
Android
iOS

When customizing your checkout layout, be careful not to render duplicate card forms. This commonly happens when:

You create a custom card form using <primer-card-form>
You also include <primer-payment-method type="PAYMENT_CARD"> in your layout

<!-- INCORRECT: Will result in duplicate card forms -->
<div slot="payments">
  <!-- Custom card form -->
  <primer-card-form>
    <!-- Custom card form content -->
  </primer-card-form>

  <!-- This will render ANOTHER card form -->
  <primer-payment-method type="PAYMENT_CARD"></primer-payment-method>
</div>

If you’re using a custom card form implementation, you should not include the PAYMENT_CARD payment method in your layout.

Filtering to avoid duplicate card forms

Important: If you’re using a custom card form, you should filter out the PAYMENT_CARD type to avoid duplicate card forms:

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:

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:

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:

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:

let nonCardMethods = session.state.paymentMethods.filter { $0.type != "PAYMENT_CARD" }

Best practices

Listen for relevant events - Handle checkout state through event listeners (Web) or by observing checkout.state (Android)
Design responsively - Ensure your layout works on all device sizes
Test thoroughly - Validate behavior across different payment methods and scenarios
Prevent component flash - Use CSS or JavaScript techniques to hide content until components are defined (Web), or observe PrimerCheckoutState.Ready before rendering (Android)
Handle payment failures - Either use the <primer-error-message-container> component (Web) or match on PrimerCheckoutState.Failure from checkout.state (Android)

Error handling

Handle payment failures and display error messages

Events guide

Complete reference for all checkout events

​Fully custom implementation

​Events

​Configuring payment methods

​Payment method filtering with include, exclude and type

​Dynamic rendering with events

​Client-side filtering

​Client-side filtering

​Avoiding duplicate card forms

​Best practices

​See also

Error handling

Events guide

Fully custom implementation

Events

Configuring payment methods

Payment method filtering with `include`, `exclude` and `type`

Dynamic rendering with events

Client-side filtering

Client-side filtering

Avoiding duplicate card forms

Best practices

See also