Embedded Checkout Example
Stripe's prebuilt Checkout page inside this page. The server creates a Checkout Session with ui_mode: 'embedded_page', and VueStripeEmbeddedCheckout mounts it with stripe.createEmbeddedCheckoutPage(). Stripe renders the line items, totals and payment form in an iframe; after payment it redirects back here.
Try the demo
The demo runs in Stripe test mode against the demo backend at backend.vuestripe.com, so nothing is charged. Pick a product; Stripe's Checkout page loads in a frame below. Pay with the test card 4242 4242 4242 4242, any future expiry date and any CVC.
Select a Product
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.
<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { VueStripeProvider, VueStripeEmbeddedCheckout } from '@vue-stripe/vue-stripe'
import type { StripeEmbeddedCheckoutAnalyticsEventUnion } from '@vue-stripe/vue-stripe'
import ProductSelector from './ProductSelector.vue'
import PaymentStatus from './PaymentStatus.vue'
import { useBackendApi, type Product } from '../../composables/useBackendApi'
import { useStripeConfig } from '../../composables/useStripeConfig'
import DocIcon from '../DocIcon.vue'
const { publishableKey } = useStripeConfig()
const { createCheckoutSession, formatPrice } = useBackendApi()
// Step management: Product -> Checkout -> Complete
const step = ref<'select' | 'checkout' | 'complete'>('select')
const selectedProduct = ref<Product | null>(null)
const sessionId = ref<string | null>(null)
const checkoutError = ref<string | null>(null)
const events = ref<string[]>([])
// Stripe redirects back here after payment with the session ID in the URL.
onMounted(() => {
const id = new URLSearchParams(window.location.search).get('session_id')
if (id) {
sessionId.value = id
step.value = 'complete'
}
})
// Stripe calls this when it creates the embedded page.
function fetchClientSecret(): Promise<string> {
const product = selectedProduct.value!
const returnUrl = `${window.location.origin}${window.location.pathname}?result=success&session_id={CHECKOUT_SESSION_ID}`
return createCheckoutSession({
priceId: product.price.id,
uiMode: 'embedded_page',
returnUrl
}).then((result) => {
if (!result.clientSecret) throw new Error('The backend did not return a client secret')
sessionId.value = result.sessionId
return result.clientSecret
})
}
function onProductSelected(product: Product) {
selectedProduct.value = product
checkoutError.value = null
events.value = []
step.value = 'checkout'
}
function onAnalytics(event: StripeEmbeddedCheckoutAnalyticsEventUnion) {
events.value.push(event.eventType)
}
function reset() {
step.value = 'select'
selectedProduct.value = null
sessionId.value = null
checkoutError.value = null
events.value = []
}
</script>
<template>
<div class="embedded-checkout-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 />
<!-- Progress Steps -->
<div class="progress-steps">
<div
class="progress-step"
:class="{ active: step === 'select', completed: step !== 'select' }"
>
<span class="step-dot">1</span>
<span class="step-label">Product</span>
</div>
<div class="progress-line" :class="{ completed: step !== 'select' }"></div>
<div
class="progress-step"
:class="{ active: step === 'checkout', completed: step === 'complete' }"
>
<span class="step-dot">2</span>
<span class="step-label">Checkout</span>
</div>
<div class="progress-line" :class="{ completed: step === 'complete' }"></div>
<div class="progress-step" :class="{ active: step === 'complete' }">
<span class="step-dot">3</span>
<span class="step-label">Complete</span>
</div>
</div>
<!-- Step 1: Select Product -->
<div v-if="step === 'select'" class="step-content">
<ProductSelector filter="one_time" @select="onProductSelected" />
</div>
<!-- Step 2: Embedded Checkout -->
<div v-else-if="step === 'checkout'" class="step-content">
<div class="step-section">
<div class="step-header">
<h3>Checkout</h3>
<button class="change-btn" @click="reset">Change Product</button>
</div>
<div class="product-summary">
<span>{{ selectedProduct?.name }}</span>
<span class="price">{{
formatPrice(
selectedProduct?.price.amount || 0,
selectedProduct?.price.currency || 'usd'
)
}}</span>
</div>
<div v-if="checkoutError" class="error-box">
<strong>Error:</strong> {{ checkoutError }}
</div>
<div class="stripe-container">
<VueStripeProvider :publishable-key="publishableKey">
<VueStripeEmbeddedCheckout
:fetch-client-secret="fetchClientSecret"
@analytics="onAnalytics"
@complete="step = 'complete'"
@error="(message: string) => (checkoutError = message)"
>
<template #loading>
<div class="loading-state">
<span class="spinner"></span> Creating checkout session...
</div>
</template>
</VueStripeEmbeddedCheckout>
</VueStripeProvider>
</div>
<p v-if="events.length" class="event-list">
Analytics events: <code>{{ events.join(', ') }}</code>
</p>
</div>
</div>
<!-- Step 3: Complete -->
<div v-else-if="step === 'complete'" class="step-content">
<div class="success-state">
<span class="success-icon"><DocIcon name="check" :size="32" :stroke-width="2.5" /></span>
<h3>Checkout Complete</h3>
<p v-if="selectedProduct">Thank you for your purchase of {{ selectedProduct.name }}.</p>
<p v-if="sessionId" class="payment-id">
Checkout Session: <code>{{ sessionId }}</code>
</p>
<button class="reset-btn" @click="reset">Start Over</button>
</div>
</div>
</template>
</div>
</template>
<style scoped>
.embedded-checkout-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;
}
.progress-steps {
display: flex;
align-items: center;
justify-content: center;
margin-bottom: 2rem;
padding: 1rem 0;
}
.progress-step {
display: flex;
flex-direction: column;
align-items: center;
gap: 0.5rem;
}
.step-dot {
display: inline-flex;
align-items: center;
justify-content: center;
width: 2rem;
height: 2rem;
background: var(--vp-c-bg-soft);
border: 2px solid var(--vp-c-divider);
border-radius: 50%;
font-size: 0.875rem;
font-weight: 600;
color: var(--vp-c-text-2);
}
.progress-step.active .step-dot {
background: var(--vp-c-brand-1);
border-color: var(--vp-c-brand-1);
color: white;
}
.progress-step.completed .step-dot {
background: var(--vp-c-green-1);
border-color: var(--vp-c-green-1);
color: white;
}
.step-label {
font-size: 0.75rem;
color: var(--vp-c-text-2);
}
.progress-line {
width: 4rem;
height: 2px;
background: var(--vp-c-divider);
margin: 0 0.5rem 1.5rem;
}
.progress-line.completed {
background: var(--vp-c-green-1);
}
.step-content {
min-height: 200px;
}
.step-section {
padding: 1.5rem;
background: var(--vp-c-bg-soft);
border-radius: 8px;
}
.step-header {
display: flex;
align-items: center;
justify-content: space-between;
margin-bottom: 1rem;
}
.step-header h3 {
margin: 0;
font-size: 1rem;
font-weight: 600;
}
.change-btn {
padding: 0.25rem 0.75rem;
background: transparent;
border: 1px solid var(--vp-c-divider);
border-radius: 4px;
font-size: 0.75rem;
color: var(--vp-c-text-2);
cursor: pointer;
}
.change-btn:hover {
border-color: var(--vp-c-brand-1);
color: var(--vp-c-brand-1);
}
.product-summary {
display: flex;
justify-content: space-between;
align-items: center;
padding: 0.75rem 1rem;
margin-bottom: 1rem;
background: var(--vp-c-bg);
border-radius: 6px;
}
.product-summary .price {
font-weight: 700;
color: var(--vp-c-brand-1);
}
/* Stripe's Checkout page has its own white background. */
.stripe-container {
padding: 1rem;
background: #ffffff;
border-radius: 8px;
}
.loading-state {
display: flex;
align-items: center;
justify-content: center;
gap: 0.5rem;
padding: 1rem;
color: #6b7280;
}
.event-list {
margin: 1rem 0 0;
font-size: 0.75rem;
color: var(--vp-c-text-2);
}
.error-box {
margin-bottom: 1rem;
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-state {
text-align: center;
padding: 2rem;
}
.success-icon {
display: inline-flex;
align-items: center;
justify-content: center;
width: 4rem;
height: 4rem;
background: var(--vp-c-green-1);
color: white;
border-radius: 50%;
font-size: 2rem;
margin-bottom: 1rem;
}
.success-state h3 {
margin: 0 0 0.5rem 0;
font-size: 1.25rem;
}
.success-state p {
margin: 0.5rem 0;
color: var(--vp-c-text-2);
}
.payment-id code {
padding: 0.25rem 0.5rem;
background: var(--vp-c-bg-soft);
border-radius: 4px;
font-size: 0.75rem;
}
.reset-btn {
margin-top: 1.5rem;
padding: 0.75rem 1.5rem;
background: var(--vp-c-bg-soft);
border: 1px solid var(--vp-c-divider);
border-radius: 6px;
font-size: 0.875rem;
cursor: pointer;
}
.reset-btn:hover {
border-color: var(--vp-c-brand-1);
color: var(--vp-c-brand-1);
}
.spinner {
width: 1rem;
height: 1rem;
border: 2px solid #e5e7eb;
border-top-color: #635bff;
border-radius: 50%;
animation: spin 0.8s linear infinite;
}
@keyframes spin {
to {
transform: rotate(360deg);
}
}
</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
- The product step loads the demo account's one-time products from the backend.
- Choosing a product renders
VueStripeEmbeddedCheckoutinsideVueStripeProvider, with afetch-client-secretfunction. - Stripe calls that function when it creates the page. The function asks the backend to create a Checkout Session with
uiMode: 'embedded_page'and a return URL to this page that carriessession_id={CHECKOUT_SESSION_ID}, and returns the session's client secret. - Stripe renders the line items, the total and the payment form in an iframe. The component re-emits Stripe's analytics events through
@analytics, and the demo lists their names under the frame. - After payment, Stripe sends the browser to the return URL. On load, the demo reads
session_idfrom the URL and shows the Checkout Session ID. It also listens to@complete, which moves to the same step when the session completes without a redirect. - If the session cannot be created,
@errorcarries the message and the demo shows it.
See also
How-to guide: Embed Stripe Checkout. Reference: VueStripeEmbeddedCheckout.
Starter app: examples/checkout is a complete Vite + Vue app with hosted and embedded Checkout and its Node server (open in StackBlitz).
