Skip to content

Save a Card (SetupIntent) ​

Save a customer's card for future off-session charges without taking a payment now. The useSetupIntent composable validates the Payment Element and confirms the SetupIntent for you.

Try the demo ​

The demo runs in Stripe test mode against the demo backend at backend.vuestripe.com, so nothing is charged. Click Start, enter the test card 4242 4242 4242 4242, any future expiry date and any CVC in the Payment Element, then click Save card. No money moves; the demo ends with the SetupIntent ID.

A SetupIntent saves a card for future off-session charges without taking a payment now. useSetupIntent() runs elements.submit() then confirmSetup() for you.

Source code ​

The code the demo above runs. Open it in StackBlitz to run and fork it with every file it imports, in Stripe test mode against the demo backend.

View source on GitHub
vue
<script setup lang="ts">
import { defineComponent, h, ref, computed } from 'vue'
import {
  VueStripeProvider,
  VueStripeElements,
  VueStripePaymentElement,
  useSetupIntent
} from '@vue-stripe/vue-stripe'
import PaymentStatus from './PaymentStatus.vue'
import { useBackendApi } from '../../composables/useBackendApi'
import { useStripeConfig } from '../../composables/useStripeConfig'
import DocIcon from '../DocIcon.vue'

const { publishableKey } = useStripeConfig()
const { createSetupIntent, loading, error } = useBackendApi()

const step = ref<'start' | 'collect' | 'saved'>('start')
const clientSecret = ref<string | null>(null)
const setupIntentId = ref<string | null>(null)
const startError = ref<string | null>(null)

async function start() {
  startError.value = null
  try {
    const res = await createSetupIntent({})
    clientSecret.value = res.clientSecret
    setupIntentId.value = res.setupIntentId
    step.value = 'collect'
  } catch (err) {
    startError.value = err instanceof Error ? err.message : 'Failed to create setup intent'
  }
}

function reset() {
  step.value = 'start'
  clientSecret.value = null
  setupIntentId.value = null
  startError.value = null
}

// Inner component drives confirmSetup via the composable.
const SaveCardForm = defineComponent({
  name: 'SaveCardForm',
  props: { clientSecret: { type: String, required: true } },
  emits: ['saved', 'error'],
  setup(props, { emit }) {
    const { confirmSetup, loading: confirming } = useSetupIntent()
    const paymentReady = ref(false)
    const canSave = computed(() => paymentReady.value && !confirming.value)

    async function save() {
      const { error, setupIntent } = await confirmSetup({
        clientSecret: props.clientSecret,
        redirect: 'if_required'
      })
      if (error) emit('error', error.message)
      else if (setupIntent?.status === 'succeeded') emit('saved')
    }

    return () =>
      h('div', { class: 'save-form' }, [
        h('div', { class: 'pe-wrap' }, [
          h(VueStripePaymentElement, { onReady: () => (paymentReady.value = true) })
        ]),
        h(
          'button',
          {
            class: ['btn', { disabled: !canSave.value }],
            disabled: !canSave.value,
            onClick: save
          },
          confirming.value ? 'Saving…' : 'Save card'
        )
      ])
  }
})
</script>

<template>
  <div class="setup-example">
    <div v-if="!publishableKey" class="warning-box">
      <strong><DocIcon name="warning" /> Missing Configuration</strong>
      <p>Please set <code>VITE_STRIPE_PUBLISHABLE_KEY</code> in your <code>.env</code> file.</p>
    </div>

    <template v-else>
      <PaymentStatus />
      <p class="intro">
        A <strong>SetupIntent</strong> saves a card for future off-session charges without taking a
        payment now. <code>useSetupIntent()</code> runs <code>elements.submit()</code> then
        <code>confirmSetup()</code> for you.
      </p>

      <!-- Step 1 -->
      <div v-if="step === 'start'" class="step">
        <button class="btn" :disabled="loading" @click="start">
          {{ loading ? 'Preparing…' : 'Start — save a card' }}
        </button>
        <div v-if="startError || error" class="error-box">
          <strong>Error:</strong> {{ startError || error }}
        </div>
      </div>

      <!-- Step 2 -->
      <div v-else-if="step === 'collect'" class="step">
        <div class="stripe-container">
          <VueStripeProvider :publishable-key="publishableKey">
            <VueStripeElements :client-secret="clientSecret!">
              <SaveCardForm
                :client-secret="clientSecret!"
                @saved="step = 'saved'"
                @error="(e) => (startError = e)"
              />
            </VueStripeElements>
          </VueStripeProvider>
        </div>
        <button class="link-btn" @click="reset">Cancel</button>
        <div v-if="startError" class="error-box"><strong>Error:</strong> {{ startError }}</div>
      </div>

      <!-- Step 3 -->
      <div v-else class="step success">
        <span class="success-icon"><DocIcon name="check" :size="28" :stroke-width="2.5" /></span>
        <h3>Card saved!</h3>
        <p v-if="setupIntentId" class="id">
          SetupIntent: <code>{{ setupIntentId }}</code>
        </p>
        <button class="link-btn" @click="reset">Save another</button>
      </div>
    </template>
  </div>
</template>

<style scoped>
.setup-example {
  padding: 1.5rem;
  background: var(--vp-c-bg);
  border: 1px solid var(--vp-c-divider);
  border-radius: 12px;
}
.warning-box {
  padding: 1rem;
  background: var(--vp-c-yellow-soft);
  border: 1px solid var(--vp-c-yellow-1);
  border-radius: 8px;
  color: var(--vp-c-yellow-darker);
}
.warning-box strong {
  display: block;
  margin-bottom: 0.5rem;
}
.warning-box p {
  margin: 0;
  font-size: 0.875rem;
}
.warning-box code {
  padding: 0.125rem 0.375rem;
  background: rgba(0, 0, 0, 0.1);
  border-radius: 3px;
}

.intro {
  margin: 0 0 1.25rem;
  font-size: 0.9rem;
  color: var(--vp-c-text-2);
}
.intro code {
  padding: 0.125rem 0.375rem;
  background: var(--vp-c-bg-soft);
  border-radius: 3px;
  font-size: 0.85em;
}

.step {
  display: flex;
  flex-direction: column;
  gap: 1rem;
  align-items: flex-start;
}
.stripe-container {
  width: 100%;
  padding: 1.5rem;
  background: var(--vp-c-bg-soft);
  border-radius: 8px;
}
.save-form {
  display: flex;
  flex-direction: column;
  gap: 1rem;
}
/* The Payment Element wrapper and Save button are rendered by the inner
   SaveCardForm component, so this SFC's scoped styles only reach them via :deep().
   (--vp-c-bg is white in light / near-black in dark, replacing the old
   white + :root.dark override that couldn't reach the nested element.) */
:deep(.pe-wrap) {
  min-height: 180px;
  padding: 0.75rem;
  background: var(--vp-c-bg);
  border: 1px solid var(--vp-c-divider);
  border-radius: 6px;
}
:deep(.btn) {
  padding: 0.75rem 1.25rem;
  background: #635bff;
  color: white;
  border: none;
  border-radius: 6px;
  font-size: 0.95rem;
  font-weight: 600;
  cursor: pointer;
  transition: opacity 0.2s;
}
:deep(.btn:hover:not(:disabled)) {
  opacity: 0.9;
}
:deep(.btn:disabled) {
  opacity: 0.6;
  cursor: not-allowed;
}
.link-btn {
  background: none;
  border: none;
  color: var(--vp-c-brand-1);
  font-size: 0.85rem;
  cursor: pointer;
  padding: 0;
}

.error-box {
  width: 100%;
  padding: 0.75rem 1rem;
  background: var(--vp-c-danger-soft);
  border: 1px solid var(--vp-c-danger-1);
  border-radius: 6px;
  color: var(--vp-c-danger-1);
  font-size: 0.875rem;
}

.success {
  align-items: center;
  text-align: center;
  padding: 1.5rem;
}
.success-icon {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 3.5rem;
  height: 3.5rem;
  background: var(--vp-c-green-1);
  color: white;
  border-radius: 50%;
  font-size: 1.75rem;
}
.success h3 {
  margin: 0.5rem 0 0;
}
.id code {
  padding: 0.25rem 0.5rem;
  background: var(--vp-c-bg-soft);
  border-radius: 4px;
  font-size: 0.75rem;
}
</style>
ts
import { ref, readonly } from 'vue'
import { useStripeConfig } from './useStripeConfig'

// Types
export interface ProductPrice {
  id: string
  amount: number | null
  currency: string
  interval: string | null
  intervalCount: number | null
}

export interface Product {
  id: string
  name: string
  description: string | null
  images: string[]
  type: 'one_time' | 'recurring'
  price: ProductPrice
  metadata: Record<string, string>
}

export interface PaymentIntentResult {
  clientSecret: string
  paymentIntentId: string
  amount: number
  currency: string
}

export interface CheckoutSessionResult {
  /** Stripe-hosted page URL (`uiMode: 'hosted'`), otherwise null. */
  url: string | null
  sessionId: string
  /** Client secret for `elements`, `embedded_page` and `form` sessions, otherwise null. */
  clientSecret: string | null
}

export interface SubscriptionResult {
  subscriptionId: string
  clientSecret: string | null
  status: string
  customerId: string
}

export interface SetupIntentResult {
  clientSecret: string
  setupIntentId: string
}

export interface IdentitySessionResult {
  clientSecret: string
  verificationSessionId: string
}

/** Error body returned by the backend on non-2xx responses. */
interface ApiErrorResponse {
  error?: string
}

interface ProductsResponse {
  products?: Product[]
}

/** Parse a JSON response body as the expected backend response shape. */
async function parseJson<T>(response: Response): Promise<T> {
  return (await response.json()) as T
}

/** Throw an Error carrying the backend's error message (or the HTTP status). */
async function throwApiError(response: Response): Promise<never> {
  const data = await parseJson<ApiErrorResponse>(response).catch((): ApiErrorResponse => ({}))
  throw new Error(data.error || `API Error: ${response.status}`)
}

export function useBackendApi() {
  const { apiUrl } = useStripeConfig()
  const loading = ref(false)
  const error = ref<string | null>(null)

  /**
   * Fetch all available products from the backend
   */
  async function getProducts(): Promise<Product[]> {
    loading.value = true
    error.value = null

    try {
      const response = await fetch(`${apiUrl.value}/api/products`)

      if (!response.ok) {
        await throwApiError(response)
      }

      const data = await parseJson<ProductsResponse>(response)
      return data.products || []
    } catch (err) {
      error.value = err instanceof Error ? err.message : 'Failed to fetch products'
      throw err
    } finally {
      loading.value = false
    }
  }

  /**
   * Create a payment intent for a one-time payment
   */
  async function createPaymentIntent(
    options: {
      /** Amount in cents; null/omitted uses the backend default. */
      amount?: number | null
      currency?: string
      priceId?: string
      description?: string
      metadata?: Record<string, string>
    } = {}
  ): Promise<PaymentIntentResult> {
    loading.value = true
    error.value = null

    try {
      const response = await fetch(`${apiUrl.value}/api/payment-intent`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(options)
      })

      if (!response.ok) {
        await throwApiError(response)
      }

      return await parseJson<PaymentIntentResult>(response)
    } catch (err) {
      error.value = err instanceof Error ? err.message : 'Failed to create payment intent'
      throw err
    } finally {
      loading.value = false
    }
  }

  /**
   * Create a regional PaymentIntent (SEPA Direct Debit / BECS / ACH Direct Debit).
   * The backend routes share the same request/response shape.
   */
  async function createRegionalIntent(
    path: 'sepa-debit-intent' | 'becs-intent' | 'ach-debit-intent',
    options: {
      amount?: number
      currency?: string
      description?: string
      metadata?: Record<string, string>
    } = {}
  ): Promise<PaymentIntentResult> {
    loading.value = true
    error.value = null

    try {
      const response = await fetch(`${apiUrl.value}/api/${path}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(options)
      })

      if (!response.ok) {
        await throwApiError(response)
      }

      return await parseJson<PaymentIntentResult>(response)
    } catch (err) {
      error.value = err instanceof Error ? err.message : `Failed to create ${path}`
      throw err
    } finally {
      loading.value = false
    }
  }

  const createSepaIntent = (options: { amount?: number; metadata?: Record<string, string> } = {}) =>
    createRegionalIntent('sepa-debit-intent', options)
  // BECS Direct Debit (AUD only - Australia)
  const createBecsIntent = (
    options: { amount?: number; description?: string; metadata?: Record<string, string> } = {}
  ) => createRegionalIntent('becs-intent', options)
  // ACH Direct Debit (USD only - United States), bank account linked with Financial Connections
  const createAchIntent = (
    options: { amount?: number; description?: string; metadata?: Record<string, string> } = {}
  ) => createRegionalIntent('ach-debit-intent', options)

  /**
   * Create a checkout session for Stripe hosted checkout
   */
  async function createCheckoutSession(
    options: {
      amount?: number
      currency?: string
      priceId?: string
      productName?: string
      productDescription?: string
      quantity?: number
      mode?: 'payment' | 'subscription' | 'setup'
      successUrl?: string
      cancelUrl?: string
      customerEmail?: string
      metadata?: Record<string, string>
      /** `hosted` (default) returns `url`; the other modes return `clientSecret`. */
      uiMode?: 'hosted' | 'elements' | 'embedded_page' | 'form'
      /** Where Stripe sends the customer after a non-hosted session completes. */
      returnUrl?: string
      taxIdCollection?: boolean
    } = {}
  ): Promise<CheckoutSessionResult> {
    loading.value = true
    error.value = null

    try {
      const response = await fetch(`${apiUrl.value}/api/checkout-session`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(options)
      })

      if (!response.ok) {
        await throwApiError(response)
      }

      return await parseJson<CheckoutSessionResult>(response)
    } catch (err) {
      error.value = err instanceof Error ? err.message : 'Failed to create checkout session'
      throw err
    } finally {
      loading.value = false
    }
  }

  /**
   * Create a subscription
   */
  async function createSubscription(options: {
    priceId: string
    customerEmail: string
    paymentMethodId?: string
    name?: string
    metadata?: Record<string, string>
  }): Promise<SubscriptionResult> {
    loading.value = true
    error.value = null

    try {
      const response = await fetch(`${apiUrl.value}/api/subscription`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(options)
      })

      if (!response.ok) {
        await throwApiError(response)
      }

      return await parseJson<SubscriptionResult>(response)
    } catch (err) {
      error.value = err instanceof Error ? err.message : 'Failed to create subscription'
      throw err
    } finally {
      loading.value = false
    }
  }

  /**
   * Create a setup intent for saving payment methods
   */
  async function createSetupIntent(
    options: {
      customerId?: string
      description?: string
      metadata?: Record<string, string>
    } = {}
  ): Promise<SetupIntentResult> {
    loading.value = true
    error.value = null

    try {
      const response = await fetch(`${apiUrl.value}/api/setup-intent`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(options)
      })

      if (!response.ok) {
        await throwApiError(response)
      }

      return await parseJson<SetupIntentResult>(response)
    } catch (err) {
      error.value = err instanceof Error ? err.message : 'Failed to create setup intent'
      throw err
    } finally {
      loading.value = false
    }
  }

  /**
   * Create a Stripe Identity VerificationSession (document check)
   */
  async function createIdentitySession(): Promise<IdentitySessionResult> {
    loading.value = true
    error.value = null

    try {
      const response = await fetch(`${apiUrl.value}/api/identity-session`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({})
      })

      if (!response.ok) {
        await throwApiError(response)
      }

      return await parseJson<IdentitySessionResult>(response)
    } catch (err) {
      error.value = err instanceof Error ? err.message : 'Failed to create verification session'
      throw err
    } finally {
      loading.value = false
    }
  }

  /**
   * Format price for display
   */
  function formatPrice(amount: number | null, currency: string): string {
    if (amount === null) return 'Price not available'

    return new Intl.NumberFormat('en-US', {
      style: 'currency',
      currency: currency.toUpperCase()
    }).format(amount / 100)
  }

  return {
    // State
    loading: readonly(loading),
    error: readonly(error),
    apiUrl,

    // Methods
    getProducts,
    createPaymentIntent,
    createSepaIntent,
    createBecsIntent,
    createAchIntent,
    createCheckoutSession,
    createSubscription,
    createSetupIntent,
    createIdentitySession,

    // Helpers
    formatPrice
  }
}

How the demo works ​

  1. Start asks the backend to create a SetupIntent and returns its client secret.
  2. VueStripeElements gets the SetupIntent's client secret and renders VueStripePaymentElement, which shows the payment methods that can be saved with it.
  3. Save card calls confirmSetup() from useSetupIntent() with redirect: 'if_required'. The composable runs elements.submit() to validate the form, then confirms the SetupIntent. Stripe runs 3D Secure when the card requires it.
  4. When the SetupIntent status is succeeded, the card is saved as a PaymentMethod and the demo shows the SetupIntent ID. A Stripe error is shown instead when confirming fails.
  5. Payment methods that need a redirect return to this page, where a banner reads the result from the URL.

Saving a card is the first half of charging it later: a server would use the saved PaymentMethod for off-session payments.

See also

How-to guide: Save a payment method for later. Reference: useSetupIntent.