Skip to content

Express Checkout ​

Offer one-click payment with the Express Checkout Element, which renders Apple Pay, Google Pay, Link and PayPal buttons based on what the customer's browser and your Dashboard support.

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; the element shows the wallet buttons that this browser and device support, such as Apple Pay in Safari or Google Pay in Chrome. In test mode, Stripe does not charge the card saved in your wallet. A headless or private window may show no buttons.

The Express Checkout Element renders one-click wallet buttons — Apple Pay, Google Pay, Link, PayPal — depending on what the customer's browser and your Dashboard support. Buttons that aren't available simply don't render.

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 { defineComponent, h, ref } from 'vue'
import {
  VueStripeProvider,
  VueStripeElements,
  VueStripeExpressCheckoutElement,
  usePaymentIntent
} 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 { createPaymentIntent, formatPrice, loading, error } = useBackendApi()

const step = ref<'select' | 'pay' | 'done'>('select')
const product = ref<Product | null>(null)
const clientSecret = ref<string | null>(null)
const confirmError = ref<string | null>(null)

async function onProductSelected(p: Product) {
  product.value = p
  confirmError.value = null
  try {
    const res = await createPaymentIntent({
      priceId: p.price.id,
      amount: p.price.amount,
      currency: p.price.currency
    })
    clientSecret.value = res.clientSecret
    step.value = 'pay'
  } catch (err) {
    confirmError.value = err instanceof Error ? err.message : 'Failed to create payment intent'
  }
}

function reset() {
  step.value = 'select'
  product.value = null
  clientSecret.value = null
  confirmError.value = null
}

const ExpressForm = defineComponent({
  name: 'ExpressForm',
  props: { clientSecret: { type: String, required: true } },
  emits: ['done', 'error'],
  setup(props, { emit }) {
    const { confirmPayment } = usePaymentIntent()
    const available = ref<boolean | null>(null)

    async function onConfirm() {
      try {
        // usePaymentIntent runs elements.submit() before confirming.
        const { error: err, paymentIntent } = await confirmPayment({
          clientSecret: props.clientSecret,
          confirmParams: { return_url: window.location.href },
          redirect: 'if_required'
        })
        if (err) throw new Error(err.message)
        if (paymentIntent?.status === 'succeeded') emit('done')
      } catch (e) {
        emit('error', e instanceof Error ? e.message : 'Payment failed')
      }
    }

    return () =>
      h('div', { class: 'express-form' }, [
        h(VueStripeExpressCheckoutElement, {
          // The element only renders wallets the browser/device supports.
          onReady: (ev) => (available.value = !!ev.availablePaymentMethods),
          onConfirm
        }),
        available.value === false
          ? h(
              'p',
              { class: 'hint' },
              'No express wallets are available in this browser. Try Safari (Apple Pay) or Chrome with Google Pay / a saved Link account.'
            )
          : null
      ])
  }
})
</script>

<template>
  <div class="express-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">
        The Express Checkout Element renders one-click wallet buttons — Apple Pay, Google Pay, Link,
        PayPal — depending on what the customer's browser and your Dashboard support. Buttons that
        aren't available simply don't render.
      </p>

      <div v-if="step === 'select'" class="step">
        <ProductSelector filter="one_time" @select="onProductSelected" />
        <div v-if="loading" class="loading-state">
          <span class="spinner"></span> Creating payment intent…
        </div>
        <div v-if="confirmError || error" class="error-box">
          <strong>Error:</strong> {{ confirmError || error }}
        </div>
      </div>

      <div v-else-if="step === 'pay'" class="step">
        <div class="summary">
          <span>{{ product?.name }}</span>
          <span class="price">{{
            formatPrice(product?.price.amount || 0, product?.price.currency || 'usd')
          }}</span>
        </div>
        <div class="stripe-container">
          <VueStripeProvider :publishable-key="publishableKey">
            <VueStripeElements :client-secret="clientSecret!">
              <ExpressForm
                :client-secret="clientSecret!"
                @done="step = 'done'"
                @error="(e) => (confirmError = e)"
              />
            </VueStripeElements>
          </VueStripeProvider>
        </div>
        <button class="link-btn" @click="reset">Change product</button>
        <div v-if="confirmError" class="error-box"><strong>Error:</strong> {{ confirmError }}</div>
      </div>

      <div v-else class="step success">
        <span class="success-icon"><DocIcon name="check" :size="28" :stroke-width="2.5" /></span>
        <h3>Payment successful!</h3>
        <button class="link-btn" @click="reset">Start over</button>
      </div>
    </template>
  </div>
</template>

<style scoped>
.express-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);
}
.step {
  display: flex;
  flex-direction: column;
  gap: 1rem;
  align-items: flex-start;
}
.summary {
  display: flex;
  justify-content: space-between;
  width: 100%;
  padding: 0.75rem 1rem;
  background: var(--vp-c-bg-soft);
  border-radius: 6px;
}
.summary .price {
  font-weight: 700;
  color: var(--vp-c-brand-1);
}
.stripe-container {
  width: 100%;
  padding: 1.5rem;
  background: var(--vp-c-bg-soft);
  border-radius: 8px;
}
.express-form {
  width: 100%;
}
/* .hint is rendered by the inner ExpressForm component; scope it through
   .express-form so :deep() reaches it without leaking into ProductSelector's
   own .hint (which also lives in this component's subtree). */
.express-form :deep(.hint) {
  margin: 0.75rem 0 0;
  font-size: 0.8rem;
  color: var(--vp-c-text-3);
}
.loading-state {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  color: var(--vp-c-text-2);
}
.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;
}
.spinner {
  width: 1rem;
  height: 1rem;
  border: 2px solid var(--vp-c-divider);
  border-top-color: var(--vp-c-brand-1);
  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 asks the backend to create a PaymentIntent for that product's price and returns its client secret.
  3. VueStripeElements gets the client secret and wraps VueStripeExpressCheckoutElement. The element renders a button only for each wallet it can offer here. Its ready event reports availablePaymentMethods; when there are none, the demo says that no wallet is available in this browser.
  4. When the customer approves the payment in the wallet's sheet, the element emits confirm. The handler calls confirmPayment() from usePaymentIntent(), which runs elements.submit() and confirms the PaymentIntent with redirect: 'if_required'.
  5. When the PaymentIntent status is succeeded, the demo shows a success message. A Stripe error appears under the element instead.

The buttons depend on the browser, the device, the wallets set up on it, and the payment methods enabled on the Stripe account.