Events reference

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

await primer.refreshSession();

const methods = primer.getPaymentMethods();

primer.setCardholderName('Jane Doe');

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

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

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

await primer.vault.delete(paymentMethodId);

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

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

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

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

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;
  };
}

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

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

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;
}

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;
}

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

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

interface CardSubmitErrorsPayload {
  errors: InputValidationError[];
}

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

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

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;
}

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

interface ShowOtherPaymentsToggledPayload {
  expanded: boolean;
}

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