Skip to main content
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

A server-side object you create through the Primer API 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.
A short-lived string returned when you create a client session. You pass it to the checkout component to initialize the session.
<primer-checkout client-token="your-client-token"></primer-checkout>
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.
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.
checkout.addEventListener('primer:payment-failure', (event) => {
  const { error } = event.detail;
  console.error('Payment failed:', error.diagnosticsId);
});

​
SDK & Architecture

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).
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.
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.
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.
A Kotlin function annotated with @Composable that describes a piece of UI. All Android SDK components are Composables that integrate naturally with Jetpack Compose.
A Kotlin coroutines type for observable state. The SDK uses StateFlow<PrimerCheckoutState> for reactive UI updates. Collect with collectAsStateWithLifecycle() in Compose.
A typed protocol that exposes the state, actions, and customization points for a specific part of the checkout. Scopes (e.g., PrimerCheckoutScope, PrimerCardFormScope, PrimerPaymentMethodSelectionScope) are the primary API surface for Primer Checkout iOS.
A Swift concurrency primitive used to observe state changes over time. Each scope exposes its state as AsyncStream<State>. Observe with for await state in scope.state.
A UIKit helper class that presents PrimerCheckout as a modal sheet from a UIViewController. Use this when integrating the SDK in a UIKit-based app.
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 closure properties on scopes that return AnyView.
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.
An object (e.g., CardFormDefaults, PrimerCheckoutSheetDefaults) that provides pre-built sub-components. Use them to customize specific parts while keeping others at their defaults.
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

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.
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. The SDK exposes vault data through the primer:vault-methods-update event and the <primer-vault-manager> component. See SDK Options — Vault.
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.
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.
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.
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.
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

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.On Android, the equivalent is observing checkout.state for PrimerCheckoutState.Ready via StateFlow.
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.
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, handle PrimerCheckoutEvent.Success and PrimerCheckoutEvent.Failure in the onEvent callback.On iOS, observe checkoutScope.state for .success(result) and .failure(error) cases, or use the onCompletion callback.
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 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, use the onBeforePaymentCreate handler on the checkout scope for payment interception.

​
Integration Modes

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.
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, use the scope closure to access PrimerCardFormScope and build custom form layouts. You control navigation and layout.