Primer checkout SDK

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

2026-09-29

✨ Improvements

When a payment fails with IDEMPOTENCY_KEY_ALREADY_EXISTS, the primer:payment-failure event now carries the payment that already exists under the key — its id (from the error response) and orderId — instead of payment: undefined. If you supply your own idempotency key from onBeforePaymentCreate, you can now reconcile a rejected duplicate attempt against the payment the first attempt created. See the primer:payment-failure reference.

2026-09-29

🔧 Fixes

Fixed the Apple Pay payment sheet showing “0 months” for a trial period. The SDK now sends recurringStartDate, recurringIntervalUnit and recurringIntervalCount from recurringPaymentRequest.trialBilling to Apple Pay, so a 3-day trial reads “3 days”. See the Apple Pay API reference.
Fixed an Apple Pay billing amount of 0 falling back to the order amount on the payment sheet. The fallback now applies only when amount is omitted, across the regular, trial, deferred and automatic reload billing options.

2026-09-25

✨ Improvements

The default “Show other payment methods” toggle now reads “Hide other payment methods” while the section is expanded, instead of keeping the same label in both states.

2026-09-24

✨ Improvements

Klarna payments now send an idempotency key by default: the session’s Klarna authorization token, unless you supply your own key from onBeforePaymentCreate. One authorization can only produce one payment. A retried or double-clicked attempt now resolves to the payment an earlier request already created and reports its real outcome, instead of failing the checkout or creating a duplicate. Payment creation under this key retries up to three times on 5xx and network failures.
If you supply your own idempotency key, a conflict on the first attempt still surfaces as IDEMPOTENCY_KEY_ALREADY_EXISTS.
After a failed payment, Klarna refreshes its session and widget so the shopper’s next attempt authorizes freshly.

2026-09-16

🚀 New features

Colour the text a shopper types, separately from the sheet. --primer-color-text-outlined-default sets input text on its own, so a dark field on a light sheet (or the reverse) no longer means overriding the sheet’s text colour. It reaches the hosted card number, expiry and CVV fields too. See Text colors.
Added --primer-space-xxlarge, and pointed the stylesheet at the same semantic colour names the iOS, Android and React Native SDKs use, so a theme reads the same across all four. No visual change on its own.

✨ Improvements

BLIK, MB WAY and the accordion’s confirm button now behave consistently with the other checkout buttons in their disabled, loading and focus states.
Every border and focus ring is drawn from the width tokens instead of a hardcoded pixel value. A width override that carries a unit is now rejected with a warning, and an invalid value falls back to the default instead of erasing the border.

🔧 Fixes

Fixed <primer-show-other-payments> landing in the wrong expanded state when used with a custom (slotted) toggle button and rendered before saved payment methods finished loading. The expanded state now follows the saved payment methods as they load, instead of being fixed when the component first renders.
Fixed brand button labels and spinners taking the sheet colour in dark mode, which left them near-black on a dark background. They now stay light.
Fixed hover and active resolving to the resting colour on the secondary button and the Adyen Klarna option cards, so neither appeared to respond to the pointer. The primary button’s label also no longer dims twice while loading, and aria-checked is no longer set on buttons that cannot be checked.
Fixed the select chevron using a baked-in near-black instead of following the icon colour, and the option list now draws dark when the dark theme is on.
Fixed styles that never took effect: the BLIK expiry warning and error text, the QR code heading size, the payment method button font, the error message slide-in, and the vault overlay, which was pinned to white instead of following the sheet.

2026-09-09

🔧 Fixes

Fixed a manually-selected card network (e.g. choosing “Cartes Bancaires” over “Visa” on a co-badged card) persisting after the card number was cleared or changed to a different card.
Fixed <primer-card-form> field validation errors not appearing the first time a shopper left an invalid field, requiring them to focus and leave an unrelated field first before the error would render.

✨ Improvements

Localisation improvements.

2026-09-03

✨ Improvements

Vault manager payment-method rows now use a native radio input for selection, improving keyboard and screen-reader support, with refreshed selected/CVV row styling.

🔧 Fixes

Fixed the vault manager’s CVV error message misaligning the label and input in <primer-vault-manager> when shown.
Fixed vaulted card network names with underscores (e.g. “CARTES_BANCAIRES”) displaying unformatted in <primer-vault-manager> instead of as a proper name (e.g. “Cartes Bancaires”).

2026-09-01

🔧 Fixes

Vault manager payment-method rows no longer pick up the --primer-radius-button token.
The selected vaulted payment method now clears once the shopper starts filling out the card form, instead of remaining selected indefinitely in custom layouts that render both side by side.
Fixed several CVV recapture bugs in <primer-vault-manager>:
- The validation error now only appears after a Pay attempt, instead of flashing when switching between stored cards.
- Clicking near the CVV field no longer collapses the selected card.
- The error message no longer shifts the layout of the cards below it.

2026-08-28

🚀 New features

Independent button corner radius. Added --primer-radius-button so you can round (or square off) checkout buttons — payment method buttons, the card form submit button, and the Klarna confirm button — without affecting components that share the same radius tokens, like dialogs, card inputs, and the accordion’s expanded container. See Button styling tokens.
Restrict vaulted payment method types. <primer-vault-manager> now accepts a vault.enabledPaymentMethods option to show only specific vaulted payment method types. See Vault manager configuration.

🔧 Fixes

Vaulted payment methods of unsupported types are no longer shown in <primer-vault-manager>.
Fixed the vault manager’s CVV recapture prompt and card expiry label not respecting the configured locale, and other localisation improvements.

2026-08-24

🚀 New features

Customizable initialization errors. When the SDK fails to initialize (e.g. an invalid or expired client token), <primer-main> now renders a checkout-error slot instead of a fixed error screen. Provide your own content for that slot, and listen for primer:state-change to read the primerJsError details (code, message, suggestion) for logging or branching. See Error handling and the <primer-main> reference.

2026-08-12

✨ Improvements

Improved how the SDK handles poor internet conditions, making the checkout more reliable.

🔧 Fixes

Fixed an issue where a failure to load saved payment methods would prevent the entire checkout from rendering.

2026-07-15

🔧 Fixes

Fixed an issue where multiple card payment flows could be started concurrently.

✨ Improvements

Internal improvements.

2026-07-13

🔧 Fixes

Fixed amount formatting for some currencies.

2026-07-08

✨ Improvements

Added localized translations for the ‘SEPA instant credit transfer’ payment method button.

2026-07-03

Support for the headless SDK (sdkCore: false) has been removed and all checkouts now run on the new engine, which has been the default since v0.4.0. If you were still setting sdkCore: false, please remove it as the option no longer switches to the headless SDK.

🚀 New features

Manual payment approval (Backend-Driven CIT). Require explicit backend approval of each payment before it’s created. See the Manual payment approval guide, or the migration guide if you’re moving from the legacy manual flow.
Added support for Bancontact Payconiq, Xfers PayNow, Omise PromptPay, and Rapyd PromptPay payment methods.

2026-06-24

🔧 Fixes

Improved browser detection so that redirect payment methods correctly fall back to a full-page redirect instead of opening a popup in environments where popups are unreliable, such as in-app browsers.

✨ Improvements

Internal security, performance, and stability improvements.

2026-06-17

🚀 New features

Payment methods are now re-evaluated when you call primer.refreshSession(). Methods hidden by your Checkout Builder visibility rules are removed from the rendered list instead of staying visible, and a new onAvailablePaymentMethodsRefresh callback notifies you whenever the available payment methods change.

refreshSession() is ignored (with a console warning) while a payment is in progress, so payment methods can’t change underneath the customer mid-payment.

🔧 Fixes

Fixed false primer:payment-failure events being emitted for payments that were still processing and went on to succeed. When a resume response indicates the payment is still being authorized, the SDK now waits for it to settle before reporting an outcome — preventing customers from being asked to retry a payment that had already gone through.
Payment failure events now include the created payment’s id and a diagnosticsId, making failures easier to reconcile against your Dashboard and the Payments API.

2026-06-02

✨ Improvements

Redirect APMs flow improvements.

🔧 Fixes

Fixed an issue where the card form could be submitted multiple times concurrently.

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.

2026-05-21

🔧 Fixes

Fixed a issue where aborting a payment in some scenarios wasn’t working correctly.

2026-05-19

🔧 Fixes

Redirect payment methods are no longer available when returnUrl is not set. See redirect options for more info.

Fixed a CSP issue that was blocking the SDK from rendering.

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

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

2026-04-17

🔧 Fixes

Fixed initialization lifecycle not cleaning up previous state properly, causing issues when reinitializing (e.g. when changing the clientToken)

2026-04-16

🚀 New features

Added Klarna and Adyen Klarna payment methods

🔧 Fixes

Fixed 3ds method timeout

2026-03-31

🔧 Fixes

Paying with vaulted methods now triggers primer:payment-start correctly

2026-03-30

🔧 Fixes

When using Google Pay as a payment method, amount sent when creating client session will take presedence over calculated amount from line items

✨ Improvements

Internal payment method processing improvements

2026-03-19

🔧 Fixes

Fixed a billing address component render issue when sdkCore was not explicitly set
Fixed a country selector inconsistent behavior

2026-03-16

🔧 Fixes

Fixed an issue that prevented card fields from rendering on Angular (NgZone)

2026-03-16

🚀 New features

Added gift card payment methods support on sdkCore: true (PAY_NL_KAARTDIRECT, MOLLIE_GIFTCARD)
primer:payment-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

2026-03-10

🔧 Fixes

Fixed a bug where third-party browser extensions could cause the checkout screen to become blank

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)

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

2026-02-25

🔧 Fixes

Fixed an issue where checkout failures were triggered when the user cancelled a payment flow

2026-02-19

Breaking Changes: v1.0.0 includes several breaking changes to the events API, callbacks, and data structures. Review the migration guide below before upgrading.

🚀 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 - Updated event system overview
Events Reference - Full payload reference
Prevent duplicate payments with idempotency keys - Recipe for using idempotency keys with the preventable primer:payment-start event

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 - Usage examples
Events Reference - Full payload reference

2026-02-11

🔧 Fixes

Fixed a failed payment flow issue

2026-01-29

🔧 Fixes

Improved error handling and fixed circular errors

2026-01-27

🔧 Fixes

Fixed Google Pay vaulted item rendering
Fixed PayPal button rendering issues within vault manager

2026-01-23

✨ Improvements

Enhanced error logging capabilities

2026-01-14

🚀 New featuresSupport 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

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.

Documentation:

SDK Options Reference - Redirect configuration details
Events Reference - Dialog event documentation

2026-01-13

🔧 Fixes

Import regression bug fix that fixes PayPal button rendering on sdkCore: false

2026-01-13

🔧 Fixes

Fixed dispatch of payment-start event

2026-01-09

✨ ImprovementsNew 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.

2026-01-07

🔧 Fixes

Fixed translations for en-US locale
Fixed PayPal horizontal layout style

2025-12-16

🚀 New featuresApple Pay and Google Pay are now available in SDK Core with early-stage support.

Apple Pay and Google Pay require SDK Core enabled (default) AND must be added to enabledPaymentMethods array.

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

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

2025-11-26

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.

🚀 New featuresThis 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:

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

2025-11-19

✨ ImprovementsIntelligent 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:

// ✅ 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

2025-11-18

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

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

2025-11-17

✨ Improvements

Added Adyen Cash App and Affirm payment instrument types

2025-11-13

🚀 New featuresAdded 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.

2025-11-11

🔧 FixesFixed 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

2025-11-11

🚀 New featuresPre-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:

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

2025-11-07

✨ ImprovementsThis 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

2025-11-06

🚀 New featuresAdded 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:

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

2025-11-04

Breaking Change: This release significantly refactors the callback and state architecture for improved type safety and developer experience. Key breaking changes:

Callback API Changes: onPaymentComplete removed in favor of separate onPaymentSuccess and onPaymentFailure callbacks
State Field Renames: error → primerJsError, failure → paymentFailure with updated structure
Type Safety: All callbacks now provide strongly-typed, specific data structures

🚀 New featuresAdded 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):

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

2025-10-30

🚀 New featuresPayPal 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.

PayPal requires SDK Core enabled (default) AND must be added to enabledPaymentMethods array.

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

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

2025-10-29

🔧 FixesFixed 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

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

2025-10-24

🔧 FixesFixed 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

2025-10-21

🚀 New featuresBLIK 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.

BLIK requires SDK Core (enabled by default) AND must be added to enabledPaymentMethods array.

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

2025-10-17

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.

🚀 New featuresBilling 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:

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

2025-10-13

🔧 Fixes

Fixed Google Pay rendering issue in certain browser configurations

SDK Core Updates:

Vault CVV recapture
Billing address API improvements

Most changes in this release relate to SDK core development.

2025-10-08

✨ ImprovementsThis release contains internal SDK improvements with no user-facing component changes.Internal Changes:

Iframe lifecycle fixes
Payment methods filter list
Datadog logging integration

2025-10-06

🔧 Fixes

PayPal button height fix
Native payment method CSS improvements

2025-09-30

✨ ImprovementsThis release contains internal SDK improvements with no user-facing component changes.Internal Changes:

Card form slot handling improvements

2025-09-29

✨ ImprovementsThis 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

2025-09-18

✨ ImprovementsThis release contains internal SDK improvements with no user-facing component changes.Internal Changes:

Error standardization
HTTP retry logic
Locale support improvements

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

2025-08-20

✨ Improvements

Removed unnecessary peer dependencies and extended React version compatibility

2025-07-24

🔧 Fixes

Removed native :focus-within CSS selector and implemented alternative focus handling for Firefox compatibility

2025-07-08

🔧 FixesFixed 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

2025-07-07

🚀 New featuresPayment 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:

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

Documentation:

SDK Reference

2025-06-20

✨ Improvements

Extended Payment type definitions to include DLOCAL_PIX, ALMA, and PAY_NL_RIVERTY

2025-06-12

🚀 New featuresComplete 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

Breaking Change: Stricter TypeScript typing may reveal previously ignored errors

Example:

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

2025-05-19

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

🚀 New featuresIntroduced 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

2025-05-02

✨ Improvements

Improved icon display and alignment for card network selection

2025-05-02

🔧 Fixes

Fixed icon display next to card number input

2025-05-01

🚀 New features

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

2025-04-30

✨ Improvements

Enhanced vault component functionality
Improved transitions
Fixed custom style application

2025-04-15

🚀 New features

Introduced experimental Stripe ACH UI and configuration support

2025-04-15

✨ Improvements

Moved style injection logic into components for better reinitialization and stability

2025-04-10

✨ Improvements

Optimized NPM builds with improved bundling
Faster loading
Reduced CDN dependency

2025-04-10

🔧 Fixes

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

2025-04-10

🚀 New featuresIntroduced 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

2025-03-11

🔧 Fixes

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

2025-03-07

🚀 New featuresFirst 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

2025-03-01

✨ Improvements

Initial NPM package setup and name reservation

API changelogs

SDK changelogs

Migration guides

Primer checkout SDK