v2 to v3

Migrating from v2 to v3

v3 syncs Vue Stripe with @stripe/react-stripe-js 6.8.1, which requires Stripe.js v9.

Upgrade Stripe.js first

npm install vue-stripe@^3 @stripe/stripe-js@^9.5.0

Stripe.js v9 removed stripe.initCheckout() and split it into two entry points. That is what forces the checkout changes below. There is no way to keep the old API working on v9.

CheckoutProvider is removed

Pick the provider that matches your integration.

-import { CheckoutProvider } from 'vue-stripe/checkout'
+import { CheckoutElementsProvider } from 'vue-stripe/checkout'

-<CheckoutProvider :stripe="stripePromise" :options="options">
+<CheckoutElementsProvider :stripe="stripePromise" :options="options">

New checkout composables

useCheckout() still works under both providers and still returns the Elements shaped result, so existing code keeps running. It is deprecated. Move to the provider-specific composable, which returns the exact actions its SDK exposes.

Calling the wrong one for your provider throws with a message telling you which to use instead.

PaymentFormElement became CheckoutForm

-import { PaymentFormElement } from 'vue-stripe'
+import { CheckoutForm } from 'vue-stripe/checkout'

It also moved entry points, and its elementType is now reported as checkoutForm rather than paymentForm. Update any handler that reads it.

-@loaderror="e => console.log(e.elementType) // 'paymentForm'"
+@loaderror="e => console.log(e.elementType) // 'checkoutForm'"

The types renamed alongside it, from PaymentFormElementProps and PaymentFormElementEmits to CheckoutFormProps and CheckoutFormEmits.

Appearance options moved for the form provider

CheckoutElementsProvider keeps appearance and fonts under elementsOptions, matching the old CheckoutProvider. CheckoutFormProvider takes them at the top level.

// CheckoutElementsProvider
const options = {
  clientSecret,
  elementsOptions: { appearance: { theme: 'night' } },
}

// CheckoutFormProvider
const formOptions = {
  clientSecret,
  appearance: { theme: 'night' },
}

New components

Nothing here is breaking. These simply did not exist in v2.

Root entry point: CurrencySelectorElement, ContactDetailsElement, ShippingAddressElement, TermsElement, IssuingCardNumberDisplayElement, IssuingCardCvcDisplayElement, IssuingCardExpiryDisplayElement, IssuingCardPinDisplayElement, IssuingCardCopyButtonElement.

Checkout entry point: CheckoutForm, ContactDetailsElement, TermsElement.

New event

Elements now emit availablepaymentmethodschange, matching onAvailablePaymentMethodsChange in React Stripe.js.

Fixed

The checkout form element called createPaymentFormElement, which Stripe.js v9 renamed to createForm. If you were on a v9 prerelease, this was broken and now works.