diff --git a/src/locales/en/main.json b/src/locales/en/main.json
index b261d2b43b4..05f75d7fa99 100644
--- a/src/locales/en/main.json
+++ b/src/locales/en/main.json
@@ -3150,6 +3150,12 @@
"addNewPaymentMethod": "Add new payment method",
"alipay": "Alipay"
},
+ "declined": {
+ "title": "Payment declined",
+ "body": "Your card couldn't be charged. Try another card, or contact your bank if this looks wrong.",
+ "reasonLabel": "What your bank said",
+ "updatePaymentMethod": "Update payment method"
+ },
"success": {
"allSet": "You're all set",
"inviteEmailsPlaceholder": "Enter emails separated by commas",
diff --git a/src/platform/workspace/components/SubscriptionDeclinedWorkspace.test.ts b/src/platform/workspace/components/SubscriptionDeclinedWorkspace.test.ts
new file mode 100644
index 00000000000..13a6f68dc40
--- /dev/null
+++ b/src/platform/workspace/components/SubscriptionDeclinedWorkspace.test.ts
@@ -0,0 +1,49 @@
+import { render, screen } from '@testing-library/vue'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it } from 'vitest'
+import { createI18n } from 'vue-i18n'
+
+import enMessages from '@/locales/en/main.json'
+
+import SubscriptionDeclinedWorkspace from './SubscriptionDeclinedWorkspace.vue'
+
+const i18n = createI18n({
+ legacy: false,
+ locale: 'en',
+ messages: { en: enMessages }
+})
+
+function renderDeclined(declineReason: string | null = null) {
+ return render(SubscriptionDeclinedWorkspace, {
+ props: { declineReason },
+ global: { plugins: [i18n] }
+ })
+}
+
+describe('SubscriptionDeclinedWorkspace', () => {
+ it('shows the Stripe reason when the API provides one', () => {
+ renderDeclined('Insufficient funds')
+
+ expect(screen.getByText('What your bank said')).toBeInTheDocument()
+ expect(screen.getByText('Insufficient funds')).toBeInTheDocument()
+ })
+
+ it('omits the reason block entirely when there is none', () => {
+ renderDeclined(null)
+
+ expect(screen.queryByText('What your bank said')).toBeNull()
+ expect(screen.getByText('Payment declined')).toBeInTheDocument()
+ })
+
+ it('offers a retry rather than ending the flow', async () => {
+ const { emitted } = renderDeclined('Card declined')
+
+ await userEvent.click(
+ screen.getByRole('button', { name: 'Update payment method' })
+ )
+ expect(emitted().updatePayment).toBeTruthy()
+
+ await userEvent.click(screen.getByRole('button', { name: 'Back' }))
+ expect(emitted().back).toBeTruthy()
+ })
+})
diff --git a/src/platform/workspace/components/SubscriptionDeclinedWorkspace.vue b/src/platform/workspace/components/SubscriptionDeclinedWorkspace.vue
new file mode 100644
index 00000000000..c393d942058
--- /dev/null
+++ b/src/platform/workspace/components/SubscriptionDeclinedWorkspace.vue
@@ -0,0 +1,64 @@
+
+
+
+
+
+ {{ $t('subscription.declined.title') }}
+
+
+ {{ $t('subscription.declined.body') }}
+
+
+
+
+
+ {{ $t('subscription.declined.reasonLabel') }}
+
+ {{ declineReason }}
+
+
+
+
+
+
+
+
+
+
+
diff --git a/src/platform/workspace/components/SubscriptionRequiredDialogContentUnified.vue b/src/platform/workspace/components/SubscriptionRequiredDialogContentUnified.vue
index e3264704f70..5711e7eaf4d 100644
--- a/src/platform/workspace/components/SubscriptionRequiredDialogContentUnified.vue
+++ b/src/platform/workspace/components/SubscriptionRequiredDialogContentUnified.vue
@@ -12,21 +12,26 @@
// panel stays fixed; below xl the whole dialog scrolls as before.
isEmbeddedPaymentStep &&
'xl:h-[min(740px,90vh)] xl:gap-0 xl:overflow-hidden xl:rounded-2xl xl:p-0',
- (isEmbeddedSuccessStep || isEmbeddedConfirmStep || isVerifyingStep) &&
+ (isEmbeddedSuccessStep ||
+ isEmbeddedConfirmStep ||
+ isVerifyingStep ||
+ isDeclinedStep) &&
'h-[min(740px,85vh)] overflow-hidden rounded-2xl bg-base-background xl:h-[min(740px,90vh)] xl:w-[512px]',
(isEmbeddedPaymentStep ||
isEmbeddedSuccessStep ||
isEmbeddedConfirmStep ||
- isVerifyingStep) &&
+ isVerifyingStep ||
+ isDeclinedStep) &&
'motion-safe:xl:transition-[width] motion-safe:xl:duration-300 motion-safe:xl:ease-in-out',
// The w-fit shell hugs min-content on phones; give the embedded
// steps a real width floor below xl.
(isEmbeddedPaymentStep ||
isEmbeddedSuccessStep ||
isEmbeddedConfirmStep ||
- isVerifyingStep) &&
+ isVerifyingStep ||
+ isDeclinedStep) &&
'max-xl:w-[min(430px,92vw)]',
- isEmbeddedPaymentStep && 'max-xl:h-[85vh]'
+ isEmbeddedPaymentStep && 'max-xl:h-[min(740px,85vh)]'
)
"
>
@@ -64,7 +69,8 @@
!isEmbeddedPaymentStep &&
!isEmbeddedSuccessStep &&
!isEmbeddedConfirmStep &&
- !isVerifyingStep
+ !isVerifyingStep &&
+ !isDeclinedStep
"
class="flex flex-col items-center gap-3"
>
@@ -73,7 +79,13 @@
-
+
{{ $t('credits.topUp.insufficientTitle') }}
@@ -226,6 +238,13 @@
@cancel-payment="handleCancelPendingPayment"
/>
+
+
checkoutStep.value === 'verifying')
+const isDeclinedStep = computed(() => checkoutStep.value === 'declined')
+
+// The decline CTA returns to confirm and opens method collection, which is
+// dialog state rather than checkout state.
+function handleDeclinedUpdatePayment() {
+ handleDeclinedBack()
+ selectSavedPaymentMethod(null)
+}
onMounted(() => {
if (!initialCheckout) return
diff --git a/src/platform/workspace/composables/useSubscriptionCheckout.test.ts b/src/platform/workspace/composables/useSubscriptionCheckout.test.ts
index 3b2f351c9b1..19c58f21e05 100644
--- a/src/platform/workspace/composables/useSubscriptionCheckout.test.ts
+++ b/src/platform/workspace/composables/useSubscriptionCheckout.test.ts
@@ -163,6 +163,7 @@ const {
mockStartOperation,
mockRetryPaymentAuthentication,
mockGetOperation,
+ mockClearOperation,
mockCancelOperation,
mockSubscriptionActionOperation,
mockListSavedPaymentMethods,
@@ -194,6 +195,7 @@ const {
mockStartOperation: vi.fn(),
mockRetryPaymentAuthentication: vi.fn(),
mockGetOperation: vi.fn(),
+ mockClearOperation: vi.fn(),
mockCancelOperation: vi.fn(),
mockSubscriptionActionOperation: {
value: undefined as MockSubscriptionActionOperation | undefined
@@ -354,6 +356,7 @@ vi.mock('@/platform/workspace/stores/billingOperationStore', () => ({
retryPaymentAuthentication: mockRetryPaymentAuthentication,
getOperation: mockGetOperation,
cancelOperation: mockCancelOperation,
+ clearOperation: mockClearOperation,
get subscriptionActionOperation() {
return mockSubscriptionActionOperation.value
}
@@ -2640,12 +2643,32 @@ describe('useSubscriptionCheckout', () => {
return checkout
}
- it('returns to plan selection when the recovered charge fails', async () => {
+ it('reaches the declined step instead of returning to pricing', async () => {
const checkout = await reentryOn('failed', {
errorMessage: 'Insufficient funds'
})
+ expect(checkout.checkoutStep.value).toBe('declined')
+ })
+
+ it('backs out of an in-flow decline to the preserved preview', async () => {
+ const checkout = await setupWithApprovedPreview()
+
+ checkout.checkoutStep.value = 'declined'
+ checkout.handleDeclinedBack()
+
+ expect(checkout.checkoutStep.value).toBe('preview')
+ })
+
+ it('backs out of a recovered decline to plan selection, not a blank preview', async () => {
+ const checkout = await reentryOn('failed', {
+ errorMessage: 'Insufficient funds'
+ })
+
+ checkout.handleDeclinedBack()
+
expect(checkout.checkoutStep.value).toBe('pricing')
+ expect(checkout.checkoutDeclineReason.value).toBeNull()
})
it('closes on success when there is no plan selection to show', async () => {
diff --git a/src/platform/workspace/composables/useSubscriptionCheckout.ts b/src/platform/workspace/composables/useSubscriptionCheckout.ts
index d1ea53d7062..3cb3e63d4ad 100644
--- a/src/platform/workspace/composables/useSubscriptionCheckout.ts
+++ b/src/platform/workspace/composables/useSubscriptionCheckout.ts
@@ -39,7 +39,7 @@ import {
} from '@/platform/workspace/utils/pendingSubscriptionCheckout'
import { trackWorkspaceCheckoutStarted } from '@/platform/workspace/utils/workspaceCheckoutTelemetry'
-type CheckoutStep = 'pricing' | 'preview' | 'verifying' | 'success'
+type CheckoutStep = 'pricing' | 'preview' | 'verifying' | 'success' | 'declined'
export type CheckoutTierKey = Exclude
export type SubscriptionCheckoutSelection =
@@ -164,6 +164,7 @@ export function useSubscriptionCheckout(
? 'verifying'
: 'pricing'
)
+ const checkoutDeclineReason = ref(null)
const isCancelingPayment = ref(false)
const cancelUnavailable = ref(false)
const cancelUnreachable = ref(false)
@@ -928,6 +929,18 @@ export function useSubscriptionCheckout(
emit('close', true)
}
+ // Declined is not terminal: back returns to the confirm step with the quote
+ // and selection intact so the same charge can be retried. A decline reached
+ // on re-entry has no preserved quote to land on — plan selection is the only
+ // step that can host it.
+ function handleDeclinedBack() {
+ checkoutDeclineReason.value = null
+ const opId = activeCheckoutOperation.value?.opId
+ if (opId) billingOperationStore.clearOperation(opId)
+ activeCheckoutOperationId.value = null
+ checkoutStep.value = previewData.value ? 'preview' : 'pricing'
+ }
+
async function handleSubscription(
confirmReactivation = false,
confirmationToken?: string,
@@ -1435,10 +1448,9 @@ export function useSubscriptionCheckout(
return
}
if (status === 'failed') {
- // The declined outcome step arrives one PR up; until it does, the
- // store's failure toast carries the verdict and the dialog returns
- // to plan selection.
- checkoutStep.value = 'pricing'
+ checkoutDeclineReason.value =
+ activeCheckoutOperation.value?.errorMessage ?? null
+ checkoutStep.value = 'declined'
return
}
if (status === undefined) {
@@ -1642,6 +1654,8 @@ export function useSubscriptionCheckout(
return {
checkoutStep,
+ checkoutDeclineReason,
+ handleDeclinedBack,
isLoadingPreview,
loadingTier,
isSubscribing,