Skip to main content
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, type definition, and callback signature see the platform-specific SDK references.

​
How 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

Each platform has its own mechanism for receiving SDK events and state changes.
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: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.

​
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);
  }
});
If your framework provides a lifecycle hook that runs after the component mounts (React’s useEffect, Vue’s onMounted, etc.), prefer that over DOMContentLoaded.

​
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.
The primer:ready event fires once after the SDK has fully initialized. It delivers the PrimerJS instance as event.detail.
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 provides information about available payment methods for the current session.
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.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 covers that pattern in detail.

​
Phase 3: User interaction

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

​
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}`);
  }
});
To show a loading indicator while BIN data is being fetched, listen for 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.

​
Triggering Submission from a Custom Button

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.
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.
For vault payment submission from a custom button, dispatch 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 to 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).

​
Event timing

Events may fire multiple times during a single checkout session (for example, if the user retries after a failure).
  • 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

​
Dismissal and session refresh

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.

​
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 paymentMethodType to apply method-specific logic
  continuePaymentCreation();
});
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.
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 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.
  • 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);
  }
});
For full headless vault implementation, including primer.vault.createCvvInput(), primer.vault.startPayment(), and primer.vault.delete() see the Headless Vault Guide.

​
Event flow overview

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

​
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

Web events reference

Every Web event name, payload type, callback signature, and instance method

Android SDK reference

Android SDK API documentation

Recipes

Use-case driven examples for common integration scenarios

Error handling

Deep dive into error handling, retries, and failure recovery