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

# Glossary

> Definitions of key terms used throughout the Primer Checkout documentation.

A reference of terms used throughout the Primer Checkout documentation. If you encounter an unfamiliar term while reading another guide, you can look it up here.

## Primer Platform

> [accordion] Client Session
>
> A server-side object you create through the [Primer API](https://primer.io/docs/checkout/client-session.md) before rendering the checkout. The client session holds everything Primer needs to present the correct payment experience: the order amount, currency, customer information, and which payment methods are available. Creating a client session returns a **client token**.

> [accordion] Client Token
>
> A short-lived string returned when you [create a client session](https://primer.io/docs/checkout/client-session.md). You pass it to the checkout component to initialize the session. Its length is not fixed, so treat it as an opaque string and do not rely on a maximum length when storing it.
>
> > [tab] Web
> >
> > ```html theme={"dark"}
> > <primer-checkout client-token="your-client-token"></primer-checkout>
> > ```
>
> > [tab] Android
> >
> > ```kotlin theme={"dark"}
> > val checkout = rememberPrimerCheckoutController(clientToken = "your-client-token")
> > ```
>
> > [tab] iOS
> >
> > ```swift theme={"dark"}
> > PrimerCheckout(clientToken: "your-client-token")
> > ```

> [accordion] Primer Dashboard
>
> The web interface where you configure your Primer account. From the Dashboard you can enable payment methods, set up processors, manage API keys, and configure checkout behavior — all without changing your frontend code.

> [accordion] Diagnostics ID
>
> A unique identifier attached to every error the SDK produces. When you contact Primer support about a failed payment or unexpected behavior, include the `diagnosticsId` so the team can locate the exact request in their logs.
>
> > [tab] Web
> >
> > ```javascript theme={"dark"}
> > checkout.addEventListener('primer:payment-failure', (event) => {
> >   const { error } = event.detail;
> >   console.error('Payment failed:', error.diagnosticsId);
> > });
> > ```
>
> > [tab] Android
> >
> > ```kotlin theme={"dark"}
> > val state by checkout.state.collectAsStateWithLifecycle()
> >
> > LaunchedEffect(state) {
> >     val s = state
> >     if (s is PrimerCheckoutState.Failure) {
> >         Log.e("Checkout", "diagnosticsId: ${s.primerError.diagnosticsId}")
> >     }
> > }
> > ```
>
> > [tab] iOS
> >
> > ```swift theme={"dark"}
> > if case let .failure(error, _) = state {
> >   print("Payment failed: \(error.diagnosticsId)")
> > }
> > ```

## SDK & Architecture

> [accordion] Primer Checkout SDK
>
> The client-side package that provides checkout UI components, payment logic, and event system. Available for Web (`@primer-io/primer-js`), Android (`io.primer:checkout`), and iOS (`PrimerSDK`).

> [accordion] Web Components (Web)
>
> A set of browser-native APIs for creating reusable, encapsulated UI elements. The Web SDK is built on Web Components, which means its elements (like `<primer-checkout>` and `<primer-card-form>`) work in any framework. See [Core Concepts](https://primer.io/docs/checkout/primer-checkout/core-concepts.md).

> [accordion] Shadow DOM (Web)
>
> A browser feature that isolates a component's internal HTML and CSS from the rest of the page. Every Web SDK component uses Shadow DOM. Because external CSS selectors can't reach inside, you customize appearance through **CSS variables** instead.

> [accordion] Controller (Android)
>
> A state holder created with a `remember*` function (e.g., `rememberPrimerCheckoutController()`). Provides observable state via `StateFlow` and action methods. Follows the standard Jetpack Compose pattern.

> [accordion] Composable (Android)
>
> A Kotlin function annotated with `@Composable` that describes a piece of UI. All Android SDK components are Composables that integrate naturally with Jetpack Compose.

> [accordion] StateFlow (Android)
>
> A Kotlin coroutines type for observable state. The SDK uses `StateFlow<PrimerCheckoutState>` for reactive UI updates. Collect with `collectAsStateWithLifecycle()` in Compose.

> [accordion] Session (iOS)
>
> An observable, `@MainActor` object that owns the checkout lifecycle and exposes the state and actions for a specific part of the checkout. [`PrimerCheckoutSession`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session) owns the top-level lifecycle and is attached with the `.primerCheckoutSession(_:theme:onCompletion:)` modifier. Per-feature sessions ([`PrimerCardFormSession`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-form-session) and [`PrimerSelectionSession`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/payment-methods-session)) are passed to the section slots of the composable views so you can read state and call actions from your custom UI. Examples are the `cardDetails`, `billingAddress` and `submitButton` slots of `PrimerCardForm`, and the `header` slot of `PrimerPaymentMethods`.

> [accordion] @Published / ObservableObject (iOS)
>
> The SwiftUI mechanism the SDK uses to expose observable state. Each session is an `ObservableObject` whose `@Published` properties drive reactive UI updates. `PrimerCheckoutSession` publishes `phase` and `clientSession`. `PrimerCardFormSession` and `PrimerSelectionSession` publish `state`, and `PrimerSelectionSession` also publishes `vaultedPaymentMethods`. Observe a session with `@StateObject` (when you own it) or `@ObservedObject` (when it is passed into a slot), and read these properties directly in your view's `body`.

> [accordion] PrimerCheckoutPresenter (iOS)
>
> A UIKit entry point class that presents the managed checkout modally from a `UIViewController` and delivers results through a [`PrimerCheckoutPresenterDelegate`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-presenter). Use this when integrating the SDK in a UIKit-based app.

> [accordion] Customization point
>
> A predefined area in a component where you can insert your own content. On Web, these are named HTML slot placeholders. On Android, these are `@Composable` lambda parameters (e.g., the `submitButton` parameter on `PrimerCardForm`). On iOS, these are slot parameters on the composable views (for example, the `submitButton` slot on `PrimerCardForm`). Section slots receive the relevant session so they can read state and call actions. Examples are the `cardDetails`, `billingAddress` and `submitButton` slots on `PrimerCardForm`, and the `header` and `emptyState` slots on `PrimerPaymentMethods`. Row slots, such as `method` on `PrimerPaymentMethods`, receive the row's data and a select action instead.

> [accordion] Design Token
>
> A named value (color, spacing, font size, corner radius) used to style components consistently. On Web, these are CSS variables (e.g., `--primer-color-brand`). On Android, they are properties in `PrimerTheme`. On iOS, they are properties in `PrimerCheckoutTheme`.

> [accordion] Defaults Object
>
> On Android, an object (e.g., `CardFormDefaults`, `PrimerCheckoutSheetDefaults`) that provides pre-built sub-components. Use them to customize specific parts while keeping others at their defaults.
>
> On iOS, the `CardFormDefaults`, `PaymentMethodsDefaults` and `VaultedPaymentMethodsDefaults` namespaces provide the default slot bodies and per-field building blocks. Examples are `CardFormDefaults.submitButton(_:)` and `CardFormDefaults.cardNumber(_:)`.

> [accordion] Hosted Input (Web)
>
> A card input field that renders inside a secure iframe managed by Primer. Sensitive card data never touches your page's DOM, keeping your integration PCI-compliant.

## Payment Concepts

> [accordion] Payment Method
>
> A way for a customer to pay — for example, a credit card, PayPal, Apple Pay, or Google Pay. Available payment methods are configured in the Primer Dashboard and delivered to the SDK through the client session. Each method has a type string such as `PAYMENT_CARD`, `PAYPAL`, or `APPLE_PAY`.

> [accordion] Vault / Vaulted Payment Methods
>
> Primer's system for securely storing a customer's payment details for future use. When vaulting is enabled, returning customers can pay with a saved card or payment method without re-entering their details. On Web, the SDK exposes vault data through the `primer:vault-methods-update` event and the `<primer-vault-manager>` component. On iOS, read `vaultedPaymentMethods` on `PrimerSelectionSession`, which is also available as `selection` on your `PrimerCheckoutSession`. Call `selectVaulted(_:)` to pay with a saved method and `delete(_:)` to remove one. You can also render the `PrimerVaultedPaymentMethods` view. It shows the selected saved method with a way to open the full list. See [SDK Options — Vault](https://primer.io/docs/checkout/primer-checkout/configuration/sdk-options.md).

> [accordion] Payment Instrument Data
>
> The details associated with a saved (vaulted) payment method. For a stored card this includes properties like `network` (e.g. `VISA`), `last4Digits`, `expirationMonth`, and `expirationYear`. You access it via the `paymentInstrumentData` property on a vaulted payment object.

> [accordion] PCI Compliance
>
> The Payment Card Industry Data Security Standard (PCI DSS). Primer Checkout handles card data securely so that sensitive information never enters your application, significantly reducing your PCI compliance scope.

> [accordion] 3DS (3D Secure)
>
> An authentication protocol that adds a verification step during card payments, typically a bank-issued challenge screen or biometric prompt. Primer Checkout handles 3DS flows automatically with no additional code required.

> [accordion] AUTO Payment Handling
>
> The default payment flow where the SDK processes the payment end-to-end. You receive success or failure events. On Web, this is the default mode. On Android, the composable module operates exclusively in AUTO mode. On iOS, the SDK also operates exclusively in AUTO mode. If you start it with `PrimerSettings(paymentHandling: .manual)`, it fails and reports a `.failure`. With `PrimerCheckoutSession`, that `.failure` ends the session.

> [accordion] Co-badge
>
> A card that belongs to multiple card networks (e.g., both Visa and Cartes Bancaires). The SDK shows a network selector for co-badged cards.

## Events

> [accordion] primer:ready
>
> The event fired when the SDK has fully initialized and is ready for interaction. Inside this event's handler you access the PrimerJS instance (`event.detail`) which provides SDK methods like `refreshSession()`, `getPaymentMethods()`, and `setCardholderName()`. See [Events Guide](https://primer.io/docs/checkout/primer-checkout/configuration/events.md).
>
> On Android, the equivalent is observing `checkout.state` for `PrimerCheckoutState.Ready` via `StateFlow`.
>
> On iOS, observe `phase` on your `PrimerCheckoutSession` and wait for `.ready`. From then on, `clientSession` is set. `onCompletion` only delivers outcomes (`.failure`, `.success` and `.dismissed`), never `.initializing` or `.ready`.

> [accordion] primer:payment-success / primer:payment-failure
>
> The events fired after a payment completes. `primer:payment-success` fires after a successful payment and the event detail includes the payment summary (order ID, last 4 digits, network). `primer:payment-failure` fires after a failed payment and includes the error object with the `diagnosticsId`. These are your primary integration points for redirects, confirmations, and error logging.
>
> ```javascript theme={"dark"}
> checkout.addEventListener('primer:payment-success', (event) => {
>   const { payment } = event.detail;
>   window.location.href = `/confirmation?order=${payment.orderId}`;
> });
>
> checkout.addEventListener('primer:payment-failure', (event) => {
>   const { error } = event.detail;
>   console.error('Payment failed:', error.diagnosticsId);
> });
> ```
>
> On Android, observe `checkout.state` and handle the terminal `PrimerCheckoutState.Success` and `PrimerCheckoutState.Failure` cases.
>
> On iOS, results arrive as a [`PrimerCheckoutState`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-state) in the `onCompletion` closure on `PrimerCheckout` or the `.primerCheckoutSession(_:theme:onCompletion:)` modifier. `.failure(error, checkoutData)` arrives once for each failed payment attempt, and the checkout stays open for a retry. The final `.success(result)` or `.dismissed` then arrives exactly once. With `PrimerCheckoutSession`, a failure during initialization arrives as a single `.failure` and ends the session. No retry screen appears, and no other outcome follows. In UIKit, implement these methods on the [`PrimerCheckoutPresenterDelegate`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-presenter): `primerCheckoutPresenterDidCompleteWithSuccess(_:)`, `primerCheckoutPresenterDidFailWithError(_:checkoutData:)` and `primerCheckoutPresenterDidDismiss()`. The delegate methods follow the same rules.

> [accordion] primer:payment-start
>
> The event fired when payment creation begins. You can intercept this event with `event.preventDefault()` to run validation before the payment is created. The event detail includes `continuePaymentCreation()` and `abortPaymentCreation()` handlers to control the payment flow. See [Events Guide](https://primer.io/docs/checkout/primer-checkout/configuration/events.md) for usage.
>
> On Android, payment interception is not available in the Composable module. Use the headless API (`onBeforePaymentCreated`) if you need this capability.
>
> On iOS, payment interception is available only in the inline integration. Set the `onBeforePaymentCreate` handler on the [`PrimerCheckoutSession`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session). It runs before every payment, saved payment methods included. Its decision handler lets you supply an idempotency key or abort payment creation. `PrimerCheckout` and `PrimerCheckoutPresenter` do not expose it.

## Integration Modes

> [accordion] Drop-in (Sheet / Full Component)
>
> An integration mode that provides a complete checkout flow with minimal code. On Web, use `<primer-checkout>`. On Android, use `PrimerCheckoutSheet`. On iOS, use `PrimerCheckout` as a SwiftUI view or `PrimerCheckoutPresenter` for UIKit. The SDK handles navigation between screens.

> [accordion] Inline (Custom Layout)
>
> An integration mode where you embed individual checkout components in your own layout. On Web, use individual components like `<primer-card-form>`. On Android, use `PrimerCheckoutHost` with child composables. On iOS, hold a `PrimerCheckoutSession` and apply the `.primerCheckoutSession(_:theme:onCompletion:)` modifier, then place composable views like `PrimerCardForm` and `PrimerPaymentMethods` in your own layout — override their `@ViewBuilder` slots to build custom forms. You control navigation and layout. On iOS, the SDK still presents follow-up screens in its own sheet over your content. These are the processing, success and failure screens, native payment method screens such as Klarna or ACH, saved payment method management, and CVV entry.


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