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
<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
interface UseHandleNextActionReturn {
handleNextAction: (options: HandleNextActionOptions) => Promise<HandleNextActionResult>
loading: Readonly<Ref<boolean>>
error: Readonly<Ref<string | null>>
}
type HandleNextActionResult = PaymentIntentOrSetupIntentResult | VueStripeErrorResult| Property | Type | Description |
|---|---|---|
handleNextAction | (options: HandleNextActionOptions) => Promise<HandleNextActionResult> | Runs the next action; resolves to Stripe's result ({ paymentIntent } / { setupIntent } or { error }). |
loading | Readonly<Ref<boolean>> | true while an action is in progress (until the last of overlapping calls settles). |
error | Readonly<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:
type HandleNextActionOptions =
| { clientSecret: string } // PaymentIntent / SetupIntent requiring an action
| { hashedValue: string } // shared payment token (Stripe.js 9.4+)| Field | Type | Description |
|---|---|---|
clientSecret | string | Client secret of the PaymentIntent or SetupIntent requiring an action. |
hashedValue | string | Hashed value of a shared payment token (agentic commerce, Stripe.js 9.4+). |
// Intent requiring an action
await handleNextAction({ clientSecret: 'pi_xxx_secret_xxx' })
// Shared payment token
await handleNextAction({ hashedValue: tokenHashedValue })TypeScript
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
- useCreateConfirmationToken - Create the token your server confirms with
- Confirm payments on your server - Step-by-step guide
- Next actions - What a next action is
