Events reference

This page is the complete API reference for every event and instance method exposed by Primer Checkout. Each entry documents the event name, when it dispatches, its payload shape, and the TypeScript types involved.

For integration guidance — where to listen, which events to combine, and real-world implementation patterns — see the Events Guide.

Category	Items
Initialization Events	`primer:ready`, `primer:methods-update`
State Events	`primer:state-change`
Card Form Events	`primer:bin-data-available`, `primer:bin-data-loading-change`, `primer:card-success`, `primer:card-error`
Payment Events	`primer:payment-start`, `primer:payment-success`, `primer:payment-failure`, `primer:payment-cancel`
Vault Events	`primer:vault-methods-update`, `primer:vault-selection-change`, `primer:show-other-payments-toggled`
Triggerable Events	`primer:card-submit`, `primer:vault-submit`, `primer:show-other-payments-toggle`
PrimerJS Instance Methods	`refreshSession()`, `getPaymentMethods()`, `setCardholderName()`, `vault.*`
Type Definitions	All TypeScript interfaces

Event lifecycle

Initialization

SDK loads, connects to the session, and signals readiness.

SDK →primer:ready

PrimerJS instance

SDK →primer:methods-update

available methods

SDK →primer:vault-methods-update

saved methods

Access SDK methods and pre-fill fields via PrimerJS

User Interaction

User enters card details; SDK detects BIN data and card network in real time.

SDK →primer:bin-data-loading-change

loading: true

SDK →primer:bin-data-available

BIN data + network

SDK →primer:bin-data-loading-change

loading: false

Update UI with card brand logo and issuer info

Payment Processing

User submits; SDK creates the payment and communicates with the server.

APP →primer:card-submit

(or button click)

SDK →primer:payment-start

intercept with preventDefault()

SDK →primer:state-change

isProcessing: true

Show spinner, disable submit button

Outcome

Server responds; SDK dispatches success or failure.

Success

primer:payment-success
state-change → isSuccessful: true

Failure

primer:payment-failure
state-change → paymentFailure: {...}

Handle primer:payment-success to redirect, or show error

DOM events

All Primer events are CustomEvent objects dispatched with bubbles: true and composed: true, allowing them to propagate through shadow DOM boundaries.

Initialization events

primer:ready

Dispatched once when the SDK is fully initialized. Payload: PrimerJS instance The PrimerJS instance is the primary interface for invoking SDK methods. See PrimerJS Instance Methods for the full surface.

checkout.addEventListener('primer:ready', (event) => {
  const primer = event.detail; // PrimerJS instance
});

primer:methods-update

Dispatched when available payment methods are loaded. Also re-dispatched after refreshSession(). Payload: InitializedPaymentMethod[] The payload is an array of available payment methods.

checkout.addEventListener('primer:methods-update', (event) => {
  const methods = event.detail; // InitializedPaymentMethod[]
  
  methods.forEach(method => {
    console.log(method.type); // e.g., 'PAYMENT_CARD', 'APPLE_PAY'
  });
});

State events

primer:state-change

Dispatched when SDK state changes during the payment lifecycle. Fires multiple times during a single payment flow. Payload: SdkState

Property	Type	Description
`isLoading`	`boolean`	SDK is loading resources
`isProcessing`	`boolean`	Payment is in progress
`isSuccessful`	`boolean`	Payment succeeded
`primerJsError`	`Error \| null`	SDK-level error (network, configuration)
`paymentFailure`	`PaymentFailure` `\| null`	Payment failure details

checkout.addEventListener('primer:state-change', (event) => {
  const state = event.detail; // SdkState
});

Card form events

primer:bin-data-available

Dispatched when BIN data is detected from user input in the card number field. Provides card network information, co-badged network alternatives, and additional issuer details when available. Payload: BinDataAvailableEvent

Property	Type	Description
`preferred`	`BinDataDetails` `\| undefined`	Recommended network based on `orderedAllowedCardNetworks`, or `undefined` if no network is allowed
`alternatives`	`BinDataDetails[]`	All detected networks excluding preferred, including disallowed ones
`status`	`'complete' \| 'partial'`	`complete` when full BIN data is available (8+ digits), `partial` for local-only detection
`firstDigits`	`string \| undefined`	The first digits (BIN prefix) of the card number, when available

checkout.addEventListener('primer:bin-data-available', (event) => {
  const { preferred, alternatives, status } = event.detail; // BinDataAvailableEvent
});

primer:bin-data-loading-change

Dispatched when BIN data retrieval starts or finishes. Use this to show a loading indicator while card information is being fetched from Primer’s servers. Payload: BinDataLoadingChangeEvent

Property	Type	Description
`loading`	`boolean`	`true` when BIN data retrieval starts, `false` when it completes

checkout.addEventListener('primer:bin-data-loading-change', (event) => {
  const { loading } = event.detail; // BinDataLoadingChangeEvent
});

primer:card-success

Dispatched when card form submission succeeds. Payload: CardSubmitSuccessPayload

Property	Type	Description
`result.success`	`boolean`	Submission succeeded
`result.token`	`string`	Payment token
`result.paymentId`	`string`	Payment ID

checkout.addEventListener('primer:card-success', (event) => {
  const payload = event.detail; // CardSubmitSuccessPayload
});

primer:card-error

Dispatched when card form validation fails on submission. Payload: CardSubmitErrorsPayload

Property	Type	Description
`errors`	`InputValidationError[]`	Validation errors for each invalid field

checkout.addEventListener('primer:card-error', (event) => {
  const payload = event.detail; // CardSubmitErrorsPayload
});

Payment events

primer:payment-start

Dispatched when payment creation begins. Use event.preventDefault() to intercept the payment flow for validation. Payload: PaymentStartData

Property	Type	Description
`paymentMethodType`	`string`	Payment method being used (e.g., `"PAYMENT_CARD"`)
`abortPaymentCreation`	`() => void`	Call to cancel payment creation
`continuePaymentCreation`	`(data?) => void`	Call to proceed with payment (optionally with `idempotencyKey`)
`timestamp`	`number`	Unix timestamp (seconds)

checkout.addEventListener('primer:payment-start', (event) => {
  const { paymentMethodType, continuePaymentCreation, abortPaymentCreation } = event.detail;
  
  // Intercept payment for validation
  event.preventDefault();
  
  if (termsAccepted) {
    continuePaymentCreation();
  } else {
    abortPaymentCreation();
  }
});

If you call event.preventDefault(), you must call either continuePaymentCreation() or abortPaymentCreation(). If neither is called, the payment will hang indefinitely.

primer:payment-success

Dispatched when payment completes successfully. Payload: PaymentSuccessData

Property	Type	Description
`payment`	`PaymentSummary`	PII-filtered payment data
`paymentMethodType`	`string`	e.g., `"PAYMENT_CARD"`, `"APPLE_PAY"`
`timestamp`	`number`	Unix timestamp (seconds)

checkout.addEventListener('primer:payment-success', (event) => {
  const { payment, paymentMethodType } = event.detail;
  console.log('Payment ID:', payment.id);
  window.location.href = '/confirmation';
});

primer:payment-failure

Dispatched when payment fails. Payload: PaymentFailureData

Property	Type	Description
`error`	`{ code: string; message: string; diagnosticsId?: string \| null; data?: Record<string, unknown> }`	Structured error information
`payment`	`PaymentSummary` `\| undefined`	Payment data, if available at time of failure
`paymentMethodType`	`string`	Payment method used
`timestamp`	`number`	Unix timestamp (seconds)

checkout.addEventListener('primer:payment-failure', (event) => {
  const { error, payment } = event.detail;
  console.error('Payment failed:', error.message);
});

primer:payment-cancel

Dispatched when a payment is cancelled by the user (e.g., dismissing Apple Pay or closing a payment popup). Payload: PaymentCancelData

Property	Type	Description
`paymentMethodType`	`string`	Payment method that was being used
`timestamp`	`number`	Unix timestamp (seconds)

document.addEventListener('primer:payment-cancel', (event) => {
  const data = event.detail; // PaymentCancelData
});

Vault Events

primer:vault-methods-update

Dispatched when vaulted payment methods are loaded or updated. Payload: VaultedMethodsUpdateData

Property	Type	Description
`vaultedPayments`	`VaultedPaymentMethodSummary[]`	Array of vaulted methods
`cvvRecapture`	`boolean`	Whether CVV re-entry is required
`timestamp`	`number`	Unix timestamp (seconds)

checkout.addEventListener('primer:vault-methods-update', (event) => {
  const { vaultedPayments, cvvRecapture } = event.detail;
  
  vaultedPayments.forEach(method => {
    console.log(method.paymentInstrumentData?.last4Digits);
  });
});

primer:vault-selection-change

Dispatched when a vaulted payment method is selected or deselected. Payload: VaultSelectionChangeData

Property	Type	Description
`paymentMethodId`	`string \| null`	ID of the selected method, or `null` if deselected
`timestamp`	`number`	Unix timestamp (seconds)

checkout.addEventListener('primer:vault-selection-change', (event) => {
  const { paymentMethodId } = event.detail;
});

primer:show-other-payments-toggled

Dispatched when the “show other payments” toggle state changes. Payload: ShowOtherPaymentsToggledPayload

Property	Type	Description
`expanded`	`boolean`	Current toggle state

checkout.addEventListener('primer:show-other-payments-toggled', (event) => {
  const { expanded } = event.detail;
});

Triggerable events

These events can be dispatched by your code to control the SDK. All triggerable events must be dispatched with bubbles: true and composed: true to cross shadow DOM boundaries.

primer:card-submit

Triggers card form submission programmatically.

document.dispatchEvent(new CustomEvent('primer:card-submit', {
  bubbles: true,
  composed: true,
}));

primer:vault-submit

Triggers vault payment submission programmatically.

document.dispatchEvent(new CustomEvent('primer:vault-submit', {
  bubbles: true,
  composed: true,
}));

primer:show-other-payments-toggle

Toggles the “other payment methods” section.

document.dispatchEvent(new CustomEvent('primer:show-other-payments-toggle', {
  bubbles: true,
  composed: true,
}));

PrimerJS instance methods

The PrimerJS instance is received from the primer:ready event.

refreshSession()

Synchronizes the client-side SDK with server-side session updates. Triggers a new primer:methods-update event.

Parameter	Type	Description
(none)	—	—
Returns	`Promise<void>`	Resolves when sync is complete

await primer.refreshSession();

getPaymentMethods()

Returns the cached list of available payment methods.

Parameter	Type	Description
(none)	—	—
Returns	`PaymentMethodInfo[]`	Available payment methods

const methods = primer.getPaymentMethods();

setCardholderName()

Sets the cardholder name field programmatically. Must be called after primer:ready.

Parameter	Type	Description
`name`	`string`	Cardholder name
Returns	`void`	—

primer.setCardholderName('Jane Doe');

Vault API

vault.createCvvInput()

Creates a CVV input element for CVV recapture in headless mode.

Parameter	Type	Description
`options.cardNetwork`	`string`	Card network (e.g. `'VISA'`)
`options.container`	`string`	CSS selector for the container element
`options.placeholder`	`string`	Placeholder text
Returns	`Promise<CvvInputInstance>`	The created CVV input

const cvvInput = await primer.vault.createCvvInput({
  cardNetwork: 'VISA',
  container: '#cvv-container',
  placeholder: 'CVV',
});

vault.startPayment()

Initiates payment with the selected vaulted method.

Parameter	Type	Description
`paymentMethodId`	`string`	ID of the vaulted payment method
`options`	`object`	Optional payment options
`options.cvv`	`string`	CVV value for card payments requiring re-capture
Returns	`Promise<void>`	Resolves when payment flow is initiated

// Basic usage
await primer.vault.startPayment(paymentMethodId);

// With CVV for cards requiring re-capture
await primer.vault.startPayment(paymentMethodId, { cvv: '123' });

vault.delete()

Deletes a vaulted payment method.

Parameter	Type	Description
`paymentMethodId`	`string`	ID of the vaulted payment method
Returns	`Promise<void>`	Resolves when deletion is complete

await primer.vault.delete(paymentMethodId);

For a complete headless vault implementation walkthrough, see the Headless Vault Guide.

Type definitions

PaymentStartData

interface PaymentStartData {
  paymentMethodType: string;
  abortPaymentCreation: () => void;
  continuePaymentCreation: (data?: { idempotencyKey?: string }) => void;
  timestamp: number;
}

PaymentSuccessData

interface PaymentSuccessData {
  payment: PaymentSummary;
  paymentMethodType?: string;
  timestamp: number;
}

PaymentFailureData

interface PaymentFailureData {
  error: {
    code: string;
    message: string;
    diagnosticsId?: string | null;
    data?: Record<string, unknown>;
  };
  payment?: PaymentSummary;
  paymentMethodType?: string;
  timestamp: number;
}

PaymentCancelData

interface PaymentCancelData {
  paymentMethodType: string;
  timestamp: number;
}

PaymentSummary

A PCI-compliant payment summary with minimal PII exposure. Contains payment identifiers and filtered payment method data.

interface PaymentSummary {
  /** Payment ID from Primer API */
  id: string;
  /** Order ID/reference from merchant */
  orderId: string;
  /** Filtered payment method data (only safe fields exposed) */
  paymentMethodData?: {
    /** Payment method type (e.g., "PAYMENT_CARD", "PAYPAL") */
    paymentMethodType?: string;
    /** Last 4 digits of card (cards only) */
    last4Digits?: string;
    /** Card network (e.g., "VISA", "MASTERCARD") - cards only */
    network?: string;
    /** Last 4 digits of account number (ACH only) */
    accountNumberLastFourDigits?: string;
    /** Bank name (ACH only) */
    bankName?: string;
  };
}

PaymentFailure

interface PaymentFailure {
  code: string;
  message: string;
  diagnosticsId?: string | null;
  data?: Record<string, unknown>;
}

SdkState

interface SdkState {
  isSuccessful: boolean;
  isProcessing: boolean;
  primerJsError: Error | null;
  isLoading: boolean;
  paymentFailure: PaymentFailure | null;
}

BinDataAvailableEvent

interface BinDataAvailableEvent {
  /** Recommended network based on orderedAllowedCardNetworks */
  preferred?: BinDataDetails;
  /** All detected networks excluding preferred */
  alternatives: BinDataDetails[];
  /** 'complete' when full BIN data is available, 'partial' for local-only detection */
  status: 'complete' | 'partial';
  /** First digits (BIN prefix) of the card number */
  firstDigits?: string;
}

BinDataDetails

interface BinDataDetails {
  /** Human-readable name for the card network */
  displayName: string;
  /** Card network identifier in Primer's systems */
  network: string;
  /** Whether the network is allowed per orderedAllowedCardNetworks */
  allowed: boolean;
  /** ISO 3166-1 alpha-2 country code of the card issuer */
  issuerCountryCode?: string;
  /** Name of the card issuer (e.g., bank name) */
  issuerName?: string;
  /** Account funding type (e.g., "CREDIT", "DEBIT", "PREPAID") */
  accountFundingType?: string;
  /** Whether a prepaid card is reloadable */
  prepaidReloadableIndicator?: string;
  /** Usage type of the card product (e.g., "CONSUMER", "COMMERCIAL") */
  productUsageType?: string;
  /** Product code assigned by the card network */
  productCode?: string;
  /** Product name assigned by the card network (e.g., "Visa Signature") */
  productName?: string;
  /** ISO 4217 currency code associated with the card issuer */
  issuerCurrencyCode?: string;
  /** Regional restrictions that apply to the card */
  regionalRestriction?: string;
  /** Type of account number (e.g., "PAN", "TOKEN") */
  accountNumberType?: string;
}

BinDataLoadingChangeEvent

interface BinDataLoadingChangeEvent {
  /** true when BIN data retrieval starts, false when it completes */
  loading: boolean;
}

CardSubmitSuccessPayload

interface CardSubmitSuccessPayload {
  result: {
    success: boolean;
    token: string;
    paymentId: string;
  };
}

CardSubmitErrorsPayload

interface CardSubmitErrorsPayload {
  errors: InputValidationError[];
}

InputValidationError

interface InputValidationError {
  field: string;
  name: string;
  error: string;
}

VaultedMethodsUpdateData

interface VaultedMethodsUpdateData {
  vaultedPayments: VaultedPaymentMethodSummary[];
  cvvRecapture: boolean;
  timestamp: number;
}

VaultedPaymentMethodSummary

interface VaultedPaymentMethodSummary {
  id: string;
  analyticsId: string;
  paymentMethodType: string;
  paymentInstrumentType: string;
  paymentInstrumentData?: {
    // Card fields
    last4Digits?: string;
    network?: string;
    cardholderName?: string;
    expirationMonth?: string;
    expirationYear?: string;
    // PayPal fields
    email?: string;
    firstName?: string;
    lastName?: string;
    externalPayerId?: string;
  };
  isSelected?: boolean;
}

VaultSelectionChangeData

interface VaultSelectionChangeData {
  paymentMethodId: string | null;
  timestamp: number;
}

ShowOtherPaymentsToggledPayload

interface ShowOtherPaymentsToggledPayload {
  expanded: boolean;
}

InitializedPaymentMethod

interface InitializedPaymentMethod {
  type: string;
  // Additional properties vary by payment method type
}

Events guide

When, why, and how to use events in your integration

SDK options reference

Configuration options for <primer-checkout>

Headless vault guide

Custom vault UI implementation

Primer Checkout Web

​Quick navigation

​Event lifecycle

​DOM events

​Initialization events

​primer:ready

​primer:methods-update

​State events

​primer:state-change

​Card form events

​primer:bin-data-available

​primer:bin-data-loading-change

​primer:card-success

​primer:card-error

​Payment events

​primer:payment-start

​primer:payment-success

​primer:payment-failure

​primer:payment-cancel

​Vault Events

​primer:vault-methods-update

​primer:vault-selection-change

​primer:show-other-payments-toggled

​Triggerable events

​primer:card-submit

​primer:vault-submit

​primer:show-other-payments-toggle

​PrimerJS instance methods

​refreshSession()

​getPaymentMethods()

​setCardholderName()

​Vault API

​vault.createCvvInput()

​vault.startPayment()

​vault.delete()

​Type definitions

​PaymentStartData

​PaymentSuccessData

​PaymentFailureData

​PaymentCancelData

​PaymentSummary

​PaymentFailure

​SdkState

​BinDataAvailableEvent

​BinDataDetails

​BinDataLoadingChangeEvent

​CardSubmitSuccessPayload

​CardSubmitErrorsPayload

​InputValidationError

​VaultedMethodsUpdateData

​VaultedPaymentMethodSummary

​VaultSelectionChangeData

​ShowOtherPaymentsToggledPayload

​InitializedPaymentMethod

​See also

Events guide

SDK options reference

Headless vault guide

Quick navigation

Event lifecycle

DOM events

Initialization events

primer:ready

primer:methods-update

State events

primer:state-change

Card form events

primer:bin-data-available

primer:bin-data-loading-change

primer:card-success

primer:card-error

Payment events

primer:payment-start

primer:payment-success

primer:payment-failure

primer:payment-cancel

Vault Events

primer:vault-methods-update

primer:vault-selection-change

primer:show-other-payments-toggled

Triggerable events

primer:card-submit

primer:vault-submit

primer:show-other-payments-toggle

PrimerJS instance methods

refreshSession()

getPaymentMethods()

setCardholderName()

Vault API

vault.createCvvInput()

vault.startPayment()

vault.delete()

Type definitions

PaymentStartData

PaymentSuccessData

PaymentFailureData

PaymentCancelData

PaymentSummary

PaymentFailure

SdkState

BinDataAvailableEvent

BinDataDetails

BinDataLoadingChangeEvent

CardSubmitSuccessPayload

CardSubmitErrorsPayload

InputValidationError

VaultedMethodsUpdateData

VaultedPaymentMethodSummary

VaultSelectionChangeData

ShowOtherPaymentsToggledPayload

InitializedPaymentMethod

See also