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

# Events guide

> When and how to use the `primer:*` DOM events – ready, payment lifecycle, card form and vault – to drive your checkout.

This guide explains the event-driven model behind Primer Checkout and walks through the integration decisions you'll face when wiring events into your application. It is organized around the questions you'll encounter as you build: where to listen, what to set up first, and how to handle each phase of the payment lifecycle.

> [!TIP]
>
> This guide focuses on **when and why** to use each event. For the complete API surface, every event name, payload shape, type definition, and callback signature see the platform-specific SDK references.

## How events work

> [tab] Web
>
> Primer Checkout components dispatch [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) objects. Every Primer event is created with `bubbles: true` and `composed: true`, which means events propagate up through shadow DOM boundaries and can be caught at any ancestor element, including `document`. This design gives you two choices for where to listen, covered in the next section.

> [tab] Android
>
> The Android SDK communicates through a single channel:
>
> * **State** (`PrimerCheckoutState`): the full checkout lifecycle -- loading, ready, and the terminal `Success`/`Failure` outcomes
>
> State is a `StateFlow<PrimerCheckoutState>` you observe in Compose via `checkout.state`. Payment outcomes are terminal cases of that same flow.

> [tab] iOS
>
> The iOS SDK communicates through two mechanisms:
>
> * **Published session state**: `PrimerCheckoutSession` publishes the lifecycle `phase` (`.initializing` / `.ready`) and `clientSession`. `PrimerCardFormSession` and `PrimerSelectionSession` publish `state` for field-level and selection progress
> * **onCompletion callback** (`PrimerCheckoutState`): Receives `.failure` once per failed attempt, including a failed initialization. Then it receives `.success` or `.dismissed` at most once. It never receives `.initializing` or `.ready`, so read those from `phase`
>
> For the managed modal, pass `onCompletion` to `PrimerCheckout`. For inline, composable UI, observe each session's `@Published` state inside your SwiftUI views and receive the outcome through the `.primerCheckoutSession(_:theme:onCompletion:)` modifier. In UIKit, conform to `PrimerCheckoutPresenterDelegate`.

## Choosing where to listen

Each platform has its own mechanism for receiving SDK events and state changes.

> [tab] Web
>
> > [tab] Component Level
> >
> > Attach listeners directly to the `<primer-checkout>` element. Each listener is scoped to a single checkout instance.
> >
> > ```javascript theme={"dark"}
> > const checkout = document.querySelector('primer-checkout');
> >
> > checkout.addEventListener('primer:ready', (event) => {
> >   // This listener only fires for this checkout instance
> >   const primer = event.detail;
> >   configureCallbacks(primer);
> > });
> > ```
> >
> > **Choose this when:**
> >
> > * You want to co-locate event logic with the component that owns it, such as inside a framework component's lifecycle hook.
> > * You need to tear down listeners cleanly when a checkout is removed from the DOM.
>
> > [tab] Document Level
> >
> > Attach listeners to `document`. Because Primer events bubble and are composed, they reach the document root regardless of where the component sits in the DOM.
> >
> > ```javascript theme={"dark"}
> > document.addEventListener('primer:payment-success', (event) => {
> >   // Fires when any Primer event bubbles up to document
> >   analytics.track('payment_completed', event.detail);
> > });
> > ```
> >
> > **Choose this when:**
> >
> > * You have a single checkout per page and prefer centralized event handling.
> > * You're building cross-cutting concerns like analytics, logging, or error monitoring.
> > * Your architecture already uses a global event bus pattern.
>
> ### Ensuring the component exists
>
> When using component-level listeners, make sure the element is in the DOM before attaching them. If your checkout renders dynamically (through a router transition, a conditional template, or lazy loading), the element may not exist at script-execution time.
>
> ```javascript theme={"dark"}
> // Safe: wait for the DOM to be ready before querying
> document.addEventListener('DOMContentLoaded', () => {
>   const checkout = document.querySelector('primer-checkout');
>   if (checkout) {
>     checkout.addEventListener('primer:payment-success', handlePaymentSuccess);
>     checkout.addEventListener('primer:payment-failure', handlePaymentFailure);
>   }
> });
> ```
>
> If your framework provides a lifecycle hook that runs after the component mounts (React's `useEffect`, Vue's `onMounted`, etc.), prefer that over `DOMContentLoaded`.

> [tab] Android
>
> State -- including the terminal `Success` and `Failure` outcomes -- is observed from `checkout.state`:
>
> ```kotlin theme={"dark"}
> val checkout = rememberPrimerCheckoutController(clientToken)
> val state by checkout.state.collectAsStateWithLifecycle()
>
> when (state) {
>     is PrimerCheckoutState.Loading -> {
>         CircularProgressIndicator()
>     }
>     is PrimerCheckoutState.Ready -> {
>         val clientSession = (state as PrimerCheckoutState.Ready).clientSession
>         Text("Total: ${checkout.formatAmount(clientSession.totalAmount ?: 0)}")
>         PrimerCheckoutSheet(checkout = checkout)
>     }
> }
> ```
>
> ### PrimerCheckoutState
>
> | State | Description | Properties |
> | - | - | - |
> | `Loading` | SDK is initializing, fetching configuration | -- |
> | `Ready` | Checkout is ready for payment | `clientSession: PrimerClientSession` |
> | `Success` | Payment completed | `checkoutData: PrimerCheckoutData` |
> | `Failure` | Payment failed or an error occurred | `error: PrimerError` |
>
> ### PrimerClientSession
>
> Available in the `Ready` state:
>
> | Property | Type | Description |
> | - | - | - |
> | `customerId` | `String?` | Customer identifier |
> | `orderId` | `String?` | Order identifier |
> | `currencyCode` | `String?` | Currency code (e.g., `"USD"`) |
> | `totalAmount` | `Int?` | Total amount in minor units (cents) |
> | `lineItems` | `List<PrimerLineItem>?` | Order line items |
> | `orderDetails` | `PrimerOrder?` | Order details (country, shipping) |
> | `customer` | `PrimerCustomer?` | Customer details (email, name, address) |
> | `paymentMethod` | `PrimerPaymentMethod?` | Payment method configuration |
> | `fees` | `List<PrimerFee>?` | Associated fees |

> [tab] iOS
>
> The outcome is delivered to the `onCompletion` closure on `PrimerCheckout` (managed modal) or on the `.primerCheckoutSession(_:theme:onCompletion:)` modifier (inline), as a `PrimerCheckoutState` -- `.success`, `.failure`, or `.dismissed`. `.success` and `.dismissed` end the session and arrive at most once. `.failure` arrives once per failed attempt. While the SDK error screen is enabled (`uiOptions.isErrorScreenEnabled`, on by default), the checkout stays open on it. The closure is then called again if the customer retries. With `PrimerCheckout` this includes a failed initialization, whose error screen offers a retry. With the inline modifier, a failure before `.ready` ends the session. This example uses the managed modal:
>
> ```swift theme={"dark"}
> PrimerCheckout(clientToken: clientToken) { state in
>   switch state {
>   case let .success(result):
>     print("Payment ID: \(result.paymentId)")
>   case let .failure(error, _):
>     print("Failed: \(error.errorDescription ?? "")")
>   case .dismissed:
>     print("Dismissed")
>   default:
>     break
>   }
> }
> ```
>
> For inline UI you observe lifecycle and field-level progress by reading each session's `@Published` property: `PrimerCheckoutSession` publishes `phase`, while `PrimerCardFormSession` and `PrimerSelectionSession` publish `state`.
>
> ### PrimerCheckoutState
>
> | State | Description | Associated Values |
> | - | - | - |
> | `.initializing` | SDK is loading configuration. Not delivered to `onCompletion`. For inline UI, read `PrimerCheckoutSession.phase` | -- |
> | `.ready` | Checkout is ready for payment. Not delivered to `onCompletion`. For inline UI, read `PrimerCheckoutSession.phase` and `PrimerCheckoutSession.clientSession` | `clientSession: PrimerClientSession` |
> | `.success` | Payment completed. Delivered once | `PaymentResult` |
> | `.failure` | A payment attempt or the initialization failed. Delivered once per failed attempt | `PrimerError`, `checkoutData: PrimerCheckoutData?` |
> | `.dismissed` | Checkout was dismissed. Delivered once | -- |

## Phase 1: Initialization

Every Primer Checkout integration begins with initialization. The SDK must fully initialize before you can pre-fill form fields or call SDK methods.

> [tab] Web
>
> The `primer:ready` event fires once after the SDK has fully initialized. It delivers the `PrimerJS` instance as `event.detail`.
>
> ```javascript theme={"dark"}
> const checkout = document.querySelector('primer-checkout');
>
> checkout.addEventListener('primer:ready', (event) => {
>   const primer = event.detail;
>
>   // Pre-fill known data (optional)
>   const user = getAuthenticatedUser();
>   if (user?.fullName) {
>     primer.setCardholderName(user.fullName);
>   }
>
>   // Access available methods immediately if needed
>   const methods = primer.getPaymentMethods();
>   console.log(`${methods.length} payment method(s) available at init`);
> });
>
> // Handle payment outcomes via events
> checkout.addEventListener('primer:payment-success', (event) => {
>   const { payment, paymentMethodType } = event.detail;
>   console.log('Payment successful:', payment.last4Digits);
>   window.location.href = `/confirmation?method=${paymentMethodType}`;
> });
>
> checkout.addEventListener('primer:payment-failure', (event) => {
>   const { error } = event.detail;
>   console.error('Payment failed:', error.message);
>   // The checkout UI already displays the error to the user.
>   // Use this event for logging, analytics, or retry logic.
> });
> ```
>
> > [!WARNING]
> >
> > If you don't listen for `primer:payment-success` and `primer:payment-failure`, successful and failed payments will complete silently with no redirect or confirmation. Always attach these event listeners.
>
> Before using `primer:payment-failure` to offer a retry, check the error's `code` and `origin` — [not all failures are retryable](https://primer.io/docs/checkout/primer-checkout/build-your-ui/error-handling.md#not-all-failures-are-retryable), and a network-level failure may hide a payment that actually succeeded.

> [tab] Android
>
> The checkout controller initializes automatically when created with `rememberPrimerCheckoutController()`. Payment outcomes are terminal cases of `checkout.state` -- observe the flow to react to them:
>
> ```kotlin theme={"dark"}
> val state by checkout.state.collectAsStateWithLifecycle()
>
> LaunchedEffect(state) {
>     when (val s = state) {
>         is PrimerCheckoutState.Success -> {
>             val payment = s.checkoutData
>             Log.d("Checkout", "Payment ID: ${payment.payment.id}")
>             navigateToConfirmation(payment)
>         }
>         is PrimerCheckoutState.Failure -> {
>             val error = s.primerError
>             Log.e("Checkout", "Failed: ${error.description}")
>             Log.e("Checkout", "Diagnostics: ${error.diagnosticsId}")
>             // Present when the payment was created before failing, e.g. a decline.
>             s.checkoutData?.payment?.let { payment ->
>                 Log.e("Checkout", "Payment: ${payment.id} order: ${payment.orderId}")
>             }
>         }
>         else -> Unit
>     }
> }
>
> PrimerCheckoutSheet(checkout = checkout)
> ```

> [tab] iOS
>
> The checkout initializes automatically when the `PrimerCheckout` SwiftUI view appears (or when the `.primerCheckoutSession` modifier calls `start()` on appear). Pass an `onCompletion` closure to receive the outcome:
>
> ```swift theme={"dark"}
> PrimerCheckout(clientToken: clientToken) { state in
>   switch state {
>   case let .success(result):
>     print("Payment ID: \(result.paymentId)")
>     navigateToConfirmation(result)
>   case let .failure(error, checkoutData):
>     print("Failed: \(error.errorDescription ?? "")")
>     print("Diagnostics: \(error.diagnosticsId)")
>     // Present when the payment was created before failing, e.g. a decline.
>     if let payment = checkoutData?.payment {
>       print("Payment: \(payment.id ?? "-") order: \(payment.orderId ?? "-")")
>     }
>   case .dismissed:
>     navigateBack()
>   default:
>     break
>   }
> }
> ```
>
> To observe the `.ready` lifecycle state for an inline integration, read the `phase` published by `PrimerCheckoutSession` (`.initializing` / `.ready`) inside your SwiftUI view. The client session that `.ready` carries is published separately as `PrimerCheckoutSession.clientSession` -- `nil` until the session is ready, then the same `PrimerClientSession` value:
>
> ```swift theme={"dark"}
> if let total = session.clientSession?.totalAmount,
>    let formatted = session.formatAmount(total) {
>     Text("Total: \(formatted)")
> }
> ```
>
> `totalAmount` is in minor units, so rendering it directly shows `1000` for a ten-dollar order. Use [`session.formatAmount(_:)`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session) to format it the way the SDK's own screens do.
>
> > [!WARNING]
> >
> > If you don't provide an `onCompletion` closure, successful and failed payments will complete with no redirect or confirmation. Always provide this closure.

## Phase 2: Payment method discovery

Shortly after initialization, the SDK provides information about available payment methods for the current session.

> [tab] Web
>
> The SDK dispatches `primer:methods-update` with the list of payment methods available for the current session. This event fires once on load and may fire again if the session changes (e.g. after calling `primer.refreshSession()` in response to a cart update).
>
> You should use this event when you want to build a custom payment method selector, conditionally render UI based on what's available, or route users to a specific method.
>
> ```javascript theme={"dark"}
> checkout.addEventListener('primer:methods-update', (event) => {
>   const methods = event.detail;
>
>   // Conditionally show an "Express Checkout" section only if Apple Pay or Google Pay is available
>   const hasExpressMethod = methods.toArray().some(
>     (m) => m.type === 'APPLE_PAY' || m.type === 'GOOGLE_PAY'
>   );
>
>   document.getElementById('express-checkout-section').hidden = !hasExpressMethod;
> });
> ```
>
> If you're building a fully custom payment method layout (headless), you'll also iterate over the methods to create `<primer-payment-method>` elements dynamically. The [Headless Vault Guide](https://primer.io/docs/sdk/primer-checkout-web/components/primer-vault-manager.md#headless-vault-implementation) covers that pattern in detail.

> [tab] Android
>
> Payment methods are managed automatically by the SDK components (`PrimerPaymentMethods`, `PrimerVaultedPaymentMethods`). You can access the client session details from the `Ready` state:
>
> ```kotlin theme={"dark"}
> val state by checkout.state.collectAsStateWithLifecycle()
>
> when (state) {
>     is PrimerCheckoutState.Ready -> {
>         val clientSession = (state as PrimerCheckoutState.Ready).clientSession
>         Text("Total: ${checkout.formatAmount(clientSession.totalAmount ?: 0)}")
>     }
> }
> ```

> [tab] iOS
>
> Payment methods are managed by the `PrimerPaymentMethods` view, which resolves a `PrimerSelectionSession` from the environment. Observe the session's published `state` to track available and selected methods:
>
> ```swift theme={"dark"}
> struct MethodCount: View {
>   @ObservedObject var session: PrimerSelectionSession
>
>   var body: some View {
>     VStack(alignment: .leading) {
>       Text("Methods: \(session.state.paymentMethods.count)")
>       if let selected = session.state.selectedPaymentMethod {
>         Text("Selected: \(selected.name)")
>       }
>     }
>   }
> }
> ```
>
> Read `state` inside a `header` or `emptyState` slot, which receive the `PrimerSelectionSession`. The `method` slot instead receives a `CheckoutPaymentMethod` and an `onSelect` closure, so it does not have access to the session.

## Phase 3: User interaction

As the user fills in payment details, the SDK provides real-time feedback.

### Showing the Card Network

> [tab] Web
>
> `primer:bin-data-available` fires as the user types their card number. It provides the detected card network, co-badged network alternatives, and additional BIN data such as issuer information when available. Use it to display the correct card brand logo, show a co-badge network picker, or adjust UI based on card attributes.
>
> ```javascript theme={"dark"}
> checkout.addEventListener('primer:bin-data-available', (event) => {
>   const { preferred, alternatives, status } = event.detail;
>   const logoEl = document.getElementById('card-logo');
>   const cobrandEl = document.getElementById('cobrand-selector');
>
>   if (preferred) {
>     logoEl.src = `/images/${preferred.network.toLowerCase()}.svg`;
>     logoEl.alt = preferred.displayName;
>   }
>
>   // Some cards support co-badging (e.g. Carte Bancaire / Visa).
>   // If there are multiple allowed networks, show a picker.
>   const selectableNetworks = [preferred, ...alternatives].filter(n => n?.allowed);
>   cobrandEl.hidden = selectableNetworks.length <= 1;
>
>   // When status is 'complete', additional issuer data is available
>   if (status === 'complete' && preferred?.issuerCountryCode) {
>     console.log(`Card issued in: ${preferred.issuerCountryCode}`);
>   }
> });
> ```
>
> To show a loading indicator while BIN data is being fetched, listen for `primer:bin-data-loading-change`:
>
> ```javascript theme={"dark"}
> checkout.addEventListener('primer:bin-data-loading-change', (event) => {
>   const { loading } = event.detail;
>   document.getElementById('card-logo').src = loading
>     ? '/images/card-placeholder.svg'
>     : document.getElementById('card-logo').src;
> });
> ```
>
> > [!NOTE]
> >
> > `primer:bin-data-available` replaces the older `primer:card-network-change` event with a richer payload that includes issuer details and card attributes. See the [Events Reference](https://primer.io/docs/sdk/primer-checkout-web/events-reference.md#primerbin-data-available) for the full payload shape.

> [tab] Android
>
> The Android SDK handles card network detection and display automatically within the `PrimerCardForm` component. Card brand icons update in real-time as the user types.

> [tab] iOS
>
> Card network detection is available via `PrimerCardFormState`. The `PrimerCardForm` view injects a `PrimerCardFormSession` into each of its slots; observe the session's published `state` and read `selectedNetwork` and `availableNetworks` as the user types:
>
> ```swift theme={"dark"}
> PrimerCardForm(cardDetails: { session in
>   VStack(alignment: .leading) {
>     CardFormDefaults.cardNumber(session)
>     if let network = session.state.selectedNetwork {
>       Text("Detected network: \(network.displayName)")
>     }
>     // Co-badged cards expose multiple networks
>     if session.state.availableNetworks.count > 1 {
>       Text("Co-badge options: \(session.state.availableNetworks.map(\.displayName).joined(separator: ", "))")
>     }
>   }
> })
> ```
>
> To select a network on a co-badged card, call `session.selectCardNetwork(_:)`.

### Triggering Submission from a Custom Button

> [tab] Web
>
> If you're using your own "Pay" button instead of the built-in one, dispatch `primer:card-submit` to tell the SDK to validate and submit the card form.
>
> ```javascript theme={"dark"}
> document.getElementById('custom-pay-button').addEventListener('click', () => {
>   document.dispatchEvent(
>     new CustomEvent('primer:card-submit', {
>       bubbles: true,
>       composed: true,
>     }),
>   );
> });
> ```
>
> > [!WARNING]
> >
> > `bubbles: true` and `composed: true` are required so the event crosses shadow DOM boundaries and reaches the card form component inside `<primer-checkout>`. Omitting either option will silently prevent submission.
>
> For vault payment submission from a custom button, dispatch `primer:vault-submit` in the same way. See the [Events Reference and Triggerable Events](https://primer.io/docs/sdk/primer-checkout-web/events-reference.md#triggerable-events) for the full list of events you can dispatch.

> [tab] Android
>
> The Android SDK handles user interaction through Compose components. Card form state is managed via `PrimerCardFormController`:
>
> ```kotlin theme={"dark"}
> val cardFormController = rememberCardFormController()
> ```
>
> The SDK provides built-in components for card input (`PrimerCardForm`), payment method selection (`PrimerPaymentMethods`), and vaulted methods (`PrimerVaultedPaymentMethods`). These handle user interaction automatically.

> [tab] iOS
>
> If you're building a custom card form UI, drive the fields and submission through the `PrimerCardFormSession` injected into each `PrimerCardForm` slot. Bind your `TextField`s to the `update*` methods and call `submit()` from your custom button:
>
> ```swift theme={"dark"}
> PrimerCardForm(
>   cardDetails: { session in
>     VStack(spacing: 16) {
>       TextField("Card number", text: Binding(
>         get: { session.state.data[.cardNumber] },
>         set: { session.updateCardNumber($0) }
>       ))
>       TextField("Cardholder name", text: Binding(
>         get: { session.state.data[.cardholderName] },
>         set: { session.updateCardholderName($0) }
>       ))
>     }
>   },
>   submitButton: { session in
>     // Submit when your custom button is tapped
>     Button("Pay") { session.submit() }
>       .disabled(!session.state.isValid || session.state.isLoading)
>   }
> )
> ```
>
> Call `session.cancel()` to leave the card form. When other payment methods are configured, it returns to payment method selection. When the card is the only configured payment method, it dismisses the checkout and delivers `.dismissed`, even if the customer has saved methods. It is ignored while a payment is running or while your `onBeforePaymentCreate` handler has not decided yet.

## Phase 4: Payment processing and outcome

Once the user submits, the SDK moves through a processing to outcome sequence.

> [tab] Web
>
> The `primer:state-change` event fires at every step, giving you a single stream to drive your UI state.
>
> ```javascript theme={"dark"}
> checkout.addEventListener('primer:state-change', (event) => {
>   const { isLoading, isProcessing, isSuccessful, paymentFailure, primerJsError } = event.detail;
>   const submitBtn = document.getElementById('custom-pay-button');
>   const spinner = document.getElementById('loading-overlay');
>
>   // Disable the button during loading or processing
>   submitBtn.disabled = isLoading || isProcessing;
>
>   // Show a loading overlay while the payment is in flight
>   spinner.hidden = !isProcessing;
>
>   if (isSuccessful) {
>     // Payment succeeded — primer:payment-success will also fire
>     document.getElementById('checkout-form').hidden = true;
>   }
>
>   if (paymentFailure) {
>     // The checkout component already displays the error to the user.
>     // Use this for supplementary logging or analytics.
>     console.error(`Payment error [${paymentFailure.code}]: ${paymentFailure.message}`);
>   }
>
>   if (primerJsError) {
>     // An SDK-level error (network failure, configuration issue, etc.)
>     // Unlike paymentFailure, this may not be shown in the checkout UI.
>     reportToErrorService(primerJsError);
>   }
> });
> ```

> [tab] Android
>
> | State | When | Key Properties |
> | - | - | - |
> | `PrimerCheckoutState.Success` | Payment completed | `checkoutData: PrimerCheckoutData` |
> | `PrimerCheckoutState.Failure` | Payment failed | `primerError: PrimerError`, `checkoutData: PrimerCheckoutData?` |
>
> ```kotlin theme={"dark"}
> val state by checkout.state.collectAsStateWithLifecycle()
>
> LaunchedEffect(state) {
>     when (val s = state) {
>         is PrimerCheckoutState.Success -> {
>             val payment = s.checkoutData
>             Log.d("Checkout", "Payment ID: ${payment.payment.id}")
>             navigateToConfirmation(payment)
>         }
>         is PrimerCheckoutState.Failure -> {
>             val error = s.primerError
>             Log.e("Checkout", "Failed: ${error.description}")
>             Log.e("Checkout", "Diagnostics: ${error.diagnosticsId}")
>             // Present when the payment was created before failing, e.g. a decline.
>             s.checkoutData?.payment?.let { payment ->
>                 Log.e("Checkout", "Payment: ${payment.id} order: ${payment.orderId}")
>             }
>         }
>         else -> Unit
>     }
> }
>
> PrimerCheckoutSheet(checkout = checkout)
> ```

> [tab] iOS
>
> The `onCompletion` closure receives `.failure` once per failed attempt. While the SDK error screen is enabled, the checkout stays open so the customer can retry. It then receives `.success` or `.dismissed` at most once, and after that nothing more. Read the [`PaymentResult`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-state) on `.success` and the [`PrimerError`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-error) on `.failure`:
>
> ```swift theme={"dark"}
> PrimerCheckout(clientToken: clientToken) { state in
>   switch state {
>   case let .success(result):
>     print("Payment ID: \(result.paymentId)")
>     print("Status: \(result.status)")
>     navigateToConfirmation(result)
>   case let .failure(error, checkoutData):
>     print("Error: \(error.errorDescription ?? "")")
>     print("Diagnostics: \(error.diagnosticsId)")
>     // Present when the payment was created before failing, e.g. a decline.
>     if let payment = checkoutData?.payment {
>       print("Payment: \(payment.id ?? "-") order: \(payment.orderId ?? "-")")
>     }
>   case .dismissed:
>     break
>   default:
>     break
>   }
> }
> ```
>
> For an inline integration, drive intermediate UI (spinners, disabled buttons) from each session's `@Published` state -- for example `PrimerCardFormSession.state.isLoading` while a payment is in flight.

### State change vs. outcome events

`primer:state-change` fires multiple times during a single payment. The outcome events (`primer:payment-success`, `primer:payment-failure`) fire exactly once at the end. Use `primer:state-change` for continuous UI updates (spinners, button states, progress indicators). Use the outcome events for final actions (redirects, confirmations, server notifications).

### Event timing

Events may fire multiple times during a single checkout session (for example, if the user retries after a failure).

> [tab] Web
>
> * `primer:state-change` fires at every step — use it for continuous UI updates (spinners, button states)
> * `primer:payment-success` and `primer:payment-failure` fire exactly once at the end — use them for final actions

> [tab] Android
>
> * `Success` fires immediately — the default success screen auto-dismisses after 3 seconds
> * `Failure` fires immediately — the error screen stays open for retry

> [tab] iOS
>
> * Each session's `@Published` state updates as the flow progresses -- observe it for continuous UI updates (spinners, button states)
> * `.success` and `.dismissed` end the checkout. Only one of them reaches `onCompletion`, at most once -- use it for final actions (navigation, confirmation)
> * `.failure` reaches `onCompletion` once per failed attempt. While the SDK error screen is enabled, the checkout stays open for a retry -- log the error or show your own message instead of navigating away
> * `.dismissed` fires when the user dismisses the checkout without completing payment

### Dismissal and session refresh

> [tab] Web
>
> Call `primer.refreshSession()` to sync the client-side SDK with your server session after a cart change. The SDK will re-dispatch `primer:methods-update` with the updated method list.

> [tab] Android
>
> Handle checkout dismissal via the `onDismiss` callback:
>
> ```kotlin theme={"dark"}
> PrimerCheckoutSheet(
>     checkout = checkout,
>     onDismiss = {
>         navigateBack()
>     },
> )
> ```
>
> Call `checkout.refresh()` to reinitialize the checkout after updating the order on your server.
>
> Use `checkout.formatAmount()` to display currency-formatted values:
>
> ```kotlin theme={"dark"}
> val formattedTotal = checkout.formatAmount(1000) // "$10.00"
> ```

> [tab] iOS
>
> Handle dismissal by observing the `.dismissed` state in `onCompletion`:
>
> ```swift theme={"dark"}
> PrimerCheckout(clientToken: clientToken) { state in
>   if case .dismissed = state {
>     navigateBack()
>   }
> }
> ```
>
> For an inline integration, call `await session.refresh()` on your `PrimerCheckoutSession` to re-fetch configuration and payment methods after a client-session update (for example, an amount or currency change).

## Intercepting payments with primer:payment-start

Sometimes you need to run a check *after* the user clicks "Pay" but *before* the payment is created — for example, confirming terms-of-service acceptance, validating inventory, or applying a last-second promotion code.

> [tab] Web
>
> The `primer:payment-start` event gives you that interception point.
>
> ```javascript theme={"dark"}
> checkout.addEventListener('primer:payment-start', (event) => {
>   const { paymentMethodType, continuePaymentCreation, abortPaymentCreation } = event.detail;
>
>   // Prevent automatic continuation
>   event.preventDefault();
>
>   const termsAccepted = document.getElementById('terms-checkbox').checked;
>
>   if (!termsAccepted) {
>     showInlineError('Please accept the terms of service before paying.');
>     abortPaymentCreation();
>     return;
>   }
>
>   // Optionally inspect paymentMethodType to apply method-specific logic
>   continuePaymentCreation();
> });
> ```
>
> > [!WARNING]
> >
> > If you call `event.preventDefault()`, you must call either `continuePaymentCreation()` or `abortPaymentCreation()` in every code path. If neither is called, the payment will hang indefinitely. If you don't call `preventDefault()`, the payment continues automatically.

> [tab] Android
>
> > [!NOTE]
> >
> > Payment interception is not available in the composable module.

> [tab] iOS
>
> Set `onBeforePaymentCreate` on your `PrimerCheckoutSession` to intercept payments after the user taps "Pay" but before the payment is created. It runs for every payment method, including payments with a saved method started from the SDK's pay button or from `PrimerSelectionSession.selectVaulted(_:)`. The handler receives the payment-method data and a decision handler:
>
> ```swift theme={"dark"}
> struct CheckoutView: View {
>   @StateObject private var session: PrimerCheckoutSession
>
>   init(clientToken: String) {
>     let session = PrimerCheckoutSession(clientToken: clientToken)
>     session.onBeforePaymentCreate = { _, decisionHandler in
>       guard termsAccepted else {
>         decisionHandler(.abortPaymentCreation())
>         return
>       }
>       decisionHandler(.continuePaymentCreation(withIdempotencyKey: nil))
>     }
>     _session = StateObject(wrappedValue: session)
>   }
>
>   var body: some View {
>     ScrollView {
>       PrimerCardForm()
>     }
>     .primerCheckoutSession(session) { state in
>       // Handle the outcome.
>     }
>   }
> }
> ```
>
> > [!WARNING]
> >
> > You must call the `decisionHandler` closure with either `.continuePaymentCreation(withIdempotencyKey:)` or `.abortPaymentCreation()` in every code path. The SDK never times out the decision. It logs a warning after 5 seconds, and the payment hangs until you call it.

`continuePaymentCreation` accepts an optional `{ idempotencyKey }` parameter. When provided, this key is sent with the payment request to prevent duplicate payments from being created. See the [Events Reference](https://primer.io/docs/sdk/primer-checkout-web/events-reference.md#preparehandler) for the full type definition.

> [!TIP]
>
> `primer:payment-start` is for **client-side** checks that resolve in the browser. If you need a **server-side** decision (running a fraud check or inventory validation on your backend before the payment is created), use the [Manual payment approval](https://primer.io/docs/checkout/primer-checkout/guides-and-recipes/manual-payment-approval.md) flow, which pauses on the `primer:payment-approval-required` event until your backend approves or aborts the attempt.

## Working with Vaulted Payment Methods

If your integration supports saved (vaulted) payment methods, additional events become relevant.

> [tab] Web
>
> * **`primer:vault-methods-update`** — fires when vaulted payment methods are loaded or when the vault state changes. Use it to render saved cards, show a "Pay with saved card" section, or determine whether CVV re-entry is required.
> * **`primer:vault-selection-change`** — fires when the user selects or deselects a saved method. Use it to enable or disable your submit button, or to toggle between "pay with saved card" and "pay with new card" views.
>
> ```javascript theme={"dark"}
> let cvvRequired = false;
>
> checkout.addEventListener('primer:vault-methods-update', (event) => {
>   const { vaultedPayments, cvvRecapture } = event.detail;
>   cvvRequired = cvvRecapture;
>
>   const savedMethodsSection = document.getElementById('saved-methods');
>   if (vaultedPayments.length > 0) {
>     savedMethodsSection.hidden = false;
>     renderSavedMethodsList(vaultedPayments);
>   } else {
>     savedMethodsSection.hidden = true;
>   }
> });
>
> checkout.addEventListener('primer:vault-selection-change', (event) => {
>   const { paymentMethodId } = event.detail;
>   const vaultSubmitBtn = document.getElementById('vault-pay-button');
>
>   // Enable the button only when a method is selected
>   vaultSubmitBtn.disabled = !paymentMethodId;
>
>   // If CVV re-entry is required, show the CVV input when a method is selected
>   if (paymentMethodId && cvvRequired) {
>     showCvvInput(paymentMethodId);
>   }
> });
> ```
>
> For full headless vault implementation, including `primer.vault.createCvvInput()`, `primer.vault.startPayment()`, and `primer.vault.delete()` see the [Headless Vault Guide](https://primer.io/docs/sdk/primer-checkout-web/components/primer-vault-manager.md#headless-vault-implementation).

> [tab] Android
>
> Vaulted payment methods are managed by the `PrimerVaultedPaymentMethods` component and `rememberVaultedPaymentMethodsController()`:
>
> ```kotlin theme={"dark"}
> val vaultController = rememberVaultedPaymentMethodsController()
> ```
>
> The SDK provides built-in UI for displaying and selecting saved payment methods within `PrimerCheckoutSheet`.

> [tab] iOS
>
> Saved methods are rendered by the `PrimerVaultedPaymentMethods` view, backed by the same `PrimerSelectionSession`. Read the published `vaultedPaymentMethods` for the list, keep the highlight in your own view state, and call `selectVaulted(_:)` from your pay button. It is the pay verb, not a selection verb:
>
> ```swift theme={"dark"}
> struct SavedMethodList: View {
>   @ObservedObject var session: PrimerSelectionSession
>   @State private var highlighted: String?
>
>   var body: some View {
>     VStack(alignment: .leading, spacing: 8) {
>       ForEach(session.vaultedPaymentMethods, id: \.id) { method in
>         Button(method.paymentMethodType) { highlighted = method.id }
>       }
>
>       Button("Pay") {
>         guard let method = session.vaultedPaymentMethods
>           .first(where: { $0.id == highlighted }) else { return }
>         session.selectVaulted(method)
>       }
>     }
>   }
> }
> ```
>
> A card that needs CVV recapture raises the CVV recapture screen on submit, and that screen finishes the payment.
>
> Call `try await session.delete(_:)` to remove a saved method -- it deletes immediately, with no confirmation step -- and `session.showAll()` to present the SDK's saved-methods screen, where the customer can switch methods or delete one. The default header of `PrimerVaultedPaymentMethods` already wires `showAll()` in.

## Event flow overview

The following diagram shows the typical sequence of events in a successful card payment, from initialization through confirmation.

```mermaid theme={"dark"}
sequenceDiagram
    participant App as Your App
    participant SDK as Primer SDK

    Note over App,SDK: Phase 1 - Initialization
    SDK->>App: SDK ready
    Note right of App: Register callbacks, pre-fill fields

    Note over App,SDK: Phase 2 - Discovery
    SDK->>App: Payment methods available
    SDK->>App: Vaulted methods loaded
    Note right of App: Render payment method UI

    Note over App,SDK: Phase 3 - User Interaction
    App->>SDK: User enters card details
    SDK->>App: Card network detected
    Note right of App: Show card brand logo

    Note over App,SDK: Phase 4 - Processing & Outcome
    App->>SDK: Submit payment
    SDK->>App: State: processing
    Note right of App: Show spinner, disable button
    SDK->>App: State: successful
    SDK->>App: Payment success event
    Note right of App: Navigate to confirmation
```

## Debugging tips

> [tab] Web
>
> * **Events not firing?** Confirm the `<primer-checkout>` element is in the DOM before you add listeners. In SPAs, race conditions between route rendering and listener attachment are the most common cause.
> * **Shadow DOM boundary issues?** Triggerable events (`primer:card-submit`, `primer:vault-submit`) must be dispatched with `bubbles: true` and `composed: true` or they won't reach the internal form component.
> * **Stale data after a cart change?** Call `primer.refreshSession()` to sync the client-side SDK with your server session. The SDK will re-dispatch `primer:methods-update` with the updated method list.

> [tab] Android
>
> * **State not updating?** Make sure you're using `collectAsStateWithLifecycle()` instead of `collectAsState()`.
> * **Outcomes not received?** Ensure you're observing `checkout.state` and handling the terminal `PrimerCheckoutState.Success` and `PrimerCheckoutState.Failure` cases.
> * **Stale data after a cart change?** Call `checkout.refresh()` to reinitialize the checkout.
> * **Log diagnostics IDs.** Every `PrimerError` includes a `diagnosticsId`. Log it for troubleshooting with Primer support.

> [tab] iOS
>
> * **State not updating?** Observe the session with `@ObservedObject` (or hold `PrimerCheckoutSession` as a `@StateObject`) so SwiftUI re-renders when its published properties change. These are `phase` and `clientSession` on `PrimerCheckoutSession`, `state` on `PrimerCardFormSession`, and `state` and `vaultedPaymentMethods` on `PrimerSelectionSession`.
> * **onCompletion not firing?** It fires for `.success`, `.failure` and `.dismissed`. Read `PrimerCheckoutSession.phase` to follow `.initializing` and `.ready`.
> * **Composable views not rendering?** Make sure the `.primerCheckoutSession(_:theme:onCompletion:)` modifier is applied above `PrimerCardForm` / `PrimerPaymentMethods` in the hierarchy. Without it, they cannot resolve a session from the environment.
> * **Child sessions are nil?** `PrimerCheckoutSession.cardForm` and `.selection` are non-`nil` only once `phase == .ready`.
> * **Log diagnostics IDs.** Every `PrimerError` includes a `diagnosticsId`. Log it for troubleshooting with Primer support.

## See also

> [card] [Web events reference](https://primer.io/docs/sdk/primer-checkout-web/events-reference.md)
>
> Every Web event name, payload type, callback signature, and instance method

> [card] [Android SDK reference](https://primer.io/docs/sdk/android-checkout/v3.0.0-beta/api/overview.md)
>
> Android SDK API documentation

> [card] [iOS SDK reference](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/overview.md)
>
> iOS SDK API documentation

> [card] [Recipes](https://primer.io/docs/checkout/primer-checkout/guides-and-recipes/overview.md)
>
> Use-case driven examples for common integration scenarios

> [card] [Error handling](https://primer.io/docs/checkout/primer-checkout/build-your-ui/error-handling.md)
>
> Deep dive into error handling, retries, and failure recovery


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