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.
This guide focuses on when and why to use each event. For the complete API surface, every event name, payload shape, and type definition see the Events Reference. How Primer events work
Primer Checkout components dispatch 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.
Choosing where to listen
The first decision in any integration is where to attach your event listeners. Both options receive the same events - the difference is scope and architecture fit.
Component Level
Document Level
Attach listeners directly to the <primer-checkout> element. Each listener is scoped to a single checkout instance.const checkout = document.querySelector('primer-checkout');
checkout.addEventListener('primer:payment-success', (event) => {
// This listener only fires for this checkout instance
const { payment } = event.detail;
window.location.href = `/confirmation?id=${payment.id}`;
});
- Your page renders more than one checkout (e.g. a multi-cart experience) and each needs independent handling.
- 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.
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.document.addEventListener('primer:payment-success', (event) => {
// Fires for any primer-checkout instance on the page
analytics.track('payment_completed', event.detail);
});
- You have a single checkout per page and prefer centralized event handling.
- You’re building cross-cutting concerns like analytics, logging, or error monitoring that should capture events from any checkout instance.
- 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.
// 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);
}
});
useEffect, Vue’s onMounted, etc.), prefer that over DOMContentLoaded.
Phase 1: Initialization
Every Primer Checkout integration begins with the primer:ready event. This event fires once, after the SDK has fully initialized, and it delivers the PrimerJS instance as event.detail. You need this instance to pre-fill form fields and call SDK methods.
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.
});
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.
Phase 2: Payment method discovery
Shortly after initialization, 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.
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.some(
(m) => m.type === 'APPLE_PAY' || m.type === 'GOOGLE_PAY'
);
document.getElementById('express-checkout-section').hidden = !hasExpressMethod;
});
<primer-payment-method> elements dynamically. The Headless Vault Guide covers that pattern in detail.
Phase 3: User interaction
As the user fills in card details, the SDK emits events that let you respond to their input in real time.
Showing the Card Network
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.
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}`);
}
});
primer:bin-data-loading-change:
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;
});
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 for the full payload shape.primer:card-submit to tell the SDK to validate and submit the card form.
document.getElementById('custom-pay-button').addEventListener('click', () => {
document.dispatchEvent(
new CustomEvent('primer:card-submit', {
bubbles: true,
composed: true,
}),
);
});
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.
primer:vault-submit in the same way. See the Events Reference and Triggerable Events for the full list of events you can dispatch.
Phase 4: Payment processing and outcome
Once the user submits, the SDK moves through a processing → outcome sequence. The primer:state-change event fires at every step, giving you a single stream to drive your UI state.
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);
}
});
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).
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. The primer:payment-start event gives you that interception point.
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 data.paymentMethodType to apply method-specific logic
// You can also pass an idempotency key which will be sent with the payment request to prevent duplicate payments from being created
continuePaymentCreation({ idempotencyKey: 'my-unique-key' });
});
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.
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 for the full type definition.
Working with Vaulted Payment Methods
If your integration supports saved (vaulted) payment methods, two additional events become relevant:
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.
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);
}
});
primer.vault.createCvvInput(), primer.vault.startPayment(), and primer.vault.delete() see the Headless Vault Guide.
Debugging tips
- 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.
See also
