Skip to content

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.

1Product
2Checkout
3Complete
0

Select a Product

Loading test products...

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 { 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>
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. The product step loads the demo account's one-time products from the backend.
  2. Choosing a product renders VueStripeEmbeddedCheckout inside VueStripeProvider, with a fetch-client-secret function.
  3. 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 carries session_id={CHECKOUT_SESSION_ID}, and returns the session's client secret.
  4. 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.
  5. After payment, Stripe sends the browser to the return URL. On load, the demo reads session_id from 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.
  6. If the session cannot be created, @error carries 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).