Advanced Integration

Learn about Vue components for Stripe.js and Stripe Elements.

Installation

npm install vue-stripe @stripe/stripe-js

Checkout provider

The CheckoutProvider provider allows you to use Element components and access the Stripe object in any nested component.

<script setup>
import { loadStripe } from '@stripe/stripe-js'
import { Elements } from 'vue-stripe'

const stripePromise = loadStripe('pk_test_xxx')

const options = {
  // passing the client secret obtained from the server
  clientSecret: '{{CLIENT_SECRET}}',
}
</script>

<template>
  <Elements :stripe="stripePromise" :options>
    <CheckoutForm />
  </Elements>
</template>

Prop	Description
stripe	A Stripe object or a Promise resolving to a Stripe object. Can initially be null for SSR apps.
options	Optional Elements configuration options. See available options.

Elements components

Element components provide a flexible way to securely collect payment information in your Vue app.

<script setup>
import { PaymentElement } from 'vue-stripe'
</script>

<template>
  <form>
    <PaymentElement />
    <button>Submit</button>
  </form>
</template>

Prop	Description
id	Passes through to the Element’s container.
class	Passes through to the Element’s container.
options	An object containing Element configuration options. See available options for the Payment Element or available options for individual payment method Elements.

Event	Description
@blur	Triggered when the Element loses focus.
@change	Triggered when data exposed by this Element is changed (for example, when there is an error).
@click	Triggered by the <PaymentRequestButtonElement> when it is clicked.
@escape	Triggered when the escape key is pressed within an Element.
@focus	Triggered when the Element receives focus.
@loadererror	Triggered when the Element fails to load. You only receive these events from the payment, linkAuthentication, address, and expressCheckout Elements.
@loaderstart	Triggered when the loader UI is mounted to the DOM and ready to be displayed. You only receive these events from the payment, linkAuthentication, address, and expressCheckout Elements.
@ready	Triggered when the Element is fully rendered and can accept imperative element.focus() calls.

Available Element components

There are many different kinds of Elements, useful for collecting different kinds of payment information. These are the available Elements today.

Component	Usage
AddressElement	Collects address details for 236+ regional formats. See the Address Element docs.
AfterpayClearpayMessageElement	Displays installments messaging for Afterpay payments.
AuBankAccountElement	Collects Australian bank account information (BSB and account number) for use with BECS Direct Debit payments.
CardCvcElement	Collects the card‘s CVC number.
CardElement	A flexible single-line input that collects all necessary card details.
CardExpiryElement	Collects the card‘s expiration date.
CardNumberElement	Collects the card number.
ExpressCheckoutElement	Allows you to accept card or wallet payments through one or more payment buttons, including Apple Pay, Google Pay, Link, or PayPal. See the Express Checkout Element docs.
FpxBankElement	The customer’s bank, for use with FPX payments.
IbanElement	The International Bank Account Number (IBAN). Available for SEPA countries.
IdealBankElement	The customer’s bank, for use with iDEAL payments.
LinkAuthenticationElement	Collects email addresses and allows users to log in to Link. See the Link Authentication Element docs.
PaymentElement	Collects payment details for 25+ payment methods from around the globe. See the Payment Element docs.
PaymentRequestButtonElement	An all-in-one checkout button backed by either Apple Pay or the Payment Request API. See the Payment Request Button docs.

useElements composable

useElements(): Readonly<Ref<Elements | null>>{lang=“ts-type”}

To safely pass the payment information collected by the Payment Element to the Stripe API, access the Elements instance so that you can use it with stripe.confirmPayment.

<script setup>
import { PaymentElement, useElements, useStripe } from 'vue-stripe'

const stripe = useStripe()
const elements = useElements()

async function handleSubmit() {
  if (!stripe.value || !elements.value) {
    // Stripe.js hasn't yet loaded.
    // Make sure to disable form submission until Stripe.js has loaded.
    return
  }

  const result = await stripe.value.confirmPayment({
    // `Elements` instance that was used to create the Payment Element
    elements: elements.value,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  })

  if (result.error) {
    // Show error to your customer (for example, payment details incomplete)
    console.log(result.error.message)
  }
  else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
}
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <PaymentElement />
    <button :disabled="!stripe">
      Submit
    </button>
  </form>
</template>

useStripe composable

useStripe(): Readonly<Ref<Stripe | null>>{lang=“ts-type”}

The useStripe composable returns a reference to the Stripe instance passed to the Elements provider.

<script setup>
import { PaymentElement, useElements, useStripe } from 'vue-stripe'

const stripe = useStripe()
const elements = useElements()

async function handleSubmit() {
  if (!stripe.value || !elements.value) {
    // Stripe.js hasn't yet loaded.
    // Make sure to disable form submission until Stripe.js has loaded.
    return
  }

  const result = await stripe.value.confirmPayment({
    // `Elements` instance that was used to create the Payment Element
    elements: elements.value,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  })

  if (result.error) {
    // Show error to your customer (for example, payment details incomplete)
    console.log(result.error.message)
  }
  else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
}
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <PaymentElement />
    <button :disabled="!stripe">
      Submit
    </button>
  </form>
</template>