Skip to content

useHandleNextAction ​

Invoke the next required action (e.g. 3DS authentication) on a PaymentIntent or SetupIntent without re-confirming it. Wraps stripe.handleNextAction().

Useful when you confirm an intent server-side and only need the client to complete required actions. Must be called within a <VueStripeProvider> or an app that installs createVueStripe().

Usage ​

vue
<script setup lang="ts">
import { ref } from 'vue'
import { useHandleNextAction } from '@vue-stripe/vue-stripe'

// clientSecret of a PaymentIntent your server confirmed, in status requires_action
const props = defineProps<{ clientSecret: string }>()
const { handleNextAction, loading, error } = useHandleNextAction()
const paid = ref(false)

const finish = async () => {
  const { paymentIntent } = await handleNextAction({ clientSecret: props.clientSecret })
  if (paymentIntent?.status === 'succeeded') paid.value = true
}
</script>

<template>
  <p v-if="paid">Payment received.</p>
  <template v-else>
    <button :disabled="loading" @click="finish">Complete payment</button>
    <p v-if="error">{{ error }}</p>
  </template>
</template>

Return Value ​

ts
interface UseHandleNextActionReturn {
  handleNextAction: (options: HandleNextActionOptions) => Promise<HandleNextActionResult>
  loading: Readonly<Ref<boolean>>
  error: Readonly<Ref<string | null>>
}

type HandleNextActionResult = PaymentIntentOrSetupIntentResult | VueStripeErrorResult
PropertyTypeDescription
handleNextAction(options: HandleNextActionOptions) => Promise<HandleNextActionResult>Runs the next action; resolves to Stripe's result ({ paymentIntent } / { setupIntent } or { error }).
loadingReadonly<Ref<boolean>>true while an action is in progress (until the last of overlapping calls settles).
errorReadonly<Ref<string | null>>The error message if the action failed.

When Stripe.js is not available (the plugin's load failed, for example; a call made while it loads waits for it), or the Stripe call throws, handleNextAction does not reject: it resolves to a VueStripeErrorResult, { error: { message } } (e.g. { error: { message: 'Stripe not initialized' } }), so one if (result.error) check covers every failure.

Options ​

HandleNextActionOptions is one of two shapes, matching Stripe's two handleNextAction overloads:

ts
type HandleNextActionOptions =
  | { clientSecret: string } // PaymentIntent / SetupIntent requiring an action
  | { hashedValue: string }  // shared payment token (Stripe.js 9.4+)
FieldTypeDescription
clientSecretstringClient secret of the PaymentIntent or SetupIntent requiring an action.
hashedValuestringHashed value of a shared payment token (agentic commerce, Stripe.js 9.4+).
ts
// Intent requiring an action
await handleNextAction({ clientSecret: 'pi_xxx_secret_xxx' })

// Shared payment token
await handleNextAction({ hashedValue: tokenHashedValue })

TypeScript ​

ts
import { useHandleNextAction } from '@vue-stripe/vue-stripe'
import type { HandleNextActionOptions, HandleNextActionResult } from '@vue-stripe/vue-stripe'

// useNextAction.ts: call useNextAction() in a component's setup
export function useNextAction() {
  const { handleNextAction } = useHandleNextAction()

  const run = async (options: HandleNextActionOptions): Promise<HandleNextActionResult> => {
    const result = await handleNextAction(options)
    if (result.error) console.error(result.error.message)
    return result
  }

  return { run }
}

See Also ​