Events & Callbacks Reference

This page is the complete API reference for every event, callback, 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:card-network-change`, `primer:card-success`, `primer:card-error`
Payment Events	`primer:payment-start`, `primer:payment-success`, `primer:payment-failure`
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 Callbacks	`onPaymentStart`, `onPaymentPrepare`, `onPaymentSuccess`, `onPaymentFailure`, `onVaultedMethodsUpdate`
PrimerJS Instance Methods	`refreshSession()`, `getPaymentMethods()`, `setCardholderName()`, `vault.*`
Type Definitions	All TypeScript interfaces

Callbacks vs DOM Events

Important: Callbacks and DOM events have slightly different payload structures for the same data:

Data	Callback property	Event property
Payment summary	`payment`	`paymentSummary`
CVV recapture flag	`cvvRecapture` (available)	(not available)

Example:

// Callback approach
primer.onPaymentSuccess = (data) => {
  console.log(data.payment.id);  // ← "payment"
};

// Event approach
checkout.addEventListener('primer:payment-success', (event) => {
  console.log(event.detail.paymentSummary.id);  // ← "paymentSummary"
});

See the Type Definitions section for complete interface details.

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

User Interaction

User enters card details; SDK detects the card network in real time.

SDK →primer:card-network-change

Visa detected

Update UI with card brand logo

Payment Processing

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

APP →primer:card-submit

(or button click)

SDK →primer:state-change

isProcessing: true

SDK →primer:payment-start

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: {...}

Redirect on success via onPaymentSuccess, 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 configuring callbacks and invoking SDK methods. See PrimerJS Callbacks and 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: InitializedPayments instance

Method	Returns	Description
`toArray()`	`InitializedPaymentMethod[]`	All available payment methods
`size()`	`number`	Count of available methods
`get(type)`	`InitializedPaymentMethod \| undefined`	Look up a method by its `type` string

checkout.addEventListener('primer:methods-update', (event) => {
  const methods = event.detail; // InitializedPayments
});

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:card-network-change

Dispatched when the card network is detected from user input in the card number field. Payload: CardNetworksContextType

Property	Type	Description
`detectedCardNetwork`	`CardNetwork` `\| null`	Detected network, or `null` if undetected
`selectableCardNetworks`	`CardNetwork[]`	Co-branded network options (e.g. Carte Bancaire / Visa)
`isLoading`	`boolean`	Network detection is in progress

checkout.addEventListener('primer:card-network-change', (event) => {
  const context = event.detail; // CardNetworksContextType (can be null)
  const network = event.detail?.detectedCardNetwork?.network;
});

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. Payload: None

document.addEventListener('primer:payment-start', () => {
  // Payment creation has started
});

primer:payment-success

Dispatched when payment completes successfully. Payload: PaymentSuccessData

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

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

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
`paymentSummary`	`PaymentSummary` `\| undefined`	Payment data, if available at time of failure
`paymentMethodType`	`string`	Payment method used
`timestamp`	`number`	Unix timestamp (seconds)

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

Vault Events

primer:vault:methods-update

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

Property	Type	Description
`vaultedPayments`	`InitializedVaultedPayments`	Vaulted methods collection
`timestamp`	`number`	Unix timestamp (seconds)

Need cvvRecapture? The cvvRecapture flag is only available via the onVaultedMethodsUpdate callback, not this DOM event. Use the callback if you need to know whether CVV re-entry is required.

InitializedVaultedPayments methods:

Method	Returns	Description
`toArray()`	`VaultedPaymentMethodSummary[]`	All vaulted methods
`size()`	`number`	Count of vaulted methods
`get(id)`	`VaultedPaymentMethodSummary \| undefined`	Look up a vaulted method by ID

document.addEventListener('primer:vault:methods-update', (event) => {
  const data = event.detail; // VaultedMethodsUpdateData
});

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)

document.addEventListener('primer:vault:selection-change', (event) => {
  const data = event.detail; // VaultSelectionChangeData
});

primer:show-other-payments-toggled

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

Property	Type	Description
`expanded`	`boolean`	Current toggle state
`timestamp`	`number`	Unix timestamp (seconds)

document.addEventListener('primer:show-other-payments-toggled', (event) => {
  const data = event.detail; // ShowOtherPaymentsToggledPayload
});

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 Callbacks

Set these callbacks on the PrimerJS instance received from the primer:ready event.

onPaymentStart

Called when payment creation begins.

Parameter	Type	Description
(none)	—	—

primer.onPaymentStart = () => {};

onPaymentPrepare

Called before payment is created. Allows validation or aborting.

Parameter	Type	Description
`data`	`{ paymentMethodType: string }`	Payment method being used
`handler`	`PrepareHandler`	Control object

PrepareHandler methods:

Method	Returns	Description
`continuePaymentCreation()`	`void`	Proceed with payment creation
`abortPaymentCreation()`	`void`	Cancel payment creation

primer.onPaymentPrepare = (data, handler) => {
  handler.continuePaymentCreation(); // or handler.abortPaymentCreation()
};

onPaymentSuccess

Called when payment succeeds.

Parameter	Type	Description
`data`	`PaymentSuccessData`	Payment result data

primer.onPaymentSuccess = (data) => {};

onPaymentFailure

Called when payment fails.

Parameter	Type	Description
`data`	`PaymentFailureData`	Error and payment data

primer.onPaymentFailure = (data) => {};

onVaultedMethodsUpdate

Called when vaulted payment methods are loaded or updated.

Parameter	Type	Description
`data`	`VaultedMethodsUpdateData`	Vaulted payments and CVV recapture flag

primer.onVaultedMethodsUpdate = (data) => {};

PrimerJS Instance Methods

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.

Deprecated Methods

These methods are deprecated and will be removed in a future release. Use the primer.vault.* equivalents.

Deprecated Method	Replacement
`primer.createCvvInput(options)`	`primer.vault.createCvvInput(options)`
`primer.startVaultPayment(id, options?)`	`primer.vault.startPayment(paymentMethodId, options?)`

Type Definitions

PaymentSuccessData

Callback vs Event payload difference: The callback (onPaymentSuccess) uses payment, while the DOM event (primer:payment-success) uses paymentSummary. Both contain the same PaymentSummary data.

// Callback payload (onPaymentSuccess)
interface PaymentSuccessData {
  payment: PaymentSummary;
  paymentMethodType?: string;
  timestamp: number;
}

// Event payload (primer:payment-success)
interface PaymentSuccessEventDetail {
  paymentSummary: PaymentSummary;
  paymentMethodType?: string;
  timestamp: number;
}

PaymentFailureData

Callback vs Event payload difference: The callback (onPaymentFailure) uses payment, while the DOM event (primer:payment-failure) uses paymentSummary. Both contain the same PaymentSummary data.

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

// Event payload (primer:payment-failure)
interface PaymentFailureEventDetail {
  error: {
    code: string;
    message: string;
    diagnosticsId?: string | null;
    data?: Record<string, unknown>;
  };
  paymentSummary?: PaymentSummary;
  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;
}

CardNetworksContextType

type CardNetworksContextType = {
  detectedCardNetwork: CardNetwork | null;
  selectableCardNetworks: CardNetwork[];
  isLoading: boolean;
} | null;

The entire context can be null before card network detection initializes. Always use optional chaining when accessing properties: event.detail?.detectedCardNetwork?.network.

CardNetwork

interface CardNetwork {
  displayName: string;
  network: string;
}

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

Callback vs Event payload difference: The callback (onVaultedMethodsUpdate) includes cvvRecapture, while the DOM event (primer:vault:methods-update) does not. Use the callback if you need the CVV recapture flag.

// Callback payload (onVaultedMethodsUpdate)
interface VaultedMethodsUpdateData {
  vaultedPayments: InitializedVaultedPayments;
  cvvRecapture: boolean;  // Only available in callback
  timestamp: number;
}

// Event payload (primer:vault:methods-update)
interface VaultedMethodsUpdateEventDetail {
  vaultedPayments: InitializedVaultedPayments;
  timestamp: number;
  // Note: cvvRecapture is NOT available in the event
}

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

PrepareHandler

interface PrepareHandler {
  continuePaymentCreation: () => void;
  abortPaymentCreation: () => void;
}

InitializedPayments

interface InitializedPayments {
  toArray(): InitializedPaymentMethod[];
  size(): number;
  get(type: string): InitializedPaymentMethod | undefined;
}

InitializedVaultedPayments

interface InitializedVaultedPayments {
  toArray(): VaultedPaymentMethodSummary[];
  size(): number;
  get(id: string): VaultedPaymentMethodSummary | undefined;
}

Components

​Quick Navigation

​Callbacks vs DOM Events

​Event Lifecycle

​DOM Events

​Initialization Events

​primer:ready

​primer:methods-update

​State Events

​primer:state-change

​Card Form Events

​primer:card-network-change

​primer:card-success

​primer:card-error

​Payment Events

​primer:payment-start

​primer:payment-success

​primer:payment-failure

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

​onPaymentStart

​onPaymentPrepare

​onPaymentSuccess

​onPaymentFailure

​onVaultedMethodsUpdate

​PrimerJS Instance Methods

​refreshSession()

​getPaymentMethods()

​setCardholderName()

​Vault API

​vault.createCvvInput()

​vault.startPayment()

​vault.delete()

​Deprecated Methods

​Type Definitions

​PaymentSuccessData

​PaymentFailureData

​PaymentSummary

​PaymentFailure

​SdkState

​CardNetworksContextType

​CardNetwork

​CardSubmitSuccessPayload

​CardSubmitErrorsPayload

​InputValidationError

​VaultedMethodsUpdateData

​VaultedPaymentMethodSummary

​VaultSelectionChangeData

​ShowOtherPaymentsToggledPayload

​PrepareHandler

​InitializedPayments

​InitializedVaultedPayments

​See Also

Quick Navigation

Callbacks vs DOM Events

Event Lifecycle

DOM Events

Initialization Events

primer:ready

primer:methods-update

State Events

primer:state-change

Card Form Events

primer:card-network-change

primer:card-success

primer:card-error

Payment Events

primer:payment-start

primer:payment-success

primer:payment-failure

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 Callbacks

onPaymentStart

onPaymentPrepare

onPaymentSuccess

onPaymentFailure

onVaultedMethodsUpdate

PrimerJS Instance Methods

refreshSession()

getPaymentMethods()

setCardholderName()

Vault API

vault.createCvvInput()

vault.startPayment()

vault.delete()

Deprecated Methods

Type Definitions

PaymentSuccessData

PaymentFailureData

PaymentSummary

PaymentFailure

SdkState

CardNetworksContextType

CardNetwork

CardSubmitSuccessPayload

CardSubmitErrorsPayload

InputValidationError

VaultedMethodsUpdateData

VaultedPaymentMethodSummary

VaultSelectionChangeData

ShowOtherPaymentsToggledPayload

PrepareHandler

InitializedPayments

InitializedVaultedPayments

See Also