> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Primer checkout SDK

This page documents all notable changes to Primer checkout. We follow [Semantic Versioning](https://semver.org/) for our releases.

<Update label="v1.4.3" description="2026-06-02">
  **✨ Improvements**

  * Redirect APMs flow improvements.

  **🔧 Fixes**

  * Fixed an issue where the card form could be submitted multiple times concurrently.
</Update>

<Update label="v1.4.2" description="2026-05-28">
  **🚀 New features**

  * Content in the `main` slot now renders immediately, before the SDK finishes initializing. Combined with the `loader-disabled` attribute, this lets you show custom UI alongside `<primer-main>` before the `primer:ready` event fires.
</Update>

<Update label="v1.4.1" description="2026-05-21">
  **🔧 Fixes**

  * Fixed a issue where aborting a payment in some scenarios wasn't working correctly.
</Update>

<Update label="v1.4.0" description="2026-05-19">
  **🔧 Fixes**

  <Warning>
    Redirect payment methods are no longer available when `returnUrl` is not set. See [redirect options](/sdk/primer-checkout-web/sdk-options-reference#redirect-options) for more info.
  </Warning>

  * Fixed a CSP issue that was blocking the SDK from rendering.
</Update>

<Update label="v1.3.0" description="2026-05-06">
  **🚀 New features**

  * Added Adyen Mbway and Pay NL Paypal payment methods

  **🔧 Fixes**

  * Fixed cardholder name validations
  * Fixed rendering of certain APM buttons
</Update>

<Update label="v1.2.0" description="2026-04-23">
  **🔧 Fixes**

  * Fixed filter vaulted cards by orderedAllowedCardNetworks
  * Fixed google pay disabled not working on safari
  * Fixed a single card network icon on the card number input should not be interactive (accessibility)
  * Fixed propagate options on the hosted inputs
</Update>

<Update label="v1.1.1" description="2026-04-17">
  **🔧 Fixes**

  * Fixed initialization lifecycle not cleaning up previous state properly, causing issues when reinitializing (e.g. when changing the `clientToken`)
</Update>

<Update label="v1.1.0" description="2026-04-16">
  **🚀 New features**

  * Added Klarna and Adyen Klarna payment methods

  **🔧 Fixes**

  * Fixed 3ds method timeout
</Update>

<Update label="v1.0.9" description="2026-03-31">
  **🔧 Fixes**

  * Paying with vaulted methods now triggers `primer:payment-start` correctly
</Update>

<Update label="v1.0.8" description="2026-03-30">
  **🔧 Fixes**

  * When using Google Pay as a payment method, [amount](https://primer.io/docs/api-reference/v2.4/api-reference/client-session-api/create-a-client-session#body-amount)
    sent when creating client session will take presedence over calculated amount from line items

  **✨ Improvements**

  * Internal payment method processing improvements
</Update>

<Update label="v1.0.7" description="2026-03-19">
  **🔧 Fixes**

  * Fixed a billing address component render issue when sdkCore was not explicitly set
  * Fixed a country selector inconsistent behavior
</Update>

<Update label="v1.0.6" description="2026-03-16">
  **🔧 Fixes**

  * Fixed an issue that prevented card fields from rendering on Angular (NgZone)
</Update>

<Update label="v1.0.5" description="2026-03-16">
  **🚀 New features**

  * Added gift card payment methods support on `sdkCore: true` (`PAY_NL_KAARTDIRECT`, `MOLLIE_GIFTCARD`)
  * [`primer:payment-cancel`](/sdk/primer-checkout-web/events-reference#primerpayment-cancel) event now includes payment data when a payment method is already created before it's unselected

  **🔧 Fixes**

  * Fixed the order of the `primer:card-success` event being fired
  * Fixed dark mode styling issues on dialogs
  * Fixed card network displaying an infinite loading spinner
</Update>

<Update label="v1.0.4" description="2026-03-10">
  **🔧 Fixes**

  * Fixed a bug where third-party browser extensions could cause the checkout screen to become blank
</Update>

<Update label="v1.0.3" description="2026-03-09">
  **🔧 Fixes**

  * Fixed a card form autofill bug where the expiry date field didn't handle full-year formats correctly (e.g. on Chrome, autofilling `10/2026` would populate `10/20` instead of `10/26`)
</Update>

<Update label="v1.0.2" description="2026-03-04">
  **🔧 Fixes**

  * Fixed Apple Pay payment sheet closing when trying to pay with third-party desktop browsers

  **✨ Improvements**

  * EFTPOS co-badged cards now leave network selection up to the vendor without user interaction
</Update>

<Update label="v1.0.1" description="2026-02-25">
  **🔧 Fixes**

  * Fixed an issue where checkout failures were triggered when the user cancelled a payment flow
</Update>

<Update label="v1.0.0" description="2026-02-19">
  <Warning>
    **Breaking Changes**: v1.0.0 includes several breaking changes to the events API, callbacks, and data structures. Review the migration guide below before upgrading.
  </Warning>

  **🚀 New features**

  * `primer:payment-start` event is now preventable, providing control over payment creation flow with `abortPaymentCreation()` and `continuePaymentCreation()` methods
  * `primer:payment-start` event now includes `paymentMethodType`, `timestamp`, and optional `idempotencyKey` support via `continuePaymentCreation({ idempotencyKey })`
  * `primer:vault-methods-update` event now includes `cvvRecapture` data
  * Added new `primer:payment-cancel` event, dispatched when a payment is cancelled

  **Breaking Changes:**

  * **Events API changes**
    * `primer:payment-success` — renamed `paymentSummary` property to `payment`
    * `primer:payment-failure` — renamed `paymentSummary` property to `payment`
    * Vault events no longer use the `vault` namespace (e.g. `primer:vault:methods-update` → `primer:vault-methods-update`, `primer:vault:selection-change` → `primer:vault-selection-change`)
    * `primer:payment-start` event payload changed to `{ paymentMethodType, abortPaymentCreation, continuePaymentCreation, timestamp }`

  * **Callbacks deprecated**
    * All callbacks (`onPaymentSuccess`, `onPaymentFailure`, `onPaymentStart`, `onPaymentPrepare`, `onVaultedMethodsUpdate`) are now deprecated. Use events instead.

  * **Simplified API**
    * Removed `.toArray()` on vaulted payments — vaulted payments are now returned as an array directly
    * Removed `.toArray()` on payment methods — payment methods are now returned as an array directly

  **Documentation:**

  * [Events Guide](/checkout/primer-checkout/configuration/events) - Updated event system overview
  * [Events Reference](/sdk/primer-checkout-web/events-reference) - Full payload reference
  * [Prevent duplicate payments with idempotency keys](/checkout/primer-checkout/guides-and-recipes/use-idempotency-keys) - Recipe for using idempotency keys with the preventable `primer:payment-start` event
</Update>

<Update label="v0.15.0" description="2026-02-16">
  **🚀 New features**

  * Added `primer:bin-data-available` event, providing card network detection along with rich BIN data including issuer information, account funding type, and card attributes.
  * Added `primer:bin-data-loading-change` event to indicate when BIN data is being fetched from Primer's servers.

  **Documentation:**

  * [Events Guide](/checkout/primer-checkout/configuration/events) - Usage examples
  * [Events Reference](/sdk/primer-checkout-web/events-reference#primerbin-data-available) - Full payload reference
</Update>

<Update label="v0.14.1" description="2026-02-11">
  **🔧 Fixes**

  * Fixed a failed payment flow issue
</Update>

<Update label="v0.13.3" description="2026-01-29">
  **🔧 Fixes**

  * Improved error handling and fixed circular errors
</Update>

<Update label="v0.13.2" description="2026-01-27">
  **🔧 Fixes**

  * Fixed Google Pay vaulted item rendering
  * Fixed PayPal button rendering issues within vault manager
</Update>

<Update label="v0.13.1" description="2026-01-23">
  **✨ Improvements**

  * Enhanced error logging capabilities
</Update>

<Update label="v0.13.0" description="2026-01-14">
  **🚀 New features**

  Support for redirect-based Alternative Payment Methods (APMs) with a popup-first approach. The SDK opens a popup overlay dialog for redirect payments, with automatic fallback to full-page redirect for WebViews and blocked popups.

  **Key Changes:**

  * **Redirect Payment Methods**
    * Popup-first flow with overlay dialog
    * Automatic fallback to full-page redirect for WebViews and blocked popups
    * New `redirect` configuration options: `returnUrl`, `forceRedirect`, `resumePaymentOnPopupClosure`

  * **New Events**
    * `primer:dialog-open` — dispatched when the redirect payment dialog opens
    * `primer:dialog-close` — dispatched when the redirect payment dialog closes

  <Warning>
    **Breaking Change**: The default value of `enabledPaymentMethods` has changed. Previously, only `PAYMENT_CARD` was enabled by default. Now, all SDK Core-supported payment methods are enabled if the property is omitted. If you relied on the card-only default, explicitly set `enabledPaymentMethods` to include only the payment methods you need.
  </Warning>

  **Documentation:**

  * [SDK Options Reference](/sdk/primer-checkout-web/sdk-options-reference) - Redirect configuration details
  * [Events Reference](/sdk/primer-checkout-web/events-reference) - Dialog event documentation
</Update>

<Update label="v0.12.5" description="2026-01-13">
  **🔧 Fixes**

  * Import regression bug fix that fixes PayPal button rendering on `sdkCore: false`
</Update>

<Update label="v0.12.4" description="2026-01-13">
  **🔧 Fixes**

  * Fixed dispatch of payment-start event
</Update>

<Update label="v0.12.3" description="2026-01-09">
  **✨ Improvements**

  New design tokens added for error states in components:

  ```
  --primer-color-background-outlined-error
  --primer-color-border-outlined-error
  --primer-width-error
  --primer-typography-error-size
  --primer-typography-error-weight
  --primer-typography-error-letter-spacing
  --primer-color-text-negative
  ```

  Check the documentation to learn more.
</Update>

<Update label="v0.12.2" description="2026-01-07">
  **🔧 Fixes**

  * Fixed translations for en-US locale
  * Fixed PayPal horizontal layout style
</Update>

<Update label="v0.12.1" description="2025-12-16">
  **🚀 New features**

  Apple Pay and Google Pay are now available in SDK Core with early-stage support.

  <Warning>
    Apple Pay and Google Pay require SDK Core enabled (default) AND must be added to `enabledPaymentMethods` array.
  </Warning>

  **Key Changes:**

  * Apple Pay payment method support in SDK Core
  * Google Pay payment method support in SDK Core
  * Apple Pay third-party browser payment using iPhone support is added
  * Enhanced PayPal support with better defaults and per-funding source styling configuration

  **Configuration:**

  Apple Pay, Google Pay, and PayPal must be explicitly enabled in the `enabledPaymentMethods` array:

  ```javascript theme={"dark"}
  import { PaymentMethodType } from '@primer-io/primer-js';

  const checkout = document.querySelector('primer-checkout');
  checkout.options = {
    sdkCore: true, // Required for Apple Pay, Google Pay and PayPal (enabled by default)
    enabledPaymentMethods: [
      PaymentMethodType.PAYMENT_CARD,
      PaymentMethodType.APPLE_PAY, // Add Apple Pay
      PaymentMethodType.GOOGLE_PAY, // Add Google Pay
      PaymentMethodType.PAYPAL, // Add PayPal
    ],
  };
  ```

  **Apple Pay and Google Pay changes**

  * **Apple Pay Payment Method**
    * Full Apple Pay integration with SDK Core
    * Button customization (17 button types, 3 button styles)
    * Billing address capture from Apple Wallet (`requiredBillingContactFields`)
    * Shipping contact capture (address, name, email, phone) via `requiredShippingContactFields`
    * Non-Safari browser support

  * **Google Pay Payment Method**
    * Full Google Pay integration with SDK Core
    * Button customization (type, color, size mode, radius, border, locale)
    * Billing address capture from Google account (`captureBillingAddress`)
    * Shipping address capture with country filtering (`captureShippingAddress`)
    * Email capture (`emailRequired`)
    * Locale support for 30+ languages

  **Example Configuration:**

  ```javascript theme={"dark"}
  const checkout = document.querySelector('primer-checkout');
  checkout.options = {
    sdkCore: true,
    // Apple Pay configuration
    applePay: {
      buttonOptions: {
        type: 'buy',
        buttonStyle: 'black',
      },
      billingOptions: {
        requiredBillingContactFields: ['postalAddress'],
      },
      shippingOptions: {
        requiredShippingContactFields: [
          'postalAddress',
          'name',
          'email',
          'phone',
        ],
      },
    },
    // Google Pay configuration
    googlePay: {
      buttonType: 'checkout',
      buttonColor: 'black',
      buttonSizeMode: 'fill',
      captureBillingAddress: true,
      captureShippingAddress: true,
      shippingAddressParameters: {
        allowedCountryCodes: ['US', 'CA', 'GB'],
        phoneNumberRequired: true,
      },
      emailRequired: true,
      requireShippingMethod: true,
    },
  };
  ```

  **PayPal changes**

  * **Enhanced PayPal Support**
    * Per-funding source styling configuration
    * Override styles for specific funding sources (e.g., PayPal, Pay Later, Venmo)
    * Better defaults for button appearance
    * Buyer country configuration support

  **Example PayPal Configuration:**

  ```javascript theme={"dark"}
  const checkout = document.querySelector('primer-checkout');
  checkout.options = {
    sdkCore: true,
    paypal: {
      style: {
        // Base styles
        borderRadius: 22,
        color: 'silver',
        // Override styles for specific funding source
        paylater: {
          color: 'white',
        },
      },
      buyerCountry: 'US',
    },
  };
  ```

  **Documentation:**

  * [Apple Pay Options Reference](/sdk/primer-checkout-web/apple-pay) - Complete configuration options and API reference
  * [Google Pay Options Reference](/sdk/primer-checkout-web/google-pay) - Complete configuration options and API reference
  * [PayPal Options Reference](/sdk/primer-checkout-web/paypal) - Complete configuration options and API reference

  <Note>
    The new payment methods are in early-stage support. Additional features and improvements will be added in future releases.
  </Note>
</Update>

<Update label="v0.11.0" description="2025-11-26">
  <Warning>
    **Breaking Change**: The vault methods `createCvvInput()` and `startVaultPayment()` on the PrimerJS instance are now deprecated. These methods still work but will be **REMOVED in the next release**. Migrate to the new `primerJS.vault.*` namespace.
  </Warning>

  **🚀 New features**

  This release introduces the `primerJS.vault.*` namespace for better API organization and adds programmatic vault deletion capability. Enhanced data exposure now provides parity between headless and non-headless vault flows.

  **Key Changes:**

  * **Vault API Namespace** (Breaking Change)
    * New `primerJS.vault.*` namespace groups all vault operations
    * `vault.createCvvInput()` replaces `primerJS.createCvvInput()`
    * `vault.startPayment()` replaces `primerJS.startVaultPayment()`
    * Old methods deprecated with console warnings in development mode
    * **Old methods will be REMOVED in the next release**

  * **New Vault Deletion Method**
    * Added `primerJS.vault.delete(paymentMethodId)` for programmatic deletion
    * Enables custom vault management UIs without Primer UI components

  * **Enhanced Data Exposure for Headless Vault**
    * **Cards**: Now exposes `cardholderName`, `expirationMonth`, `expirationYear`
    * **PayPal**: Now exposes `email`, `firstName`, `lastName`, `externalPayerId`
    * **Klarna**: Now exposes `email`, `firstName`, `lastName`
    * Provides data parity between headless mode and non-headless vault UI

  **Migration Guide:**

  ```javascript theme={"dark"}
  // Before (deprecated - will be removed)
  const cvvInput = await primerJS.createCvvInput(options);
  await primerJS.startVaultPayment(methodId, { cvv });

  // After (recommended)
  const cvvInput = await primerJS.vault.createCvvInput(options);
  await primerJS.vault.startPayment(methodId, { cvv });
  await primerJS.vault.delete(methodId); // NEW
  ```

  **Documentation:**

  * [Headless Vault Implementation Guide](/sdk/primer-checkout-web/components/primer-vault-manager#headless-vault-implementation) - Complete implementation example
  * [Events & Callbacks Reference](/sdk/primer-checkout-web/events-reference) - VaultAPI documentation
</Update>

<Update label="v0.10.0" description="2025-11-19">
  **✨ Improvements**

  Intelligent change detection for SDK options prevents unnecessary re-initialization when object references change but content remains identical. Solves form flickering and data loss issues in React applications.

  **Key Changes:**

  * **Deep Comparison Implementation**
    * Added deep equality comparison for `options` property changes
    * Prevents SDK re-initialization when new object references contain identical values
    * Eliminates form flickering and data loss during React re-renders

  * **React Integration Improvements**
    * Inline options objects now work correctly without causing re-initialization
    * User-entered payment data preserved across component updates
    * `useMemo` no longer required (though still recommended for optimal performance)

  * **Backward Compatible**
    * No breaking changes or API modifications
    * Existing code continues to work identically

  **Example:**

  ```tsx theme={"dark"}
  // ✅ Now works correctly: Inline objects no longer cause re-initialization
  return (
    <primer-checkout
      client-token={clientToken}
      options={{
        sdkCore: true,
      }}
      ref={checkoutRef}
    >
      <div slot='main'>{children}</div>
    </primer-checkout>
  );
  ```

  **Documentation:**

  * [React Integration Guide](/checkout/primer-checkout/frameworks/react-integration-guide) - Updated with deep comparison behavior and best practices
  * [Options Guide](/checkout/primer-checkout/configuration/sdk-options) - Comprehensive options configuration patterns
</Update>

<Update label="v0.9.0" description="2025-11-18">
  **🚀 New features**

  Complete headless vault implementation allowing full programmatic control over vaulted payment methods. Build custom vault UIs while retaining all vault functionality.

  **Key Changes:**

  * **Headless Vault Mode**
    * Added `vault.headless` configuration option to hide vault UI components while maintaining full vault functionality
    * Enables custom vault UI implementation with complete control over layout and styling
    * All vault features remain operational (payment method selection, CVV recapture, submission)
    * Fully compatible with existing vault configuration options

  * **CVV Recapture Support**
    * Added `cvvRecapture` flag in `onVaultedMethodsUpdate` callback data
    * Indicates when CVV re-entry is required for a vaulted payment method
    * Automatically set based on payment processor requirements

  * **New PrimerJS Methods**
    * Added CVV input creation for custom vault UI
    * Added vault payment initiation for programmatic control
    * Type-safe integration with TypeScript support

  **🔧 Fixes**

  * Changed `vault.showEmptyState` default from `true` to `false`
  * Aligns with common use cases where empty state is custom or hidden
  * Explicit opt-in now required for empty state display

  **Documentation:**

  * [Headless Vault Implementation Guide](/sdk/primer-checkout-web/components/primer-vault-manager#headless-vault-implementation) - Complete implementation example with code
  * [Vault Options Reference](/sdk/primer-checkout-web/sdk-options-reference#vault-options) - Complete vault.headless API reference
  * [Events & Callbacks Reference](/sdk/primer-checkout-web/events-reference) - Method documentation
</Update>

<Update label="v0.8.2" description="2025-11-17">
  **🚀 New features**

  * Added new event `primer:vault:selection-change` dispatched when a payment method is selected or deselected

  **🔧 Fixes**

  * Fixed slotted show other payment methods toggle button in the case when `Pay` button is of type `button`

  **Documentation:**

  * [New events](/sdk/primer-checkout-web/events-reference)
</Update>

<Update label="v0.8.1" description="2025-11-17">
  **✨ Improvements**

  * Added Adyen Cash App and Affirm payment instrument types
</Update>

<Update label="v0.8.0" description="2025-11-13">
  **🚀 New features**

  Added new slots for vault submit button and slot for Show other payment methods toggle button. Refer to the `<primer-vault-manager>` and `<primer-show-other-payments>` SDK reference documentation on how to use them.
</Update>

<Update label="v0.7.4" description="2025-11-11">
  **🔧 Fixes**

  Fixed build failures caused by dynamic imports issue in the billing address component's locale country data.

  **Key Changes:**

  * **Billing Address Component**
    * Fixed dynamic imports for locale country data
    * Resolved build failures and bundle errors
    * Component now builds correctly across all environments

  **Impact:**

  * Merchants experiencing build failures should update immediately
  * No API changes or migration required
</Update>

<Update label="v0.7.3" description="2025-11-11">
  **🚀 New features**

  Pre-fill the cardholder name field with a default value using synchronous initialization. No race conditions, no blank field flash - the value appears immediately when the checkout loads.

  **Key Changes:**

  * **Cardholder Name Pre-filling**
    * Added `card.cardholderName.defaultValue` option for synchronous cardholder name pre-filling
    * Value applied during iframe initialization (before it becomes visible)
    * Eliminates race conditions and blank field flash from async approaches
    * User can edit or clear the pre-filled value
    * Backward compatible - optional parameter

  **Usage Example:**

  ```javascript theme={"dark"}
  const checkout = document.querySelector('primer-checkout');
  checkout.setAttribute('client-token', 'your-client-token');

  checkout.options = {
    card: {
      cardholderName: {
        visible: true,
        required: true,
        defaultValue: 'John Doe', // Pre-fill cardholder name
      },
    },
  };
  ```

  **Technical Details:**

  * Synchronous initialization via iframe URL hash
  * Value visible immediately when iframe loads (T+4ms vs T+16ms for async)
  * No timing issues or readiness checks required
  * Works with SDK Core enabled (default)

  **When to Use:**

  * Pre-filling from user profiles during checkout initialization
  * For runtime updates after initialization, use `primerJS.setCardholderName()` (see v0.7.1)

  **Documentation:**

  * [Card Options Reference](/sdk/primer-checkout-web/sdk-options-reference#card-options) - Complete API reference
  * [Options Guide](/checkout/primer-checkout/configuration/sdk-options) - Configuration patterns and best practices
</Update>

<Update label="v0.7.2" description="2025-11-07">
  **✨ Improvements**

  This release improves the accessibility and visual consistency of the Vault Manager component, along with fixing layout issues in the Show Other Payments component.

  **Key Changes:**

  * **Vault Manager Enhancements**
    * Improved accessibility for better screen reader support and keyboard navigation
    * Fixed icon rendering issues in dark mode for better visual consistency

  * **Show Other Payments Component**
    * Fixed persistent padding issue when the component is collapsed
    * Improved layout behavior for a cleaner collapsed state
</Update>

<Update label="v0.7.1" description="2025-11-06">
  **🚀 New features**

  Added `setCardholderName()` method to PrimerJS instance for programmatically setting cardholder name values.

  **Key Changes:**

  * **New PrimerJS Method**
    * Added `setCardholderName(name: string)` - Programmatically set the cardholder name field value
    * Useful for pre-filling from user profiles or auto-completing checkout forms
    * Must be called after `primer:ready` event and after card inputs are rendered
    * Graceful error handling with warnings if called before initialization

  **Usage Example:**

  ```javascript theme={"dark"}
  checkout.addEventListener('primer:ready', (event) => {
    const primerJS = event.detail;
    // Pre-fill cardholder name from user profile
    primerJS.setCardholderName('John Doe');
  });
  ```

  **Documentation:**

  * [Events & Callbacks Reference](/sdk/primer-checkout-web/events-reference) - Full API reference
  * [Events Guide](/checkout/primer-checkout/configuration/events) - Practical usage examples
</Update>

<Update label="v0.7.0" description="2025-11-04">
  <Warning>
    **Breaking Change**: This release significantly refactors the callback and state architecture for improved type safety and developer experience. Key breaking changes:

    1. **Callback API Changes**: `onPaymentComplete` removed in favor of separate `onPaymentSuccess` and `onPaymentFailure` callbacks
    2. **State Field Renames**: `error` → `primerJsError`, `failure` → `paymentFailure` with updated structure
    3. **Type Safety**: All callbacks now provide strongly-typed, specific data structures
  </Warning>

  **🚀 New features**

  Added comprehensive payment event system with PII-protected payment summaries and vault update notifications.

  **Key Changes:**

  * **Callback Architecture Refactor (BREAKING)**
    * Removed `onPaymentComplete` unified callback
    * Added `onPaymentSuccess(data: PaymentSuccessData)` - Handles successful payments with payment summary
    * Added `onPaymentFailure(data: PaymentFailureData)` - Handles payment failures with error details
    * Added `onVaultedMethodsUpdate()` - Notifies when vaulted payment methods change
    * Existing callbacks unchanged: `onPaymentStart`, `onPaymentPrepare`

  * **State Field Renames (BREAKING)**
    * `error` → `primerJsError` (SDK initialization/component errors)
    * `failure` → `paymentFailure` (payment processing failures)
    * `failure.details` → `paymentFailure.diagnosticsId`
    * Added `paymentFailure.data` for additional error metadata

  * **New Payment Events**
    * `primer:payment-start` - Dispatched when payment creation begins
    * `primer:payment-success` - Dispatched on successful payment (includes PII-filtered PaymentSummary)
    * `primer:payment-failure` - Dispatched on payment failure (includes error details)
    * `primer:vault:methods-update` - Dispatched when vaulted payment methods update

  * **PII Protection**
    * PaymentSummary type with whitelisted fields only (last4Digits, network, bankName)
    * No cardholder names, full card numbers, or other PII exposed in events
    * Compliant with GDPR Article 5(1)(c) and PCI DSS Requirement 3.4

  * **Performance Improvements**
    * 40-60% reduction in redundant state-change events through deduplication
    * Internal optimization with no API changes

  **Migration Guide:**

  Before (v0.6.x):

  ```javascript theme={"dark"}
  primerJS.onPaymentComplete = (data) => {
    if (data.status === 'success') {
      console.log('Payment ID:', data.payment?.id);
    } else if (data.status === 'error') {
      console.log('Error:', data.error?.message);
    }
  };

  // State access
  if (state.error) {
    // Handle SDK error
  }
  if (state.failure) {
    // Handle payment error
    console.log('Details:', state.failure.details);
  }
  ```

  After (v0.7.0):

  ```javascript theme={"dark"}
  primerJS.onPaymentSuccess = ({ payment, paymentMethodType }) => {
    console.log('Payment ID:', payment.id);
    console.log('Last 4 digits:', payment.paymentMethodData?.last4Digits);
    console.log('Network:', payment.paymentMethodData?.network);
  };

  primerJS.onPaymentFailure = ({ error, payment, paymentMethodType }) => {
    console.log('Error:', error.message);
    console.log('Diagnostics ID:', error.diagnosticsId);
    console.log('Additional data:', error.data);
  };

  primerJS.onVaultedMethodsUpdate = () => {
    console.log('Vaulted methods updated');
    // Refresh vault display if needed
  };

  // State access
  if (state.primerJsError) {
    // Handle SDK error
  }
  if (state.paymentFailure) {
    // Handle payment error
    console.log('Diagnostics ID:', state.paymentFailure.diagnosticsId);
  }
  ```

  **Documentation:**

  * [Events Guide](/checkout/primer-checkout/configuration/events) - Complete event system overview
  * [Events & Callbacks Reference](/sdk/primer-checkout-web/events-reference) - Full API reference
</Update>

<Update label="v0.6.0" description="2025-10-30">
  **🚀 New features**

  PayPal is now available in SDK Core with early-stage support. PayPal provides button-based payment flows with comprehensive customization options for styling, funding source control, and vaulting.

  <Warning>
    PayPal requires SDK Core enabled (default) AND must be added to `enabledPaymentMethods` array.
  </Warning>

  **Key Changes:**

  * PayPal payment method support in SDK Core
  * Button style customization (layout, color, shape, height, label)
  * Funding source control (enable/disable specific PayPal payment options)
  * Vaulting support for saved PayPal accounts
  * Sandbox testing options for development

  **Configuration:**

  PayPal must be explicitly enabled in the `enabledPaymentMethods` array:

  ```javascript theme={"dark"}
  import { PaymentMethodType } from '@primer-io/primer-js';

  const checkout = document.querySelector('primer-checkout');
  checkout.options = {
    sdkCore: true, // Required for PayPal (enabled by default)
    enabledPaymentMethods: [
      PaymentMethodType.PAYMENT_CARD,
      PaymentMethodType.PAYPAL, // Add PayPal
    ],
    paypal: {
      style: {
        color: 'gold',
        shape: 'rect',
      },
    },
  };
  ```

  **Documentation:**

  * [PayPal Options Reference](/sdk/primer-checkout-web/paypal) - Complete PayPal configuration options

  <Note>
    PayPal is in early-stage support. Additional features and improvements will be added in future releases.
  </Note>
</Update>

<Update label="v0.5.2" description="2025-10-29">
  **🔧 Fixes**

  Fixed critical bug where billing address was being set even when not required by checkout configuration, causing payment submission failures and validation errors.

  **Key Changes:**

  * Fixed billing address validation logic to respect checkout configuration requirements
  * Billing address no longer submitted when not required by merchant settings
  * Eliminated unnecessary validation errors during payment submission
  * Improved payment flow reliability

  <Warning>
    **Recommendation:** Update to this version immediately to avoid payment submission issues.
  </Warning>
</Update>

<Update label="v0.5.1" description="2025-10-24">
  **🔧 Fixes**

  Fixed billing address rendering issue when `sdkCore` option was omitted. The billing address component now correctly displays when relying on the default SDK Core setting introduced in v0.4.0.

  **Key Changes:**

  * Fixed SDK Core default detection for billing address component
  * Billing address now renders correctly when `sdkCore` option is not explicitly set
  * No impact on other SDK functionality
</Update>

<Update label="v0.5.0" description="2025-10-21">
  **🚀 New features**

  BLIK support is now available for the Polish market. BLIK is Poland's leading mobile payment system that allows customers to authorize payments using a 6-digit code from their banking app.

  <Warning>
    BLIK requires SDK Core (enabled by default) AND must be added to `enabledPaymentMethods` array.
  </Warning>

  **Key Changes:**

  * BLIK payment method for Polish market (6-digit code from banking app)
  * Auto-submit with real-time status polling and timeout warnings
  * Collapsible UI: button → form → loading → success/error states
  * Full localization (40+ languages) and dark mode support
  * TypeScript improvements: Enhanced JSDoc documentation for all `PrimerCheckoutOptions` properties
  * Dependency updates across all packages

  **Example Configuration:**

  ```javascript theme={"dark"}
  import { PaymentMethodType } from '@primer-io/primer-js';

  const checkout = document.querySelector('primer-checkout');
  checkout.setAttribute('client-token', 'your-client-token');

  checkout.options = {
    enabledPaymentMethods: [
      PaymentMethodType.PAYMENT_CARD,
      PaymentMethodType.ADYEN_BLIK, // Add BLIK
    ],
  };
  ```
</Update>

<Update label="v0.4.0" description="2025-10-17">
  <Warning>
    **Breaking Change**: SDK Core is now the default payment engine. Previously, omitting the `sdkCore` option used the legacy SDK. Starting in v0.4.0, SDK Core is enabled by default when `sdkCore` is not specified.

    **Migration:** To continue using the legacy SDK, explicitly set `sdkCore: false` in your configuration.
  </Warning>

  **🚀 New features**

  Billing address capture is now supported through Primer Dashboard checkout configuration.

  **Key Changes:**

  * SDK Core enabled by default when `sdkCore` option not specified
  * Billing address form support (SDK Core only)
  * Automatic billing address display in drop-in mode
  * Manual integration required for custom layouts
  * Removed "experimental" terminology from SDK Core references
  * Expanded test coverage for SDK selection scenarios

  **Billing Address:**

  * Enable via Primer Dashboard checkout configuration
  * Automatic display in drop-in mode
  * Manual inclusion needed for slotted card forms (custom layouts)
  * Requires SDK Core enabled (not available with `sdkCore: false`)
  * Billing Address Documentation (coming soon)

  **Example - SDK Core Opt-out:**

  ```javascript theme={"dark"}
  // v0.3.x - Legacy SDK by default
  const checkout = document.querySelector('primer-checkout');
  checkout.setAttribute('client-token', 'your-client-token');
  // sdkCore not specified - used Legacy SDK by default

  // v0.4.0 - SDK Core by default
  const checkout = document.querySelector('primer-checkout');
  checkout.setAttribute('client-token', 'your-client-token');
  checkout.options = {
    sdkCore: false, // Explicit opt-out for Legacy SDK
  };
  ```
</Update>

<Update label="v0.3.12" description="2025-10-13">
  **🔧 Fixes**

  * Fixed Google Pay rendering issue in certain browser configurations

  **SDK Core Updates:**

  * Vault CVV recapture
  * Billing address API improvements

  <Note>
    Most changes in this release relate to SDK core development.
  </Note>
</Update>

<Update label="v0.3.11" description="2025-10-08">
  **✨ Improvements**

  This release contains internal SDK improvements with no user-facing component changes.

  **Internal Changes:**

  * Iframe lifecycle fixes
  * Payment methods filter list
  * Datadog logging integration
</Update>

<Update label="v0.3.10" description="2025-10-06">
  **🔧 Fixes**

  * PayPal button height fix
  * Native payment method CSS improvements
</Update>

<Update label="v0.3.9" description="2025-09-30">
  **✨ Improvements**

  This release contains internal SDK improvements with no user-facing component changes.

  **Internal Changes:**

  * Card form slot handling improvements
</Update>

<Update label="v0.3.8" description="2025-09-29">
  **✨ Improvements**

  This release contains internal SDK improvements with no user-facing component changes.

  **Internal Changes:**

  * Analytics URL from client token
  * Vault management features
  * Logger implementation
  * Iframe RPC refactor
</Update>

<Update label="v0.3.7" description="2025-09-18">
  **✨ Improvements**

  This release contains internal SDK improvements with no user-facing component changes.

  **Internal Changes:**

  * Error standardization
  * HTTP retry logic
  * Locale support improvements
</Update>

<Update label="v0.3.6" description="2025-09-04">
  **🚀 New features**

  * Added cardholder name toggle option for card form customization

  **Changes:**

  * Cardholder name display toggle
  * Fixed toggle implementation in primer-sdk-web
</Update>

<Update label="v0.3.5" description="2025-08-20">
  **✨ Improvements**

  * Removed unnecessary peer dependencies and extended React version compatibility
</Update>

<Update label="v0.3.4" description="2025-07-24">
  **🔧 Fixes**

  * Removed native `:focus-within` CSS selector and implemented alternative focus handling for Firefox compatibility
</Update>

<Update label="v0.3.3" description="2025-07-08">
  **🔧 Fixes**

  Fixed vault manager initialization preventing unnecessary API calls when vault is disabled. Components now handle missing customer ID gracefully.

  **Changes:**

  * Lazy vault initialization (only when `vault.enabled` is true)
  * Eliminated unnecessary API calls when vault disabled
  * Graceful handling of missing customer ID
</Update>

<Update label="v0.3.2" description="2025-07-07">
  **🚀 New features**

  Payment Method Container enables declarative payment layouts using `include` and `exclude` attributes, eliminating verbose event listener code.

  **Key Features:**

  * Declarative filtering with HTML attributes
  * Automatic updates when payment methods change
  * Backward compatible with existing implementations

  **Example:**

  ```html theme={"dark"}
  <primer-payment-method-container
    include="APPLE_PAY,GOOGLE_PAY"
  ></primer-payment-method-container>
  ```

  **Documentation:**

  * [SDK Reference](/sdk/primer-checkout-web/components/primer-payment-method-container)
</Update>

<Update label="v0.3.1" description="2025-06-20">
  **✨ Improvements**

  * Extended Payment type definitions to include `DLOCAL_PIX`, `ALMA`, and `PAY_NL_RIVERTY`
</Update>

<Update label="v0.3.0" description="2025-06-12">
  **🚀 New features**

  Complete vault component redesign with new control system for disabling payment methods globally or individually.

  **Vault Component:**

  * Visual overhaul with improved responsive layout
  * Custom empty state slot: `<div slot="vault-empty-state">`
  * Control empty state visibility: `vault.showEmptyState: false`
  * Enhanced accessibility

  **Payment Controls:**

  * Individual method disabling: `<primer-card-form disabled></primer-card-form>`
  * Global disabling: `disabledPayments: true` in SDK options
  * Consistent disabled styling across all methods

  <Warning>
    **Breaking Change**: Stricter TypeScript typing may reveal previously ignored errors
  </Warning>

  **Example:**

  ```html theme={"dark"}
  <primer-vault-manager>
    <div slot="vault-empty-state">
      <p>No saved payment methods</p>
    </div>
  </primer-vault-manager>
  ```
</Update>

<Update label="v0.2.0" description="2025-05-19">
  <Warning>
    **Breaking Change**: All DOM events renamed to `primer:*` namespace format. Legacy `primer-oncheckout-complete` and `primer-oncheckout-failure` events removed.

    **Event Renames:**

    * `primer-state-changed` → `primer:state-change`
    * `primer-payment-methods-updated` → `primer:methods-update`
    * `primer-checkout-initialized` → `primer:ready`
    * `primer-card-submit-success` → `primer:card-success`
    * `primer-card-submit-errors` → `primer:card-error`
    * `primer-card-network-change` → `primer:card-network-change`
  </Warning>

  **🚀 New features**

  Introduced type-safe `PrimerJS` class replacing direct SDK access:

  * `refreshSession()` - Refresh client session
  * `getPaymentMethods()` - Retrieve available methods
  * `onPaymentStart` - Payment initiation callback
  * `onPaymentPrepare` - Intercept payment creation
  * `onPaymentComplete` - Unified payment result callback
</Update>

<Update label="v0.1.8" description="2025-05-02">
  **✨ Improvements**

  * Improved icon display and alignment for card network selection
</Update>

<Update label="v0.1.7" description="2025-05-02">
  **🔧 Fixes**

  * Fixed icon display next to card number input
</Update>

<Update label="v0.1.6" description="2025-05-01">
  **🚀 New features**

  * Added `hide-labels` property to card form
  * Introduced `primer-oncheckout-complete` and `primer-oncheckout-failure` events
</Update>

<Update label="v0.1.5" description="2025-04-30">
  **✨ Improvements**

  * Enhanced vault component functionality
  * Improved transitions
  * Fixed custom style application
</Update>

<Update label="v0.1.4" description="2025-04-15">
  **🚀 New features**

  * Introduced experimental Stripe ACH UI and configuration support
</Update>

<Update label="v0.1.3" description="2025-04-15">
  **✨ Improvements**

  * Moved style injection logic into components for better reinitialization and stability
</Update>

<Update label="v0.1.2" description="2025-04-10">
  **✨ Improvements**

  * Optimized NPM builds with improved bundling
  * Faster loading
  * Reduced CDN dependency
</Update>

<Update label="v0.1.1" description="2025-04-10">
  **🔧 Fixes**

  * Fixed Safari styling issues by switching from Inter font to system fonts
</Update>

<Update label="v0.1.0" description="2025-04-10">
  **🚀 New features**

  Introduced standalone vaulting component, Klarna integration, and significant UX improvements.

  **Key Features:**

  * Klarna payment method with collapsible design
  * Standalone vault component supporting all backend payment methods
  * Enhanced error validation (triggers on blur instead of submit)
  * Improved styling system with JavaScript-injected CSS tokens
  * CSS-only loader with merchant customization support
</Update>

<Update label="v0.0.3" description="2025-03-11">
  **🔧 Fixes**

  * Fixed TypeScript type bundling
  * Apple Pay/Google Pay button height adjustments
</Update>

<Update label="v0.0.2" description="2025-03-07">
  **🚀 New features**

  First public beta introducing card form, Apple Pay, Google Pay, PayPal (beta), localization support, and comprehensive styling API.

  **Core Components:**

  * `<primer-checkout>` - Main container and SDK initialization
  * `<primer-card-form>` - Card input with validation
  * `<primer-payment-method>` - Payment method renderer
  * Card input components: number, expiry, CVV, cardholder name
  * Form helpers: button, input, label, error, wrapper
</Update>

<Update label="v0.0.1" description="2025-03-01">
  **✨ Improvements**

  * Initial NPM package setup and name reservation
</Update>