ACH Direct Debit Example
Pay from a US bank account. The server creates a PaymentIntent for us_bank_account; collectBankAccountForPayment() from useFinancialConnections() opens Stripe's Financial Connections modal, where the customer links an account, and useConfirmUsBankAccountPayment() confirms the payment once the customer accepts the mandate. No Elements group is needed: Stripe's modal collects the account.
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, then click Link bank account. In the test-mode modal, pick Test (Non-OAuth), agree to the terms, choose the Success account and finish without saving to Link. ACH payments clear in a few business days, so the PaymentIntent ends in processing.
Select a Product
Source code
<script setup lang="ts">
import { ref, computed } from 'vue'
import { VueStripeProvider } from '@vue-stripe/vue-stripe'
import ProductSelector from './ProductSelector.vue'
import AchDebitPanel from './AchDebitPanel.vue'
import { useBackendApi, type Product } from '../../composables/useBackendApi'
import { useStripeConfig } from '../../composables/useStripeConfig'
import DocIcon from '../DocIcon.vue'
const { publishableKey } = useStripeConfig()
const { createAchIntent, formatPrice, loading } = useBackendApi()
// Step management: Product -> Bank account -> Complete
const step = ref<'select' | 'payment' | 'complete'>('select')
const selectedProduct = ref<Product | null>(null)
const clientSecret = ref<string | null>(null)
const amount = ref(0)
const paymentIntentId = ref<string | null>(null)
const paymentStatus = ref<string | null>(null)
const intentError = ref<string | null>(null)
// ACH Direct Debit charges in USD, so the demo charges the product's amount in USD.
const amountLabel = computed(() => formatPrice(amount.value, 'usd'))
async function onProductSelected(product: Product) {
selectedProduct.value = product
intentError.value = null
try {
const result = await createAchIntent({
amount: product.price.amount || 1000,
description: `Payment for ${product.name}`
})
clientSecret.value = result.clientSecret
amount.value = result.amount
step.value = 'payment'
} catch (err) {
intentError.value = err instanceof Error ? err.message : 'Failed to create payment intent'
}
}
function onSuccess(id: string, status: string) {
paymentIntentId.value = id
paymentStatus.value = status
step.value = 'complete'
}
function reset() {
step.value = 'select'
selectedProduct.value = null
clientSecret.value = null
amount.value = 0
paymentIntentId.value = null
paymentStatus.value = null
intentError.value = null
}
</script>
<template>
<div class="ach-debit-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>
<!-- 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 === 'payment', completed: step === 'complete' }"
>
<span class="step-dot">2</span>
<span class="step-label">Bank account</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 v-if="loading" class="loading-state">
<span class="spinner"></span> Creating ACH Direct Debit PaymentIntent...
</div>
<div v-if="intentError" class="error-box"><strong>Error:</strong> {{ intentError }}</div>
</div>
<!-- Step 2: Link the bank account, then confirm -->
<div v-else-if="step === 'payment'" class="step-content">
<div class="step-section">
<div class="step-header">
<h3>Pay by bank account</h3>
<button class="change-btn" @click="reset">Change Product</button>
</div>
<div class="product-summary">
<span>{{ selectedProduct?.name }}</span>
<span class="price">{{ amountLabel }}</span>
</div>
<VueStripeProvider :publishable-key="publishableKey">
<AchDebitPanel
:client-secret="clientSecret!"
:amount-label="amountLabel"
@success="onSuccess"
/>
</VueStripeProvider>
</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>Payment Submitted</h3>
<p>
ACH Direct Debit payments take a few business days. The PaymentIntent is
<strong>{{ paymentStatus }}</strong> until the debit clears.
</p>
<p v-if="paymentIntentId" class="payment-id">
Payment ID: <code>{{ paymentIntentId }}</code>
</p>
<button class="reset-btn" @click="reset">Start Over</button>
</div>
</div>
</template>
</div>
</template>
<style scoped>
.ach-debit-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);
}
.loading-state {
display: flex;
align-items: center;
justify-content: center;
gap: 0.5rem;
padding: 1rem;
color: #6b7280;
}
.error-box {
margin: 1rem 0;
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><script setup lang="ts">
// Rendered inside VueStripeProvider: both composables inject the Stripe instance.
// No VueStripeElements is needed, Stripe's Financial Connections modal collects the account.
import { computed, ref } from 'vue'
import { useFinancialConnections, useConfirmUsBankAccountPayment } from '@vue-stripe/vue-stripe'
const props = defineProps<{
clientSecret: string
amountLabel: string
}>()
const emit = defineEmits<{
success: [paymentIntentId: string, status: string]
}>()
const {
collectBankAccountForPayment,
loading: collecting,
error: collectError
} = useFinancialConnections()
const {
confirmUsBankAccountPayment,
loading: confirming,
error: confirmError
} = useConfirmUsBankAccountPayment()
const name = ref('Jenny Rosen')
const email = ref('jenny@example.com')
const linked = ref(false)
const cancelled = ref(false)
const canLink = computed(
() => name.value.trim() !== '' && email.value.includes('@') && !collecting.value
)
// Step 1: Stripe's modal links a bank account and attaches it to the PaymentIntent.
async function linkBankAccount() {
cancelled.value = false
const result = await collectBankAccountForPayment({
clientSecret: props.clientSecret,
params: {
payment_method_type: 'us_bank_account',
payment_method_data: { billing_details: { name: name.value, email: email.value } }
}
})
if (result.error) return
// Closing the modal resolves without an error, but the PaymentIntent still needs a payment method.
if (result.paymentIntent?.status === 'requires_payment_method') {
cancelled.value = true
return
}
linked.value = result.paymentIntent?.status === 'requires_confirmation'
}
// Step 2: the customer accepts the mandate; confirming records it and starts the debit.
async function confirm() {
const { paymentIntent } = await confirmUsBankAccountPayment(props.clientSecret)
if (paymentIntent) emit('success', paymentIntent.id, paymentIntent.status)
}
</script>
<template>
<div class="ach-panel">
<template v-if="!linked">
<label class="field">
<span>Account holder name</span>
<input v-model="name" type="text" autocomplete="name" data-test="ach-name" />
</label>
<label class="field">
<span>Email</span>
<input v-model="email" type="email" autocomplete="email" data-test="ach-email" />
</label>
<button
:class="['confirm-btn', { disabled: !canLink }]"
:disabled="!canLink"
data-test="ach-link"
@click="linkBankAccount"
>
{{ collecting ? 'Waiting for the bank modal...' : 'Link bank account' }}
</button>
<p v-if="cancelled" class="hint" data-test="ach-cancelled">
No account was linked. Open the modal again to choose a bank.
</p>
</template>
<template v-else>
<div class="linked-box" data-test="ach-linked">Bank account linked to the PaymentIntent.</div>
<p class="mandate">
By clicking Pay, you authorize Vue Stripe Demo to debit the bank account above for
{{ amountLabel }} through ACH Direct Debit, in accordance with these terms. You can revoke
this authorization by contacting us.
</p>
<button
:class="['confirm-btn', { disabled: confirming }]"
:disabled="confirming"
data-test="ach-confirm"
@click="confirm"
>
{{ confirming ? 'Processing...' : `Pay ${amountLabel}` }}
</button>
</template>
<div v-if="collectError || confirmError" class="error-box" data-test="ach-error">
<strong>Error:</strong> {{ collectError || confirmError }}
</div>
</div>
</template>
<style scoped>
.ach-panel {
display: flex;
flex-direction: column;
gap: 1rem;
}
.field {
display: flex;
flex-direction: column;
gap: 0.375rem;
}
.field > span {
font-size: 0.8125rem;
font-weight: 600;
color: var(--vp-c-text-2);
}
.field input {
padding: 0.625rem 0.75rem;
border: 1px solid var(--vp-c-divider);
border-radius: 6px;
background: var(--vp-c-bg);
color: var(--vp-c-text-1);
font-size: 0.9375rem;
}
.field input:focus {
outline: none;
border-color: var(--vp-c-brand-1);
}
.linked-box {
padding: 0.75rem 1rem;
background: var(--vp-c-green-soft);
border: 1px solid var(--vp-c-green-1);
border-radius: 6px;
font-size: 0.875rem;
}
.mandate,
.hint {
margin: 0;
font-size: 0.8125rem;
color: var(--vp-c-text-2);
}
.confirm-btn {
width: 100%;
padding: 0.875rem 1.5rem;
background: #635bff;
color: white;
border: none;
border-radius: 6px;
font-size: 1rem;
font-weight: 600;
cursor: pointer;
transition: opacity 0.2s;
}
.confirm-btn:hover:not(.disabled) {
opacity: 0.9;
}
.confirm-btn.disabled {
opacity: 0.6;
cursor: not-allowed;
}
.error-box {
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;
}
</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 asks the backend to create a PaymentIntent for
us_bank_accountin US dollars for the product's amount, and returns its client secret. - Only
VueStripeProviderwraps the payment step. There is no Elements group, because Stripe's Financial Connections modal collects the bank account. - The name and email fields are pre-filled with
Jenny Rosenandjenny@example.com. Link bank account callscollectBankAccountForPayment()fromuseFinancialConnections()withpayment_method_type: 'us_bank_account'and those billing details. The modal links an account and attaches it to the PaymentIntent, which moves torequires_confirmation. Closing the modal leaves the PaymentIntent inrequires_payment_method, and the demo says so. - The demo then shows the ACH mandate text with the amount. Pay calls
confirmUsBankAccountPayment(clientSecret)fromuseConfirmUsBankAccountPayment(), which records the mandate acceptance and starts the debit. - The demo shows the PaymentIntent ID and its status,
processing.
See also
How-to guide: Accept ACH Direct Debit. Reference: useFinancialConnections and useConfirmUsBankAccountPayment.
