@primer-io/primer-js 0.6.0 → 0.7.1

package/dist/primer-loader.d.ts

@@ -10,15 +10,29 @@ export type CardNetworksContextType = {
 	selectableCardNetworks: CardNetwork[];
 	isLoading: boolean;
 } | null;
+/**
+ * SDK state representation
+ */
 export type SdkState = {
 	isSuccessful: boolean;
 	isProcessing: boolean;
-	error: Error | null;
+	/**
+	 * SDK/component initialization errors.
+	 * This represents errors from the Primer JS layer itself (e.g., configuration errors,
+	 * component initialization failures), not payment processing errors.
+	 */
+	primerJsError: Error | null;
 	isLoading: boolean;
-	failure: {
+	/**
+	 * Payment processing failure information.
+	 * Contains structured error details from failed payment attempts.
+	 * Includes error code, message, diagnostics ID, and additional metadata.
+	 */
+	paymentFailure: {
 		code: string;
 		message: string;
-		details?: Record<string, unknown>;
+		diagnosticsId?: string | null;
+		data?: Record<string, unknown>;
 	} | null;
 };
 export type SdkStateContextType = SdkState | null;
@@ -176,6 +190,214 @@ declare const PaymentMethodType: {
 	readonly ALMA: "ALMA";
 };
 export type PaymentMethodType = (typeof PaymentMethodType)[keyof typeof PaymentMethodType];
+declare const PaymentMethodType$1 = {
+	WORLDPAY_IDEAL: "WORLDPAY_IDEAL",
+	STRIPE_ACH: "STRIPE_ACH",
+	STRIPE_IDEAL: "STRIPE_IDEAL",
+	ADYEN_KLARNA: "ADYEN_KLARNA",
+	ADYEN_BANCONTACT_CARD: "ADYEN_BANCONTACT_CARD",
+	PAY_NL_KAARTDIRECT: "PAY_NL_KAARTDIRECT",
+	ADYEN_EPS: "ADYEN_EPS",
+	ADYEN_BANCONTACT_PAYCONIQ: "ADYEN_BANCONTACT_PAYCONIQ",
+	OMISE_PROMPTPAY: "OMISE_PROMPTPAY",
+	OMISE_TRUEMONEY: "OMISE_TRUEMONEY",
+	ADYEN_MULTIBANCO: "ADYEN_MULTIBANCO",
+	PACYPAY_WECHAT: "PACYPAY_WECHAT",
+	PACYPAY_ALIPAY: "PACYPAY_ALIPAY",
+	ADYEN_MBWAY: "ADYEN_MBWAY",
+	XENDIT_DANA: "XENDIT_DANA",
+	XENDIT_SHOPEEPAY: "XENDIT_SHOPEEPAY",
+	ADYEN_PAYSHOP: "ADYEN_PAYSHOP",
+	ADYEN_PAYTRAIL: "ADYEN_PAYTRAIL",
+	CLEARPAY: "CLEARPAY",
+	RAPYD_FAST: "RAPYD_FAST",
+	RAPYD_PROMPTPAY: "RAPYD_PROMPTPAY",
+	RAPYD_GCASH: "RAPYD_GCASH",
+	RAPYD_POLI: "RAPYD_POLI",
+	RAPYD_GRABPAY: "RAPYD_GRABPAY",
+	PRIMER_PAYPAL: "PRIMER_PAYPAL",
+	TWOC2P: "TWOC2P",
+	NETS: "NETS",
+	STRIPE_GIROPAY: "STRIPE_GIROPAY",
+	MOLLIE_GIROPAY: "MOLLIE_GIROPAY",
+	MOLLIE_EPS: "MOLLIE_EPS",
+	PAY_NL_EPS: "PAY_NL_EPS",
+	PAY_NL_P24: "PAY_NL_P24",
+	MOLLIE_P24: "MOLLIE_P24",
+	MOLLIE_SOFORT: "MOLLIE_SOFORT",
+	COINBASE: "COINBASE",
+	OPENNODE: "OPENNODE",
+	MOLLIE_GIFT_CARD: "MOLLIE_GIFTCARD",
+	XFERS_PAYNOW: "XFERS_PAYNOW",
+	PAYMENT_CARD: "PAYMENT_CARD",
+	APPLE_PAY: "APPLE_PAY",
+	GOOGLE_PAY: "GOOGLE_PAY",
+	PAYPAL: "PAYPAL",
+	GO_CARDLESS: "GOCARDLESS",
+	KLARNA: "KLARNA",
+	PAY_NL_IDEAL: "PAY_NL_IDEAL",
+	PAY_NL_SOFORT_BANKING: "PAY_NL_SOFORT_BANKING",
+	PAY_NL_BANCONTACT: "PAY_NL_BANCONTACT",
+	PAY_NL_PAYPAL: "PAY_NL_PAYPAL",
+	PAY_NL_CREDIT_TRANSFER: "PAY_NL_CREDIT_TRANSFER",
+	PAY_NL_DIRECT_DEBIT: "PAY_NL_DIRECT_DEBIT",
+	PAY_NL_GIROPAY: "PAY_NL_GIROPAY",
+	PAY_NL_PAYCONIQ: "PAY_NL_PAYCONIQ",
+	PAY_NL_RIVERTY: "PAY_NL_RIVERTY",
+	HOOLAH: "HOOLAH",
+	ADYEN_BLIK: "ADYEN_BLIK",
+	ADYEN_MOBILEPAY: "ADYEN_MOBILEPAY",
+	ADYEN_VIPPS: "ADYEN_VIPPS",
+	ADYEN_GIROPAY: "ADYEN_GIROPAY",
+	ADYEN_SOFORT: "ADYEN_SOFORT",
+	ADYEN_IDEAL: "ADYEN_IDEAL",
+	ADYEN_TRUSTLY: "ADYEN_TRUSTLY",
+	ADYEN_ALIPAY: "ADYEN_ALIPAY",
+	ADYEN_TWINT: "ADYEN_TWINT",
+	ADYEN_BANK_TRANSFER: "ADYEN_BANK_TRANSFER",
+	MOLLIE_BANCONTACT: "MOLLIE_BANCONTACT",
+	MOLLIE_IDEAL: "MOLLIE_IDEAL",
+	BUCKAROO_GIROPAY: "BUCKAROO_GIROPAY",
+	BUCKAROO_EPS: "BUCKAROO_EPS",
+	BUCKAROO_SOFORT: "BUCKAROO_SOFORT",
+	BUCKAROO_BANCONTACT: "BUCKAROO_BANCONTACT",
+	BUCKAROO_IDEAL: "BUCKAROO_IDEAL",
+	ATOME: "ATOME",
+	DLOCAL_PIX: "DLOCAL_PIX",
+	ALMA: "ALMA",
+} as const;
+type PaymentMethodType$1 = (typeof PaymentMethodType$1)[keyof typeof PaymentMethodType$1];
+declare const PaymentInstrumentType$1 = {
+	WORLDPAY_IDEAL: "WORLDPAY_IDEAL",
+	AUTOMATED_CLEARING_HOUSE: "AUTOMATED_CLEARING_HOUSE",
+	ADYEN_KLARNA: "ADYEN_KLARNA",
+	ADYEN_BANCONTACT_CARD: "ADYEN_BANCONTACT_CARD",
+	PAY_NL_KAARTDIRECT: "PAY_NL_KAARTDIRECT",
+	ADYEN_EPS: "ADYEN_EPS",
+	ADYEN_BANCONTACT_PAYCONIQ: "ADYEN_BANCONTACT_PAYCONIQ",
+	OMISE_PROMPTPAY: "OMISE_PROMPTPAY",
+	OMISE_TRUEMONEY: "OMISE_TRUEMONEY",
+	ADYEN_MULTIBANCO: "ADYEN_MULTIBANCO",
+	PACYPAY_WECHAT: "PACYPAY_WECHAT",
+	PACYPAY_ALIPAY: "PACYPAY_ALIPAY",
+	ADYEN_MBWAY: "ADYEN_MBWAY",
+	XENDIT_DANA: "XENDIT_DANA",
+	XENDIT_SHOPEEPAY: "XENDIT_SHOPEEPAY",
+	ADYEN_PAYSHOP: "ADYEN_PAYSHOP",
+	ADYEN_PAYTRAIL: "ADYEN_PAYTRAIL",
+	CLEARPAY: "CLEARPAY",
+	RAPYD_FAST: "RAPYD_FAST",
+	RAPYD_PROMPTPAY: "RAPYD_PROMPTPAY",
+	RAPYD_GCASH: "RAPYD_GCASH",
+	RAPYD_POLI: "RAPYD_POLI",
+	RAPYD_GRABPAY: "RAPYD_GRABPAY",
+	PRIMER_PAYPAL: "PRIMER_PAYPAL",
+	TWOC2P: "TWOC2P",
+	NETS: "NETS",
+	STRIPE_ACH: "STRIPE_ACH",
+	STRIPE_GIROPAY: "STRIPE_GIROPAY",
+	MOLLIE_GIROPAY: "MOLLIE_GIROPAY",
+	MOLLIE_EPS: "MOLLIE_EPS",
+	PAY_NL_EPS: "PAY_NL_EPS",
+	PAY_NL_P24: "PAY_NL_P24",
+	MOLLIE_P24: "MOLLIE_P24",
+	MOLLIE_SOFORT: "MOLLIE_SOFORT",
+	COINBASE: "COINBASE",
+	OPENNODE: "OPENNODE",
+	MOLLIE_GIFT_CARD: "MOLLIE_GIFTCARD",
+	XFERS_PAYNOW: "XFERS_PAYNOW",
+	CARD: "PAYMENT_CARD",
+	APPLE_PAY: "APPLE_PAY",
+	GOOGLE_PAY: "GOOGLE_PAY",
+	PAYPAL: "PAYPAL_ORDER",
+	PAYPAL_VAULTED: "PAYPAL_BILLING_AGREEMENT",
+	GO_CARDLESS: "GOCARDLESS",
+	PAY_NL_IDEAL: "PAY_NL_IDEAL",
+	PAY_NL_SOFORT_BANKING: "PAY_NL_SOFORT_BANKING",
+	PAY_NL_BANCONTACT: "PAY_NL_BANCONTACT",
+	PAY_NL_PAYPAL: "PAY_NL_PAYPAL",
+	PAY_NL_CREDIT_TRANSFER: "PAY_NL_CREDIT_TRANSFER",
+	PAY_NL_DIRECT_DEBIT: "PAY_NL_DIRECT_DEBIT",
+	PAY_NL_GIROPAY: "PAY_NL_GIROPAY",
+	PAY_NL_PAYCONIQ: "PAY_NL_PAYCONIQ",
+	PAY_NL_RIVERTY: "PAY_NL_RIVERTY",
+	HOOLAH: "HOOLAH",
+	ADYEN_BLIK: "ADYEN_BLIK",
+	ADYEN_VIPPS: "ADYEN_VIPPS",
+	ADYEN_GIROPAY: "ADYEN_GIROPAY",
+	ADYEN_SOFORT: "ADYEN_SOFORT",
+	ADYEN_IDEAL: "ADYEN_IDEAL",
+	ADYEN_TRUSTLY: "ADYEN_TRUSTLY",
+	ADYEN_ALIPAY: "ADYEN_ALIPAY",
+	ADYEN_TWINT: "ADYEN_TWINT",
+	ADYEN_MOBILEPAY: "ADYEN_MOBILEPAY",
+	MOLLIE_BANCONTACT: "MOLLIE_BANCONTACT",
+	MOLLIE_IDEAL: "MOLLIE_IDEAL",
+	BUCKAROO_GIROPAY: "BUCKAROO_GIROPAY",
+	BUCKAROO_EPS: "BUCKAROO_EPS",
+	BUCKAROO_SOFORT: "BUCKAROO_SOFORT",
+	BUCKAROO_BANCONTACT: "BUCKAROO_BANCONTACT",
+	BUCKAROO_IDEAL: "BUCKAROO_IDEAL",
+	ATOME: "ATOME",
+	KLARNA_CUSTOMER_TOKEN: "KLARNA_CUSTOMER_TOKEN",
+	DLOCAL_PIX: "DLOCAL_PIX",
+	ALMA: "ALMA",
+} as const;
+type PaymentInstrumentType$1 = (typeof PaymentInstrumentType$1)[keyof typeof PaymentInstrumentType$1];
+/**
+ * Minimal payment summary with reduced PII exposure.
+ * Used in events for public data delivery.
+ */
+export interface PaymentSummary {
+	/** Payment ID from Primer API */
+	id: string;
+	/** Order ID/reference from merchant */
+	orderId: string;
+	/** Payment method data with whitelisted fields */
+	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;
+	};
+}
+/**
+ * Minimal vaulted payment method summary with reduced PII exposure.
+ * Used for vault events and callbacks to expose vaulted payment methods safely.
+ */
+export interface VaultedPaymentMethodSummary {
+	/** Payment instrument ID */
+	id: string;
+	/** Analytics tracking ID */
+	analyticsId: string;
+	/** Payment method type (e.g., "PAYMENT_CARD", "PAYPAL") */
+	paymentMethodType: PaymentMethodType$1;
+	/** Payment instrument type (e.g., "CARD", "PAYPAL_BILLING_AGREEMENT") */
+	paymentInstrumentType: PaymentInstrumentType$1;
+	/** Payment instrument data with whitelisted safe fields only */
+	paymentInstrumentData?: {
+		/** 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;
+		/** Account type (ACH only) */
+		accountType?: string;
+		/** Email for wallet payment methods */
+		email?: string;
+	};
+	/** Optional user-provided description for the payment method */
+	userDescription?: string;
+}
 export type APIVersionOption = "legacy" | "2.4";
 declare enum HeadlessManagerType {
 	CARD = "CARD",
@@ -1339,7 +1561,7 @@ export interface PrimerCheckoutOptions {
 	 * ]
 	 * ```
 	 */
-	enabledPaymentMethods?: typeof PaymentMethodType.PAYMENT_CARD | (typeof PaymentMethodType.ADYEN_BLIK)[];
+	enabledPaymentMethods?: typeof PaymentMethodType.PAYMENT_CARD | typeof PaymentMethodType.PAYPAL | (typeof PaymentMethodType.ADYEN_BLIK)[];
 }
 export type InitializedManager = {
 	type: typeof PaymentMethodType.STRIPE_ACH;
@@ -1437,17 +1659,116 @@ export declare class InitializedPayments {
 	toArray(): InitializedPaymentMethod[];
 	size(): number;
 }
+/**
+ * Map of vaulted payment method ID to vaulted payment method summary
+ */
+export type VaultedPaymentMethodsMap = Map<string, VaultedPaymentMethodSummary>;
+/**
+ * Wrapper class for vaulted payment methods that provides type-safe access
+ * to filtered vaulted payment method data.
+ *
+ * This class mirrors the structure of InitializedPayments but for vault data,
+ * providing a consistent API for merchants to access vaulted payment methods
+ * through events and callbacks.
+ *
+ * @example
+ * ```typescript
+ * // Access via callback
+ * primerJS.onVaultedMethodsUpdate = (data) => {
+ *   console.log('Vault size:', data.size());
+ *
+ *   // Get specific method by ID
+ *   const method = data.get('pm_abc123');
+ *   if (method) {
+ *     console.log('Last 4:', method.paymentInstrumentData?.last4Digits);
+ *   }
+ *
+ *   // Get all methods
+ *   const allMethods = data.toArray();
+ *   allMethods.forEach(method => {
+ *     console.log(method.paymentMethodType);
+ *   });
+ * };
+ * ```
+ */
+export declare class InitializedVaultedPayments {
+	private readonly _methods;
+	/**
+	 * @param map - Map of vaulted payment method IDs to summaries
+	 */
+	constructor(map: VaultedPaymentMethodsMap);
+	/**
+	 * Get a vaulted payment method by its ID
+	 *
+	 * @param id - Payment method ID
+	 * @returns Vaulted payment method summary if found, undefined otherwise
+	 */
+	get(id: string): VaultedPaymentMethodSummary | undefined;
+	/**
+	 * Get all vaulted payment methods as an array
+	 *
+	 * @returns Array of all vaulted payment method summaries
+	 */
+	toArray(): VaultedPaymentMethodSummary[];
+	/**
+	 * Get the count of vaulted payment methods
+	 *
+	 * @returns Number of vaulted payment methods
+	 */
+	size(): number;
+}
+/**
+ * Payment prepare callback data.
+ * Includes payment method type for validation or abort control flow.
+ */
 export interface PaymentData {
-	paymentMethodType: string;
+	/** Payment method type (e.g., "PAYMENT_CARD", "PAYPAL") */
+	paymentMethodType: PaymentMethodType;
 }
 export interface PrepareHandler {
 	continuePaymentCreation: () => void;
 	abortPaymentCreation: () => void;
 }
-export interface PaymentCompleteData {
-	payment: Payment | null;
-	status: "success" | "pending" | "error";
-	error?: PrimerClientError;
+/**
+ * Payment success callback data.
+ * Includes minimal payment summary with reduced PII exposure.
+ */
+export interface PaymentSuccessData {
+	/** Minimal payment summary (ID, orderId, last4, brand) - reduced PII exposure */
+	payment: PaymentSummary;
+	/** Payment method type (e.g., "PAYMENT_CARD", "PAYPAL") */
+	paymentMethodType: string;
+	/** Unix timestamp in seconds */
+	timestamp: number;
+}
+/**
+ * Payment failure callback data.
+ * Includes error details and optional payment summary if created before failure.
+ */
+export interface PaymentFailureData {
+	/** Error details */
+	error: {
+		code: string;
+		message: string;
+		diagnosticsId?: string;
+		data?: Record<string, unknown>;
+	};
+	/** Optional minimal payment summary if payment was created before failure */
+	payment?: PaymentSummary;
+	/** Payment method type (e.g., "PAYMENT_CARD", "PAYPAL") */
+	paymentMethodType: string;
+	/** Unix timestamp in seconds */
+	timestamp: number;
+}
+/**
+ * Vault methods update callback data.
+ * Includes filtered vaulted payment methods with minimal PII exposure.
+ */
+export interface VaultedMethodsUpdateData {
+	/** Wrapper containing filtered vaulted payment methods */
+	vaultedPayments: InitializedVaultedPayments;
+	/** Unix timestamp in seconds */
+	timestamp: number;
 }
 /**
  * PrimerJS is a wrapper class that provides a stable API for interfacing with the Primer SDK
@@ -1456,15 +1777,136 @@ export interface PaymentCompleteData {
 export declare class PrimerJS {
 	private headlessInstance;
 	private paymentMethods;
+	private paymentManagers;
+	/**
+	 * Called when payment flow begins.
+	 * Use for analytics tracking or UI updates (e.g., disable form).
+	 *
+	 * @example
+	 * ```typescript
+	 * primerJS.onPaymentStart = () => {
+	 *   analytics.track('payment_started');
+	 *   disablePaymentForm();
+	 * };
+	 * ```
+	 */
 	onPaymentStart?: () => void;
+	/**
+	 * Called before payment creation for validation or abort control flow.
+	 * Use for last-chance validation or conditional payment creation.
+	 *
+	 * @param data - Payment method information
+	 * @param handler - Control flow handler (continue or abort)
+	 *
+	 * @example
+	 * ```typescript
+	 * primerJS.onPaymentPrepare = (data, handler) => {
+	 *   if (!validateBusinessRules(data.paymentMethodType)) {
+	 *     handler.abortPaymentCreation();
+	 *     return;
+	 *   }
+	 *   handler.continuePaymentCreation();
+	 * };
+	 * ```
+	 */
 	onPaymentPrepare?: (data: PaymentData, handler: PrepareHandler) => void;
-	onPaymentComplete?: (data: PaymentCompleteData) => void;
+	/**
+	 * Called when payment completes successfully.
+	 * Receives minimal payment summary with reduced PII exposure.
+	 *
+	 * Use for:
+	 * - Order confirmation and backend sync
+	 * - Receipt generation
+	 * - Payment processing with minimal PII exposure
+	 *
+	 * @param data - Payment success data with PaymentSummary (ID, orderId, last4, brand)
+	 *
+	 * @example
+	 * ```typescript
+	 * primerJS.onPaymentSuccess = async ({ payment, paymentMethodType }) => {
+	 *   // Update backend
+	 *   await fetch(`/api/orders/${payment.orderId}/complete`, {
+	 *     method: 'POST',
+	 *     body: JSON.stringify({ paymentId: payment.id }),
+	 *   });
+	 *
+	 *   // Redirect to success page
+	 *   window.location.href = `/order-success?id=${payment.orderId}`;
+	 * };
+	 * ```
+	 */
+	onPaymentSuccess?: (data: PaymentSuccessData) => void;
+	/**
+	 * Called when payment fails or is declined.
+	 * Receives error details and optional payment summary if created before failure.
+	 *
+	 * Use for:
+	 * - Error handling and user messaging
+	 * - Support ticket creation with diagnosticsId
+	 * - Retry logic for specific error types
+	 *
+	 * @param data - Payment failure data with error details and optional PaymentSummary
+	 *
+	 * @example
+	 * ```typescript
+	 * primerJS.onPaymentFailure = ({ error, payment }) => {
+	 *   console.error('Payment failed:', error.code, error.message);
+	 *
+	 *   // Log to error tracking
+	 *   Sentry.captureException(new Error(error.message), {
+	 *     extra: {
+	 *       diagnosticsId: error.diagnosticsId,
+	 *       paymentId: payment?.id,
+	 *     },
+	 *   });
+	 *
+	 *   // Show user-friendly message
+	 *   showErrorMessage(error.message);
+	 * };
+	 * ```
+	 */
+	onPaymentFailure?: (data: PaymentFailureData) => void;
+	/**
+	 * Called when vaulted payment methods are loaded or updated.
+	 * Receives filtered vaulted payment method data with minimal PII exposure.
+	 *
+	 * Use for:
+	 * - Building custom vault UI
+	 * - Analytics tracking for vault usage
+	 * - Syncing vault state with backend
+	 *
+	 * @param data - Vault methods update data with filtered payment methods
+	 *
+	 * @example
+	 * ```typescript
+	 * primerJS.onVaultedMethodsUpdate = ({ vaultedPayments }) => {
+	 *   console.log(`Vault contains ${vaultedPayments.size()} methods`);
+	 *
+	 *   // Display in custom UI
+	 *   const methods = vaultedPayments.toArray();
+	 *   methods.forEach(method => {
+	 *     displayVaultedMethod({
+	 *       id: method.id,
+	 *       type: method.paymentMethodType,
+	 *       last4: method.paymentInstrumentData?.last4Digits,
+	 *       network: method.paymentInstrumentData?.network,
+	 *     });
+	 *   });
+	 * };
+	 * ```
+	 */
+	onVaultedMethodsUpdate?: (data: VaultedMethodsUpdateData) => void;
 	constructor(headlessInstance: PrimerHeadlessCheckout);
 	/**
 	 * Set the initialized payment methods
 	 * @internal - This is only used internally by the SDK
 	 */
 	setPaymentMethods(methods: InitializedPayments): void;
+	/**
+	 * Set the initialized payment managers
+	 * @internal - This is only used internally by the SDK
+	 */
+	setPaymentManagers(managers: InitializedManagersMap): void;
 	/**
 	 * Refetches a new client session from merchant backend.
 	 */
@@ -1482,20 +1924,35 @@ export declare class PrimerJS {
 	 * Internal method to handle the onBeforePaymentCreate callback and transform it to onPaymentPrepare
 	 * @internal - This is only used internally by the SDK
 	 */
-	handleBeforePaymentCreate(data: PaymentData, originalHandler: {
+	handleBeforePaymentCreate(data: {
+		paymentMethodType: PaymentMethodType;
+	}, originalHandler: {
 		continuePaymentCreation: () => void;
 		abortPaymentCreation: () => void;
 	}): void;
 	/**
-	 * Internal method to handle payment completion (success)
+	 * Internal method to handle the onVaultedMethodsUpdate callback
 	 * @internal - This is only used internally by the SDK
 	 */
-	handlePaymentComplete(payment: Payment | null): void;
+	handleVaultedMethodsUpdate(vaultedPayments: InitializedVaultedPayments): void;
 	/**
-	 * Internal method to handle payment failure
-	 * @internal - This is only used internally by the SDK
+	 * Sets the cardholder name value in the card payment form.
+	 *
+	 * ⚠️ Must be called after card hosted inputs have been rendered.
+	 * Calling too early will log a warning and fail gracefully.
+	 *
+	 * @param cardholderName - The cardholder name to set
+	 *
+	 * @example
+	 * ```typescript
+	 * const checkout = document.querySelector('primer-checkout');
+	 * checkout.addEventListener('primer:ready', (event) => {
+	 *   const primerJS = event.detail;
+	 *   primerJS.setCardholderName('John Doe');
+	 * });
+	 * ```
 	 */
-	handlePaymentFailure(error: PrimerClientError, payment?: Payment): void;
+	setCardholderName(cardholderName: string): void;
 }
 export interface CardSubmitResult {
 	success?: boolean;
@@ -1528,6 +1985,27 @@ export interface PrimerEvents {
 	"primer-ach-bank-details-collected": CustomEvent;
 	"primer-ach-mandate-confirmed": CustomEvent;
 	"primer-ach-mandate-declined": CustomEvent;
+	"primer:payment-start": CustomEvent<undefined>;
+	"primer:payment-success": CustomEvent<{
+		paymentSummary: PaymentSummary;
+		paymentMethodType: string;
+		timestamp: number;
+	}>;
+	"primer:payment-failure": CustomEvent<{
+		error: {
+			code: string;
+			message: string;
+			diagnosticsId?: string;
+			data?: Record<string, unknown>;
+		};
+		paymentSummary?: PaymentSummary;
+		paymentMethodType: string;
+		timestamp: number;
+	}>;
+	"primer:vault:methods-update": CustomEvent<{
+		vaultedPayments: InitializedVaultedPayments;
+		timestamp: number;
+	}>;
 }
 declare class PrimerEventsController implements ReactiveController {
 	host: ReactiveControllerHost & LitElement;
@@ -1556,6 +2034,33 @@ declare class PrimerEventsController implements ReactiveController {
 	 * @param eventDetails - The event details to forward, including source information
 	 */
 	handleExternalCardSubmit(eventDetails: CardSubmitPayload): void;
+	/**
+	 * Dispatch payment start event.
+	 * Called when payment flow begins.
+	 */
+	dispatchPaymentStart(): void;
+	/**
+	 * Dispatch payment success event with minimal payment summary.
+	 * Called when payment completes successfully.
+	 */
+	dispatchPaymentSuccess(payment: Payment, paymentMethodType: string): void;
+	/**
+	 * Dispatch payment failure event.
+	 * Called when payment fails or is declined.
+	 */
+	dispatchPaymentFailure(error: {
+		code: string;
+		message: string;
+		diagnosticsId?: string;
+		data?: Record<string, unknown>;
+	}, paymentMethodType: string, payment?: Payment): void;
+	/**
+	 * Dispatch vault methods update event.
+	 * Called when vaulted payment methods are loaded or updated.
+	 *
+	 * @param vaultedPayments - Wrapper containing filtered vaulted payment methods
+	 */
+	dispatchVaultMethodsUpdate(vaultedPayments: InitializedVaultedPayments): void;
 }
 export type AnalyticsContextType = AnalyticsUtils | null;
 export type EventsContextType = PrimerEventsController | null;
@@ -1655,6 +2160,25 @@ declare class VaultManagerController extends CompositeStateController<PrimerChec
 	 * Lifecycle method called when the host disconnects
 	 */
 	hostDisconnected(): void;
+	/**
+	 * Transform raw vault data into filtered, event-ready format.
+	 * Applies PII filtering to all vaulted payment methods.
+	 *
+	 * @param vaultedPaymentMethods - Raw vaulted payment methods from API
+	 * @returns InitializedVaultedPayments wrapper with filtered data
+	 */
+	private createVaultedPaymentsWrapper;
+	/**
+	 * Update vaulted payment methods and dispatch events/callbacks.
+	 * This method:
+	 * 1. Updates internal state via core controller
+	 * 2. Creates filtered wrapper for external APIs
+	 * 3. Dispatches event to listeners
+	 * 4. Invokes callback if defined
+	 *
+	 * @param methods - Raw vaulted payment methods from API
+	 */
+	private updatePaymentMethodsWithEvents;
 	/**
 	 * Fetch vaulted payment methods from the server
 	 */
@@ -1739,40 +2263,48 @@ declare class SDKContextController implements ReactiveController {
 	setEventsController(value: EventsContextType): void;
 }
 export type SdkStateAction = {
-	type: "START_PROCESSING";
-} | {
-	type: "START_LOADING";
+	type: "SET_LOADING";
+	payload: boolean;
 } | {
-	type: "COMPLETE_PROCESSING";
+	type: "SET_PROCESSING";
+	payload: boolean;
 } | {
-	type: "STOP_PROCESSING";
+	type: "SET_SUCCESS";
+	payload: boolean;
 } | {
-	type: "SET_ERROR";
-	payload: Error;
+	type: "SET_PRIMER_JS_ERROR";
+	payload: Error | null;
 } | {
-	type: "SET_FAILURE";
+	type: "SET_PAYMENT_FAILURE";
 	payload: {
 		code: string;
 		message: string;
-		details?: Record<string, unknown>;
-	};
+		diagnosticsId?: string | null;
+		data?: Record<string, unknown>;
+	} | null;
 } | {
-	type: "COMPLETE_LOADING";
+	type: "COMPLETE_PROCESSING";
 } | {
 	type: "RESET";
-} | {
-	type: "RESET_ERROR";
 };
 declare class SdkStateController extends ReactiveStateController<PrimerCheckoutType, SdkState, SdkStateAction, null> {
 	constructor(host: PrimerCheckoutType);
+	setLoading(loading: boolean): void;
+	setProcessing(processing: boolean): void;
+	setSuccess(success: boolean): void;
+	setPrimerJsError(error: Error | null): void;
+	setPaymentFailure(failure: {
+		code: string;
+		message: string;
+		diagnosticsId?: string | null;
+		data?: Record<string, unknown>;
+	} | null): void;
+	completeProcessing(): void;
+	reset(): void;
 	startLoading(): void;
+	completeLoading(): void;
 	startProcessing(): void;
 	stopProcessing(): void;
-	completeProcessing(): void;
-	completeLoading(): void;
-	setError(error: Error): void;
-	setFailure(code: string, message: string, details?: Record<string, unknown>): void;
-	reset(): void;
 	resetError(): void;
 	forceCompleteLoading(): void;
 }
@@ -1790,6 +2322,7 @@ export interface PrimerCheckoutType extends ReactiveControllerHost, LitElement {
 	primerEventsController: PrimerEventsController;
 	vaultManagerController: VaultManagerController;
 	cardNetworkController: CardNetworkController;
+	primerJS?: PrimerJS;
 }
 declare class CardNetworkController implements ReactiveController {
 	private host;
@@ -1917,6 +2450,50 @@ declare const targetLocales = [
 	`zh-TW`,
 ] as const;
 export type LocaleCode = typeof sourceLocale | (typeof targetLocales)[number];
+declare class HeadlessSdkController implements ReactiveController {
+	host: PrimerCheckoutType;
+	private sdkInstanceTask;
+	private createPaymentMethodManager;
+	private _paymentsList;
+	private currentSdkInstance;
+	private primerJS;
+	private loadingTimeout;
+	private isDisconnected;
+	constructor(host: PrimerCheckoutType);
+	set paymentsList(value: PaymentMethodInfo[]);
+	get paymentsList(): PaymentMethodInfo[];
+	get primerJSInstance(): PrimerJS | null;
+	hostConnected(): void;
+	hostDisconnected(): void;
+	/**
+	 * Normalizes options for legacy SDK compatibility.
+	 * When cardholder name is visible in Primer.js, it should be required in the legacy SDK
+	 * regardless of user's required setting, to ensure proper validation behavior.
+	 */
+	private normalizeOptionsForLegacySdk;
+	private setupLoadingTimeout;
+	private clearLoadingTimeout;
+	private cleanupResources;
+	private _loadV2Sdk;
+	initializeHeadless(): ([clientToken, options]: readonly [
+		string | null,
+		PrimerCheckoutOptions | null
+	]) => Promise<PrimerHeadlessCheckout | typeof initialState>;
+	initializeLitContext(): ([sdkInstance, paymentsList]: readonly [
+		PrimerHeadlessCheckout | null | undefined,
+		PaymentMethodInfo[]
+	]) => Promise<InitializedPaymentMethodMap | typeof initialState | null>;
+	initializePaymentMethodManager(paymentMethod: PaymentMethodInfo): () => Promise<{
+		type: PaymentMethodType;
+		manager: IKlarnaPaymentMethodManager;
+	} | {
+		type: PaymentMethodType;
+		manager: ICardPaymentMethodManager;
+	} | {
+		type: PaymentMethodType;
+		manager: IRedirectPaymentMethodManager;
+	} | null>;
+}
 declare global {
 	interface HTMLElementTagNameMap {
 		"primer-checkout": PrimerCheckoutComponent;
@@ -1948,6 +2525,7 @@ declare class AchPaymentEventsController implements ReactiveController {
 export declare class PrimerCheckoutComponent extends LitElement implements PrimerCheckoutType {
 	set jsInitialized(value: boolean);
 	get jsInitialized(): boolean;
+	get primerJS(): PrimerJS | undefined;
 	static styles: CSSResult[];
 	customStyles: string;
 	clientToken: string;
@@ -1973,6 +2551,7 @@ export declare class PrimerCheckoutComponent extends LitElement implements Prime
 	vaultManagerController: VaultManagerController;
 	cardNetworkController: CardNetworkController;
 	achPaymentEventsController: AchPaymentEventsController;
+	headlessSdkController: HeadlessSdkController;
 	constructor();
 	connectedCallback(): void;
 	attributeChangedCallback(attrName: string, oldVal: string, newVal: string): void;