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
<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>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
- Start asks the backend to create a SetupIntent and returns its client secret.
VueStripeElementsgets the SetupIntent's client secret and rendersVueStripePaymentElement, which shows the payment methods that can be saved with it.- Save card calls
confirmSetup()fromuseSetupIntent()withredirect: 'if_required'. The composable runselements.submit()to validate the form, then confirms the SetupIntent. Stripe runs 3D Secure when the card requires it. - 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. - 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.
