Changelog

This page documents all notable changes to Primer Checkout. We follow Semantic Versioning for our releases.

v0.13.0 - Redirect Payment Methods (14-Jan-2026)​

Key Changes:

• Redirect Payment Flow: Popup-first approach with overlay dialog, automatic fallback to full redirect for WebViews and blocked popups
• New redirect Options: returnUrl, forceRedirect, resumePaymentOnPopupClosure
• New Events: primer:dialog-open, primer:dialog-close
• enabledPaymentMethods Default Change: Now defaults to all supported payment methods instead of just PAYMENT_CARD. If not specified, all SDK Core-supported payment methods will be enabled.

Documentation:

• SDK Options Reference - Redirect Options - Complete configuration options and behavior details
• Events & Callbacks Reference - Dialog events documentation

v.0.12.5 - (13-Jan-2026)​

v.0.12.4 (13-Jan-2026)​

v.0.12.3 (9-Jan-2026)​

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.

v.0.12.2 (7-Jan-2026) - Regression fixes to Paypal horizontal layout style and translations for en-US locale​

v0.12.1 - Apple Pay, Google Pay and improved PayPal SDK Core support (16-Dec-2025)​

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:

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:

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:

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 - Complete configuration options and API reference
• Google Pay Options Reference - Complete configuration options and API reference
• PayPal Options Reference - Complete configuration options and API reference
• Payment Methods Guide - Integration patterns and best practices

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

v0.11.0 - Vault API Namespace & Enhanced Data (26-Nov-2025)​

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:

// 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 - Complete implementation example
• Events & Callbacks Reference - VaultAPI documentation

v0.10.0 - Deep Comparison Options Architecture (19-Nov-2025)​

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:

// ✅ 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 - Updated with deep comparison behavior and best practices
• Options Guide - Comprehensive options configuration patterns

v0.9.0 - Headless Vault Flow Support (18-Nov-2025)​

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

• Bug Fix

  • 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 - Complete implementation example with code
• Vault Options Reference - Complete vault.headless API reference
• Events & Callbacks Reference - Method documentation

v0.8.2 - Fixes and enhancements to slotted show other payment methods toggle button and slotted vault submit button (17-Nov-2025)​

Documentation:

• New events

v0.8.1 - Add Adyen Cash App and Affirm payment instrument types. (17-Nov-2025)​

v0.8.0 - Available slots for vault submit button and show other payment methods button (13-Nov-2025)​

v0.7.4 - Billing Address Build Fix (11-Nov-2025)​

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

v0.7.3 - Cardholder Name Default Value (11-Nov-2025)​

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:

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 - Complete API reference
• Options Guide - Configuration patterns and best practices

v0.7.2 - Vault Manager Improvements (07-Nov-2025)​

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

v0.7.1 - Programmatic Cardholder Name (06-Nov-2025)​

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:

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

Documentation:

• Events & Callbacks Reference - Full API reference
• Events Guide - Practical usage examples

v0.7.0 - Payment Events & Callback Architecture Refactor (04-Nov-2025)​

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):

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):

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 - Complete event system overview
• Events & Callbacks Reference - Full API reference

v0.6.0 - PayPal Support (30-Oct-2025)​

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:

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 - Complete PayPal configuration options
• Payment Methods Guide - Supported payment methods and SDK modes

Note: PayPal is in early-stage support. Additional features and improvements will be added in future releases.

v0.5.2 - Billing Address Requirement Fix (29-Oct-2025)​

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

Recommendation: Update to this version immediately to avoid payment submission issues.

v0.5.1 - SDK Core Default Fix (24-Oct-2025)​

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

v0.5.0 - BLIK Payment Method (21-Oct-2025)​

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:

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

v0.4.0 - SDK Core Default & Billing Address (17-Oct-2025)​

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:

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

v0.3.12 - Google Pay Fix (13-Oct-2025)​

SDK Core Updates:

• Vault CVV recapture
• Billing address API improvements

Note: Most changes in this release relate to SDK core development.

v0.3.11 - SDK Core Updates (08-Oct-2025)​

Internal Changes:

• Iframe lifecycle fixes
• Payment methods filter list
• Datadog logging integration

v0.3.10 - CSS Improvements (06-Oct-2025)​

v0.3.9 - SDK Core Updates (30-Sep-2025)​

Internal Changes:

• Card form slot handling improvements

v0.3.8 - SDK Core Updates (29-Sep-2025)​

Internal Changes:

• Analytics URL from client token
• Vault management features
• Logger implementation
• Iframe RPC refactor

v0.3.7 - SDK Core Updates (18-Sep-2025)​

Internal Changes:

• Error standardization
• HTTP retry logic
• Locale support improvements

v0.3.6 - Cardholder Name Toggle (04-Sep-2025)​

Changes:

• Cardholder name display toggle
• Fixed toggle implementation in primer-sdk-web

v0.3.5 - Dependency Cleanup (20-Aug-2025)​

v0.3.4 - Firefox Compatibility (24-Jul-2025)​

v0.3.3 - Vault Initialization Fix (08-Jul-2025)​

Changes:

• Lazy vault initialization (only when vault.enabled is true)
• Eliminated unnecessary API calls when vault disabled
• Graceful handling of missing customer ID

v0.3.2 - Payment Method Container (07-Jul-2025)​

Key Features:

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

Example:

<primer-payment-method-container
  include="APPLE_PAY,GOOGLE_PAY"
></primer-payment-method-container>

Documentation:

• SDK Reference

v0.3.1 - Payment Type Updates (20-Jun-2025)​

v0.3.0 - Vault Redesign & Payment Controls (12-Jun-2025)​

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

Example:

<primer-vault-manager>
  <div slot="vault-empty-state">
    <p>No saved payment methods</p>
  </div>
</primer-vault-manager>

v0.2.0 - Event System Overhaul (19-May-2025)​

v0.1.8 - Card Network Icon Fix (02-May-2025)​

Improved icon display and alignment for card network selection.

v0.1.7 - Card Form Icon Fix (02-May-2025)​

Fixed icon display next to card number input.

v0.1.6 - Component Improvements (01-May-2025)​

Added hide-labels property to card form. Introduced primer-oncheckout-complete and primer-oncheckout-failure events.

v0.1.5 - Vault and Styling Improvements (30-Apr-2025)​

Enhanced vault component functionality, improved transitions, and fixed custom style application.

v0.1.4 - Experimental Stripe ACH (15-Apr-2025)​

Introduced experimental Stripe ACH UI and configuration support.

v0.1.3 - Style Injection Improvements (15-Apr-2025)​

Moved style injection logic into components for better reinitialization and stability.

v0.1.2 - Build Optimizations (10-Apr-2025)​

Optimized NPM builds with improved bundling, faster loading, and reduced CDN dependency.

v0.1.1 - Safari Compatibility (10-Apr-2025)​

Fixed Safari styling issues by switching from Inter font to system fonts.

v0.1.0 - Vaulting & UX Improvements (10-Apr-2025)​

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

v0.0.3 - TypeScript & Button Fixes (11-Mar-2025)​

Fixed TypeScript type bundling and Apple Pay/Google Pay button height adjustments.

v0.0.2 - Initial Beta Release (07-Mar-2025)​

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

v0.0.1 - Package Setup (01-Mar-2025)​

Initial NPM package setup and name reservation.