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 <primer-checkout> via the client-token attribute to initialize the checkout. The token authenticates the session and carries the configuration the SDK needs to render payment methods and process payments.
<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 JavaScript package (@primer-io/primer-js) that provides the checkout UI components, payment logic, and event system. You install it via npm and call loadPrimer() to register the web components in the browser.
A set of browser-native APIs for creating reusable, encapsulated UI elements. Primer Checkout is built on Web Components, which means its elements (like <primer-checkout> and <primer-card-form>) work in any framework — React, Vue, Svelte, or plain HTML — without adapters or wrappers. See Core Concepts for more detail.
A browser feature that isolates a component’s internal HTML and CSS from the rest of the page. Every Primer component uses Shadow DOM, which prevents your styles from accidentally breaking the checkout and prevents checkout styles from leaking into your app. Because external CSS selectors can’t reach inside the Shadow DOM, you customize appearance through CSS variables instead.
A named placeholder inside a Web Component where you can insert your own content. Primer components expose slots so you can control layout and inject custom elements without modifying internal markup. For example, the main slot on <primer-checkout> and the payments slot on <primer-main>. See Layout Customization.
CSS variables (e.g. --primer-color-brand) that Primer exposes as its styling API. Because CSS variables can cross Shadow DOM boundaries, they are the supported way to customize colors, spacing, typography, border radius, and other visual aspects of checkout components. Primer’s documentation sometimes refers to these as design tokens. See the Design Tokens Explorer.
A card input field (card number, expiry, CVV) that renders inside a secure iframe managed by Primer. Sensitive card data is captured directly by Primer’s servers and never touches your page’s DOM, keeping your integration PCI-compliant without additional certification effort.

​
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. In code, each method has a type string such as PAYMENT_CARD, PAYPAL, or APPLE_PAY.
The string identifier for a specific payment method. You’ll see it in event payloads (e.g. paymentMethodType: 'PAYMENT_CARD') and as the type attribute on <primer-payment-method>. Common values include PAYMENT_CARD, PAYPAL, APPLE_PAY, GOOGLE_PAY, and KLARNA.
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) — a set of requirements for any system that handles credit card data. Primer Checkout’s hosted inputs handle card data inside secure iframes so that sensitive information never enters your page, 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 — including rendering challenge screens and processing the result — with no additional code required.

​
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.
The event fired whenever the checkout’s state changes. The event detail includes boolean flags like isProcessing (payment is in progress) and isSuccessful (payment completed), as well as error objects like paymentFailure and primerJsError. Use it to drive UI updates such as loading spinners, button states, and error messages.
The event fired when the SDK has determined which payment methods are available for the current session. The event detail provides the list of methods, which you can use to dynamically render <primer-payment-method> elements.
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);
});
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.

​
Components

The root component that initializes the SDK and provides context for all child components. It accepts the client-token attribute and dispatches top-level events like primer:ready and primer:state-change.
The layout component that renders the default checkout UI inside <primer-checkout>. It provides the payments and checkout-complete slots for layout customization. You can bypass it entirely for fully custom implementations.
A container component that provides context for card input fields. It must wrap all card input components (primer-input-card-number, primer-input-card-expiry, primer-input-cvv, primer-input-cardholder-name). See Build a Custom Card Form.
A component that renders a specific payment method’s UI. Set the type attribute to the desired payment method type (e.g. PAYMENT_CARD, PAYPAL). If the specified method isn’t available in the current session, the component renders nothing.
A component that manages the display and interaction of saved (vaulted) payment methods for returning customers.
A pre-built component that automatically displays payment error messages. Use it as a simpler alternative to building custom error handling with events.