Events reference

Complete API reference for all Primer SDK events, instance methods, and type definitions

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.

Quick navigation

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, primer:payment-approval-required
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

---

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
payment	PaymentSummary | undefined	Payment data, available when a payment was already created before cancellation
timestamp	number	Unix timestamp (seconds)

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

---

primer:payment-approval-required

Dispatched on a MANUAL approval session when the customer submits a payment. Primer tokenizes the payment method and prepares a payment attempt, but does not create the payment; it waits for your backend to approve or abort the attempt. See the Manual payment approval guide.

Payload: PaymentApprovalRequiredData

Property	Type	Description
clientSessionId	string	The client session identifier
paymentAttemptId	string	Identifies the attempt; required when calling /approve or /abort
paymentMethodToken	PaymentMethodToken	The tokenized payment method (e.g., card network, last 4 digits) for fraud or risk checks
continueFlow	() => Promise<void>	Call after your backend approves or aborts; resolves once the result screen is shown
timestamp	number	Unix timestamp (seconds)

checkout.addEventListener('primer:payment-approval-required', async (event) => {
  const { paymentAttemptId, continueFlow } = event.detail;

  // Your backend calls POST /payment-attempts/{id}/approve (or /abort)
  await fetch('/my-backend/handle-payment-approval', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ paymentAttemptId }),
  });

  await continueFlow();
});

If the page is refreshed while an attempt is still awaiting approval, this event is re-emitted. Deduplicate on paymentAttemptId so you don’t approve the same attempt twice.

---

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;
  payment?: PaymentSummary;
  timestamp: number;
}

PaymentApprovalRequiredData

interface PaymentApprovalRequiredData {
  clientSessionId: string;
  paymentAttemptId: string;
  paymentMethodToken: PaymentMethodToken;
  continueFlow: () => Promise<void>;
  timestamp: number;
}

PaymentMethodToken

The tokenized payment method surfaced with the approval event. Exposes only non-sensitive fields.

interface PaymentMethodToken {
  /** The payment method token */
  token: string;
  analyticsId: string;
  /** e.g., "SINGLE_USE" */
  tokenType: string;
  /** e.g., "PAYMENT_CARD" */
  paymentInstrumentType: string;
  /** Safe payment method details (card example shown) */
  paymentInstrumentData: {
    last4Digits?: string;
    cardholderName?: string;
    network?: string;
  };
  vaultData: unknown | null;
  threeDSecureAuthentication: unknown | null;
}

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
}

---

See also

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