From 0fbb81e4aab04f2b943bc005d156e402466bf8f7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Jos=C3=A9=20Ram=C3=ADrez?=
 <70615692+jjramirezn@users.noreply.github.com>
Date: Fri, 17 Jul 2026 02:15:04 -0300
Subject: [PATCH 1/4] feat(card): proof-of-address upload on stuck Rain
 applications
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The card status screens for requires-info/rejected only offered
"Contact support", even when the backend classified the application as
PoA-fixable (residence vs POI country mismatch, the digital-nomad case
that drives most manual card support).

When the rain rail carries the sumsub:proof_of_address next-action, the
status screen now renders a primary "Upload proof of address" CTA that
opens the Sumsub RFI flow via the self-heal machinery (provider RAIN on
/users/identity/resubmit — peanut-api-ts#1194 is the backend half). On
completion the rain overview refetches and the backend flips the rail
reason to "document received - being reviewed".

The self-heal flow gets its own SumsubKycModals surface — the existing
SumsubKycWrapper on this page is bound to card-apply tokens with their
own refresh/poll semantics and must not be multiplexed.
---
 src/app/(mobile-ui)/card/page.tsx             | 31 +++++++++-
 src/app/actions/sumsub.ts                     |  2 +-
 .../Card/ApplicationStatusScreen.tsx          | 18 +++++-
 .../ApplicationStatusScreen.test.tsx          | 39 ++++++++++++
 src/hooks/useSumsubKycFlow.ts                 | 59 ++++++++++---------
 5 files changed, 118 insertions(+), 31 deletions(-)

diff --git a/src/app/(mobile-ui)/card/page.tsx b/src/app/(mobile-ui)/card/page.tsx
index 17e3062aa2..27be3da591 100644
--- a/src/app/(mobile-ui)/card/page.tsx
+++ b/src/app/(mobile-ui)/card/page.tsx
@@ -21,6 +21,8 @@ import Loading from '@/components/Global/Loading'
 import { Button } from '@/components/0_Bruddle/Button'
 import PageContainer from '@/components/0_Bruddle/PageContainer'
 import { SumsubKycWrapper } from '@/components/Kyc/SumsubKycWrapper'
+import { SumsubKycModals } from '@/components/Kyc/SumsubKycModals'
+import { useMultiPhaseKycFlow } from '@/hooks/useMultiPhaseKycFlow'
 import { rainApi, type ApplyForCardResponse } from '@/services/rain'
 import { useGrantSessionKey } from '@/hooks/wallet/useGrantSessionKey'
 import { useCapabilities } from '@/hooks/useCapabilities'
@@ -69,7 +71,7 @@ const CardPage: FC = () => {
 
     const { overview, isLoading: overviewLoading, error: overviewError } = useRainCardOverview()
     const { serializeGrant } = useGrantSessionKey()
-    const { railsForProvider, isLoading: capabilitiesLoading } = useCapabilities()
+    const { railsForProvider, nextActionsForRail, isLoading: capabilitiesLoading } = useCapabilities()
     const { setIsSupportModalOpen } = useModalsContext()
     const onBack = useSafeBack('/home')
 
@@ -212,6 +214,30 @@ const CardPage: FC = () => {
         void queryClient.invalidateQueries({ queryKey: [RAIN_CARD_OVERVIEW_QUERY_KEY] })
     }, [queryClient])
 
+    // Self-heal Sumsub flow for the requires-info/rejected states (e.g. the
+    // proof-of-address upload). Separate surface from the card-application
+    // SumsubKycWrapper below — that one is driven by applyForCard tokens with
+    // its own refresh/poll semantics; multiplexing them would fight over the
+    // token. On completion the overview refetches so the screen advances.
+    const selfHealKycFlow = useMultiPhaseKycFlow({ onKycSuccess: invalidateOverview })
+
+    // The rain rail's self-serve proof-of-address action, when the backend
+    // classified the application as PoA-fixable (kind 'sumsub' + levelKey
+    // 'proof_of_address' — emitted for WRONG_ADDRESS-class denials). Absent →
+    // the status screens keep their contact-support-only shape.
+    const cardRail = railsForProvider('rain')[0]
+    const poaAction = cardRail
+        ? nextActionsForRail(cardRail.id).find(
+              (action) => action.kind === 'sumsub' && action.levelKey === 'proof_of_address'
+          )
+        : undefined
+    const onUploadProofOfAddress = poaAction
+        ? () => {
+              posthog.capture(ANALYTICS_EVENTS.CARD_SUMSUB_OPENED)
+              void selfHealKycFlow.handleSelfHealResubmit('RAIN')
+          }
+        : undefined
+
     // Routes a non-incomplete apply response to the right next screen. Shared
     // by the user-initiated apply path and the post-Sumsub poll, since both
     // need the same main-kyc-required / terms-required / default fan-out.
@@ -605,6 +631,7 @@ const CardPage: FC = () => {
                         variant="requires-info"
                         reasonMessage={cardRailReason}
                         onContactSupport={() => setIsSupportModalOpen(true)}
+                        onUploadProofOfAddress={onUploadProofOfAddress}
                         onPrev={onBack}
                     />
                 )
@@ -641,6 +668,7 @@ const CardPage: FC = () => {
                         variant="rejected"
                         reasonMessage={cardRailReason}
                         onContactSupport={() => setIsSupportModalOpen(true)}
+                        onUploadProofOfAddress={onUploadProofOfAddress}
                         onPrev={onBack}
                     />
                 )
@@ -657,6 +685,7 @@ const CardPage: FC = () => {
     return (
         <PageContainer>
             {renderState()}
+            <SumsubKycModals flow={selfHealKycFlow} />
             <SumsubKycWrapper
                 visible={sumsubToken !== null}
                 accessToken={sumsubToken}
diff --git a/src/app/actions/sumsub.ts b/src/app/actions/sumsub.ts
index 519e8f43ca..7b3e37e8e9 100644
--- a/src/app/actions/sumsub.ts
+++ b/src/app/actions/sumsub.ts
@@ -86,7 +86,7 @@ export const restartIdentityVerification = async (): Promise<{
 
 // initiate self-heal document resubmission for a provider-rejected user
 export const initiateSelfHealResubmission = async (
-    provider: 'BRIDGE' | 'MANTECA',
+    provider: 'BRIDGE' | 'MANTECA' | 'RAIN',
     // Optional — target a specific (e.g. future-dated advisory) Bridge requirement
     // by key. Omitted for the legacy blocking flow (current nextAction).
     requirementKey?: string
diff --git a/src/components/Card/ApplicationStatusScreen.tsx b/src/components/Card/ApplicationStatusScreen.tsx
index ced7d5061e..caa6148736 100644
--- a/src/components/Card/ApplicationStatusScreen.tsx
+++ b/src/components/Card/ApplicationStatusScreen.tsx
@@ -4,6 +4,7 @@ import Image from 'next/image'
 import { PeanutCrying } from '@/assets/mascot'
 import NavHeader from '@/components/Global/NavHeader'
 import Loading from '@/components/Global/Loading'
+import { Button } from '@/components/0_Bruddle/Button'
 
 type Variant = 'pending' | 'manual-review' | 'requires-info' | 'requires-support' | 'rejected'
 
@@ -14,6 +15,10 @@ interface Props {
      *  user sees what specifically is missing. Provider-neutral by contract. */
     reasonMessage?: string
     onContactSupport?: () => void
+    /** When the rail carries a self-serve proof-of-address action, this opens
+     *  the Sumsub upload flow — rendered as the primary CTA so users fix it
+     *  themselves instead of messaging support. */
+    onUploadProofOfAddress?: () => void
     onPrev?: () => void
 }
 
@@ -46,7 +51,13 @@ const COPY: Record<Variant, { title: string; body: string }> = {
 /** Variants where support is the only path forward — these render the CTA. */
 const SUPPORT_VARIANTS: ReadonlySet<Variant> = new Set(['requires-info', 'requires-support', 'rejected'])
 
-const ApplicationStatusScreen: FC<Props> = ({ variant, reasonMessage, onContactSupport, onPrev }) => {
+const ApplicationStatusScreen: FC<Props> = ({
+    variant,
+    reasonMessage,
+    onContactSupport,
+    onUploadProofOfAddress,
+    onPrev,
+}) => {
     const copy = COPY[variant]
     return (
         <div className="flex min-h-[inherit] flex-col gap-8">
@@ -69,6 +80,11 @@ const ApplicationStatusScreen: FC<Props> = ({ variant, reasonMessage, onContactS
                     {reasonMessage && <p className="text-grey-1">{reasonMessage}</p>}
                     <p className="text-grey-1">{copy.body}</p>
                 </div>
+                {SUPPORT_VARIANTS.has(variant) && onUploadProofOfAddress && (
+                    <Button variant="purple" shadowSize="4" className="w-full" onClick={onUploadProofOfAddress}>
+                        Upload proof of address
+                    </Button>
+                )}
                 {SUPPORT_VARIANTS.has(variant) && onContactSupport && (
                     <button type="button" onClick={onContactSupport} className="text-black underline">
                         Contact support
diff --git a/src/components/Card/__tests__/ApplicationStatusScreen.test.tsx b/src/components/Card/__tests__/ApplicationStatusScreen.test.tsx
index fd3f414ce2..5e772d2a13 100644
--- a/src/components/Card/__tests__/ApplicationStatusScreen.test.tsx
+++ b/src/components/Card/__tests__/ApplicationStatusScreen.test.tsx
@@ -57,3 +57,42 @@ describe('ApplicationStatusScreen — rejected', () => {
         expect(onContactSupport).toHaveBeenCalledTimes(1)
     })
 })
+
+describe('ApplicationStatusScreen — proof-of-address upload CTA', () => {
+    it('renders the upload CTA as primary when the rail carries a PoA action', () => {
+        const onUpload = jest.fn()
+        render(
+            <ApplicationStatusScreen
+                variant="requires-info"
+                reasonMessage="We need a valid proof of address document."
+                onContactSupport={jest.fn()}
+                onUploadProofOfAddress={onUpload}
+            />
+        )
+        fireEvent.click(screen.getByText('Upload proof of address'))
+        expect(onUpload).toHaveBeenCalledTimes(1)
+        // Contact support stays available as the fallback path.
+        expect(screen.getByText('Contact support')).toBeInTheDocument()
+    })
+
+    it('renders the upload CTA on the rejected variant too (denied + fixable PoA)', () => {
+        render(
+            <ApplicationStatusScreen
+                variant="rejected"
+                onContactSupport={jest.fn()}
+                onUploadProofOfAddress={jest.fn()}
+            />
+        )
+        expect(screen.getByText('Upload proof of address')).toBeInTheDocument()
+    })
+
+    it('omits the upload CTA when no PoA action exists', () => {
+        render(<ApplicationStatusScreen variant="requires-info" onContactSupport={jest.fn()} />)
+        expect(screen.queryByText('Upload proof of address')).not.toBeInTheDocument()
+    })
+
+    it('never renders the upload CTA on non-support variants', () => {
+        render(<ApplicationStatusScreen variant="pending" onUploadProofOfAddress={jest.fn()} />)
+        expect(screen.queryByText('Upload proof of address')).not.toBeInTheDocument()
+    })
+})
diff --git a/src/hooks/useSumsubKycFlow.ts b/src/hooks/useSumsubKycFlow.ts
index 4e30b56a21..88194f95c1 100644
--- a/src/hooks/useSumsubKycFlow.ts
+++ b/src/hooks/useSumsubKycFlow.ts
@@ -77,7 +77,7 @@ export const useSumsubKycFlow = ({ onKycSuccess, onManualClose, regionIntent }:
     // prevents stale websocket events or mount-time fetches from auto-closing the drawer.
     const userInitiatedRef = useRef(false)
     // tracks self-heal provider for token refresh — null when in regular KYC flow
-    const selfHealProviderRef = useRef<'BRIDGE' | 'MANTECA' | null>(null)
+    const selfHealProviderRef = useRef<'BRIDGE' | 'MANTECA' | 'RAIN' | null>(null)
 
     useEffect(() => {
         regionIntentRef.current = regionIntent
@@ -470,39 +470,42 @@ export const useSumsubKycFlow = ({ onKycSuccess, onManualClose, regionIntent }:
     // and opens the sumsub SDK with the action token. `requirementKey` targets a
     // specific (e.g. future-dated advisory) Bridge requirement; omitted for the
     // legacy blocking flow.
-    const handleSelfHealResubmit = useCallback(async (provider: 'BRIDGE' | 'MANTECA', requirementKey?: string) => {
-        setIsLoading(true)
-        setError(null)
-        userInitiatedRef.current = true
-        selfHealProviderRef.current = provider
+    const handleSelfHealResubmit = useCallback(
+        async (provider: 'BRIDGE' | 'MANTECA' | 'RAIN', requirementKey?: string) => {
+            setIsLoading(true)
+            setError(null)
+            userInitiatedRef.current = true
+            selfHealProviderRef.current = provider
 
-        try {
-            const response = await initiateSelfHealResubmission(provider, requirementKey)
+            try {
+                const response = await initiateSelfHealResubmission(provider, requirementKey)
 
-            if (response.error) {
-                userInitiatedRef.current = false
-                selfHealProviderRef.current = null
-                setError(response.error)
-                return
-            }
+                if (response.error) {
+                    userInitiatedRef.current = false
+                    selfHealProviderRef.current = null
+                    setError(response.error)
+                    return
+                }
 
-            if (response.data?.token) {
-                setAccessToken(response.data.token)
-                setShowWrapper(true)
-            } else {
+                if (response.data?.token) {
+                    setAccessToken(response.data.token)
+                    setShowWrapper(true)
+                } else {
+                    userInitiatedRef.current = false
+                    selfHealProviderRef.current = null
+                    setError('Could not initiate document resubmission. Please try again.')
+                }
+            } catch (e: unknown) {
                 userInitiatedRef.current = false
                 selfHealProviderRef.current = null
-                setError('Could not initiate document resubmission. Please try again.')
+                const message = e instanceof Error ? e.message : 'An unexpected error occurred'
+                setError(message)
+            } finally {
+                setIsLoading(false)
             }
-        } catch (e: unknown) {
-            userInitiatedRef.current = false
-            selfHealProviderRef.current = null
-            const message = e instanceof Error ? e.message : 'An unexpected error occurred'
-            setError(message)
-        } finally {
-            setIsLoading(false)
-        }
-    }, [])
+        },
+        []
+    )
 
     // Start a capability nextAction by key (POST /users/kyc/start-action) and
     // open the WebSDK with the returned token. Unlike handleInitiateKyc (which

From 880c28d3f878045949b574f99e29e0c344b2c57d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Jos=C3=A9=20Ram=C3=ADrez?=
 <70615692+jjramirezn@users.noreply.github.com>
Date: Fri, 17 Jul 2026 02:34:18 -0300
Subject: [PATCH 2/4] =?UTF-8?q?chore(card):=20review=20touch-ups=20?=
 =?UTF-8?q?=E2=80=94=20RAIN=5FDOCUMENT=20union,=20PoA=20analytics=20source?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Align SelfHealResubmissionResponse.requiredAction with the backend's
RAIN_DOCUMENT value, and tag the self-heal CARD_SUMSUB_OPENED capture
with source: poa-self-heal so it's distinguishable from card-apply.
---
 src/app/(mobile-ui)/card/page.tsx | 2 +-
 src/app/actions/sumsub.ts         | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/app/(mobile-ui)/card/page.tsx b/src/app/(mobile-ui)/card/page.tsx
index 27be3da591..cea060c609 100644
--- a/src/app/(mobile-ui)/card/page.tsx
+++ b/src/app/(mobile-ui)/card/page.tsx
@@ -233,7 +233,7 @@ const CardPage: FC = () => {
         : undefined
     const onUploadProofOfAddress = poaAction
         ? () => {
-              posthog.capture(ANALYTICS_EVENTS.CARD_SUMSUB_OPENED)
+              posthog.capture(ANALYTICS_EVENTS.CARD_SUMSUB_OPENED, { source: 'poa-self-heal' })
               void selfHealKycFlow.handleSelfHealResubmit('RAIN')
           }
         : undefined
diff --git a/src/app/actions/sumsub.ts b/src/app/actions/sumsub.ts
index 7b3e37e8e9..017bde0d66 100644
--- a/src/app/actions/sumsub.ts
+++ b/src/app/actions/sumsub.ts
@@ -48,7 +48,7 @@ export interface SelfHealResubmissionResponse {
     applicantId: string
     actionId: string
     externalActionId: string
-    requiredAction: 'REUPLOAD_ID' | 'REUPLOAD_ADDRESS_PROOF' | 'CONTACT_SUPPORT'
+    requiredAction: 'REUPLOAD_ID' | 'REUPLOAD_ADDRESS_PROOF' | 'CONTACT_SUPPORT' | 'RAIN_DOCUMENT'
     userMessage: string
     attempt: number
     maxAttempts: number

From c5e6503ecc7837537dc16ddc07fab12ab5e3641e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Jos=C3=A9=20Ram=C3=ADrez?=
 <70615692+jjramirezn@users.noreply.github.com>
Date: Fri, 17 Jul 2026 02:58:42 -0300
Subject: [PATCH 3/4] refactor(card): dedicated lightweight PoA upload flow,
 inline errors

Review found the useMultiPhaseKycFlow reuse wrong for this surface:
its post-approval phase machine is bank-onboarding shaped (mutating
status poll that can hang the 'verifying' modal indefinitely, Bridge
ToS fan-out on an unrelated rail, completeFlow re-rendering the same
requires-info screen so users re-upload and burn attempts), and
initiation errors were invisible - a dead primary CTA on a stuck-
application screen.

Replaced with a tiny dedicated flow: call the resubmit action directly,
drive a second SumsubKycWrapper with its own token state, render
initiation failures inline under the CTA, and flip an optimistic
'we received your document' banner on SDK completion until the backend
webhook stamps the rail. The useSumsubKycFlow union widening is
reverted - no longer needed.
---
 src/app/(mobile-ui)/card/page.tsx             | 75 ++++++++++++++-----
 .../Card/ApplicationStatusScreen.tsx          | 13 +++-
 .../ApplicationStatusScreen.test.tsx          | 14 ++++
 src/hooks/useSumsubKycFlow.ts                 | 59 +++++++--------
 4 files changed, 108 insertions(+), 53 deletions(-)

diff --git a/src/app/(mobile-ui)/card/page.tsx b/src/app/(mobile-ui)/card/page.tsx
index cea060c609..3b4d088ae5 100644
--- a/src/app/(mobile-ui)/card/page.tsx
+++ b/src/app/(mobile-ui)/card/page.tsx
@@ -21,8 +21,7 @@ import Loading from '@/components/Global/Loading'
 import { Button } from '@/components/0_Bruddle/Button'
 import PageContainer from '@/components/0_Bruddle/PageContainer'
 import { SumsubKycWrapper } from '@/components/Kyc/SumsubKycWrapper'
-import { SumsubKycModals } from '@/components/Kyc/SumsubKycModals'
-import { useMultiPhaseKycFlow } from '@/hooks/useMultiPhaseKycFlow'
+import { initiateSelfHealResubmission } from '@/app/actions/sumsub'
 import { rainApi, type ApplyForCardResponse } from '@/services/rain'
 import { useGrantSessionKey } from '@/hooks/wallet/useGrantSessionKey'
 import { useCapabilities } from '@/hooks/useCapabilities'
@@ -214,12 +213,19 @@ const CardPage: FC = () => {
         void queryClient.invalidateQueries({ queryKey: [RAIN_CARD_OVERVIEW_QUERY_KEY] })
     }, [queryClient])
 
-    // Self-heal Sumsub flow for the requires-info/rejected states (e.g. the
-    // proof-of-address upload). Separate surface from the card-application
-    // SumsubKycWrapper below — that one is driven by applyForCard tokens with
-    // its own refresh/poll semantics; multiplexing them would fight over the
-    // token. On completion the overview refetches so the screen advances.
-    const selfHealKycFlow = useMultiPhaseKycFlow({ onKycSuccess: invalidateOverview })
+    // Proof-of-address self-heal — a dedicated, deliberately tiny flow. The
+    // multi-phase KYC machinery (useMultiPhaseKycFlow) is bank-onboarding
+    // shaped: its post-approval phase machine polls a mutating endpoint, can
+    // fan out to Bridge ToS modals, and completes on rail semantics that never
+    // match the Rain PoA lifecycle. Here we only need: mint an action token →
+    // open the SDK → on submit, thank the user and refetch. Separate surface
+    // from the card-application SumsubKycWrapper below — that one is driven by
+    // applyForCard tokens with its own refresh/poll semantics.
+    const [poaToken, setPoaToken] = useState<string | null>(null)
+    const [poaError, setPoaError] = useState<string | null>(null)
+    // Optimistic "we got your document" until the backend webhook flips the
+    // rail reason to its own review-wait state (may lag the SDK by seconds).
+    const [poaSubmitted, setPoaSubmitted] = useState(false)
 
     // The rain rail's self-serve proof-of-address action, when the backend
     // classified the application as PoA-fixable (kind 'sumsub' + levelKey
@@ -231,12 +237,19 @@ const CardPage: FC = () => {
               (action) => action.kind === 'sumsub' && action.levelKey === 'proof_of_address'
           )
         : undefined
-    const onUploadProofOfAddress = poaAction
-        ? () => {
-              posthog.capture(ANALYTICS_EVENTS.CARD_SUMSUB_OPENED, { source: 'poa-self-heal' })
-              void selfHealKycFlow.handleSelfHealResubmit('RAIN')
-          }
-        : undefined
+    const startPoaUpload = useCallback(async () => {
+        posthog.capture(ANALYTICS_EVENTS.CARD_SUMSUB_OPENED, { source: 'poa-self-heal' })
+        setPoaError(null)
+        const response = await initiateSelfHealResubmission('RAIN')
+        if (response.error || !response.data?.token) {
+            // Surfaced inline on the status screen — a silent primary CTA on a
+            // stuck-application screen is worse than no CTA.
+            setPoaError(response.error ?? 'Could not start the upload. Please try again.')
+            return
+        }
+        setPoaToken(response.data.token)
+    }, [])
+    const onUploadProofOfAddress = poaAction && !poaSubmitted ? () => void startPoaUpload() : undefined
 
     // Routes a non-incomplete apply response to the right next screen. Shared
     // by the user-initiated apply path and the post-Sumsub poll, since both
@@ -625,13 +638,16 @@ const CardPage: FC = () => {
                         </div>
                     )
                 }
-                const cardRailReason = railsForProvider('rain')[0]?.reason?.userMessage
+                const cardRailReason = poaSubmitted
+                    ? 'We received your proof of address — it’s being reviewed.'
+                    : railsForProvider('rain')[0]?.reason?.userMessage
                 return (
                     <ApplicationStatusScreen
                         variant="requires-info"
                         reasonMessage={cardRailReason}
                         onContactSupport={() => setIsSupportModalOpen(true)}
                         onUploadProofOfAddress={onUploadProofOfAddress}
+                        uploadError={poaError ?? undefined}
                         onPrev={onBack}
                     />
                 )
@@ -660,15 +676,18 @@ const CardPage: FC = () => {
                 // (meaningless without its reason), the rejected screen is useful
                 // on its own (reassurance + support CTA), so show it now and let
                 // the reason fill in once capabilities resolve.
-                const cardRailReason = capabilitiesLoading
-                    ? undefined
-                    : railsForProvider('rain')[0]?.reason?.userMessage
+                const cardRailReason = poaSubmitted
+                    ? 'We received your proof of address — it’s being reviewed.'
+                    : capabilitiesLoading
+                      ? undefined
+                      : railsForProvider('rain')[0]?.reason?.userMessage
                 return (
                     <ApplicationStatusScreen
                         variant="rejected"
                         reasonMessage={cardRailReason}
                         onContactSupport={() => setIsSupportModalOpen(true)}
                         onUploadProofOfAddress={onUploadProofOfAddress}
+                        uploadError={poaError ?? undefined}
                         onPrev={onBack}
                     />
                 )
@@ -685,7 +704,25 @@ const CardPage: FC = () => {
     return (
         <PageContainer>
             {renderState()}
-            <SumsubKycModals flow={selfHealKycFlow} />
+            <SumsubKycWrapper
+                visible={poaToken !== null}
+                accessToken={poaToken}
+                onClose={() => setPoaToken(null)}
+                onComplete={() => {
+                    // Document submitted to Sumsub. Review + the backend webhook
+                    // stamp happen async — flip the optimistic banner and refetch
+                    // so the screen picks up the backend's wait state when ready.
+                    setPoaToken(null)
+                    setPoaSubmitted(true)
+                    invalidateOverview()
+                    void fetchUser()
+                }}
+                onRefreshToken={async () => {
+                    const response = await initiateSelfHealResubmission('RAIN')
+                    if (!response.data?.token) throw new Error(response.error ?? 'Failed to refresh token')
+                    return response.data.token
+                }}
+            />
             <SumsubKycWrapper
                 visible={sumsubToken !== null}
                 accessToken={sumsubToken}
diff --git a/src/components/Card/ApplicationStatusScreen.tsx b/src/components/Card/ApplicationStatusScreen.tsx
index caa6148736..78a5c758f9 100644
--- a/src/components/Card/ApplicationStatusScreen.tsx
+++ b/src/components/Card/ApplicationStatusScreen.tsx
@@ -19,6 +19,9 @@ interface Props {
      *  the Sumsub upload flow — rendered as the primary CTA so users fix it
      *  themselves instead of messaging support. */
     onUploadProofOfAddress?: () => void
+    /** Inline failure from starting the upload (a silent primary CTA on a
+     *  stuck-application screen reads as broken). */
+    uploadError?: string
     onPrev?: () => void
 }
 
@@ -56,6 +59,7 @@ const ApplicationStatusScreen: FC<Props> = ({
     reasonMessage,
     onContactSupport,
     onUploadProofOfAddress,
+    uploadError,
     onPrev,
 }) => {
     const copy = COPY[variant]
@@ -81,9 +85,12 @@ const ApplicationStatusScreen: FC<Props> = ({
                     <p className="text-grey-1">{copy.body}</p>
                 </div>
                 {SUPPORT_VARIANTS.has(variant) && onUploadProofOfAddress && (
-                    <Button variant="purple" shadowSize="4" className="w-full" onClick={onUploadProofOfAddress}>
-                        Upload proof of address
-                    </Button>
+                    <div className="flex w-full flex-col gap-2">
+                        <Button variant="purple" shadowSize="4" className="w-full" onClick={onUploadProofOfAddress}>
+                            Upload proof of address
+                        </Button>
+                        {uploadError && <p className="text-sm text-error">{uploadError}</p>}
+                    </div>
                 )}
                 {SUPPORT_VARIANTS.has(variant) && onContactSupport && (
                     <button type="button" onClick={onContactSupport} className="text-black underline">
diff --git a/src/components/Card/__tests__/ApplicationStatusScreen.test.tsx b/src/components/Card/__tests__/ApplicationStatusScreen.test.tsx
index 5e772d2a13..ba5149108a 100644
--- a/src/components/Card/__tests__/ApplicationStatusScreen.test.tsx
+++ b/src/components/Card/__tests__/ApplicationStatusScreen.test.tsx
@@ -96,3 +96,17 @@ describe('ApplicationStatusScreen — proof-of-address upload CTA', () => {
         expect(screen.queryByText('Upload proof of address')).not.toBeInTheDocument()
     })
 })
+
+describe('ApplicationStatusScreen — upload error', () => {
+    it('renders the inline error under the upload CTA', () => {
+        render(
+            <ApplicationStatusScreen
+                variant="requires-info"
+                onContactSupport={jest.fn()}
+                onUploadProofOfAddress={jest.fn()}
+                uploadError="Could not start the upload. Please try again."
+            />
+        )
+        expect(screen.getByText('Could not start the upload. Please try again.')).toBeInTheDocument()
+    })
+})
diff --git a/src/hooks/useSumsubKycFlow.ts b/src/hooks/useSumsubKycFlow.ts
index 88194f95c1..4e30b56a21 100644
--- a/src/hooks/useSumsubKycFlow.ts
+++ b/src/hooks/useSumsubKycFlow.ts
@@ -77,7 +77,7 @@ export const useSumsubKycFlow = ({ onKycSuccess, onManualClose, regionIntent }:
     // prevents stale websocket events or mount-time fetches from auto-closing the drawer.
     const userInitiatedRef = useRef(false)
     // tracks self-heal provider for token refresh — null when in regular KYC flow
-    const selfHealProviderRef = useRef<'BRIDGE' | 'MANTECA' | 'RAIN' | null>(null)
+    const selfHealProviderRef = useRef<'BRIDGE' | 'MANTECA' | null>(null)
 
     useEffect(() => {
         regionIntentRef.current = regionIntent
@@ -470,42 +470,39 @@ export const useSumsubKycFlow = ({ onKycSuccess, onManualClose, regionIntent }:
     // and opens the sumsub SDK with the action token. `requirementKey` targets a
     // specific (e.g. future-dated advisory) Bridge requirement; omitted for the
     // legacy blocking flow.
-    const handleSelfHealResubmit = useCallback(
-        async (provider: 'BRIDGE' | 'MANTECA' | 'RAIN', requirementKey?: string) => {
-            setIsLoading(true)
-            setError(null)
-            userInitiatedRef.current = true
-            selfHealProviderRef.current = provider
+    const handleSelfHealResubmit = useCallback(async (provider: 'BRIDGE' | 'MANTECA', requirementKey?: string) => {
+        setIsLoading(true)
+        setError(null)
+        userInitiatedRef.current = true
+        selfHealProviderRef.current = provider
 
-            try {
-                const response = await initiateSelfHealResubmission(provider, requirementKey)
+        try {
+            const response = await initiateSelfHealResubmission(provider, requirementKey)
 
-                if (response.error) {
-                    userInitiatedRef.current = false
-                    selfHealProviderRef.current = null
-                    setError(response.error)
-                    return
-                }
+            if (response.error) {
+                userInitiatedRef.current = false
+                selfHealProviderRef.current = null
+                setError(response.error)
+                return
+            }
 
-                if (response.data?.token) {
-                    setAccessToken(response.data.token)
-                    setShowWrapper(true)
-                } else {
-                    userInitiatedRef.current = false
-                    selfHealProviderRef.current = null
-                    setError('Could not initiate document resubmission. Please try again.')
-                }
-            } catch (e: unknown) {
+            if (response.data?.token) {
+                setAccessToken(response.data.token)
+                setShowWrapper(true)
+            } else {
                 userInitiatedRef.current = false
                 selfHealProviderRef.current = null
-                const message = e instanceof Error ? e.message : 'An unexpected error occurred'
-                setError(message)
-            } finally {
-                setIsLoading(false)
+                setError('Could not initiate document resubmission. Please try again.')
             }
-        },
-        []
-    )
+        } catch (e: unknown) {
+            userInitiatedRef.current = false
+            selfHealProviderRef.current = null
+            const message = e instanceof Error ? e.message : 'An unexpected error occurred'
+            setError(message)
+        } finally {
+            setIsLoading(false)
+        }
+    }, [])
 
     // Start a capability nextAction by key (POST /users/kyc/start-action) and
     // open the WebSDK with the returned token. Unlike handleInitiateKyc (which

From abcd7e77cd27af93ad7766f3ed6c49e02bd91647 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Jos=C3=A9=20Ram=C3=ADrez?=
 <70615692+jjramirezn@users.noreply.github.com>
Date: Fri, 17 Jul 2026 03:25:53 -0300
Subject: [PATCH 4/4] chore(card): PoA click-guard + optimistic-banner reset

Concurrent CTA clicks could mint two Sumsub actions (the backend id
collision path deliberately creates a suffixed fresh action); guard
with a ref. Reset poaSubmitted once the backend state takes over so a
re-offered upload isn't suppressed until remount.
---
 src/app/(mobile-ui)/card/page.tsx | 32 ++++++++++++++++++++++++-------
 1 file changed, 25 insertions(+), 7 deletions(-)

diff --git a/src/app/(mobile-ui)/card/page.tsx b/src/app/(mobile-ui)/card/page.tsx
index 3b4d088ae5..1e39da95af 100644
--- a/src/app/(mobile-ui)/card/page.tsx
+++ b/src/app/(mobile-ui)/card/page.tsx
@@ -237,20 +237,38 @@ const CardPage: FC = () => {
               (action) => action.kind === 'sumsub' && action.levelKey === 'proof_of_address'
           )
         : undefined
+    // Double-click guard: two concurrent initiations race the backend's
+    // create-action idempotency into minting two Sumsub actions (the id
+    // collision path deliberately mints a suffixed fresh action).
+    const poaStartingRef = useRef(false)
     const startPoaUpload = useCallback(async () => {
+        if (poaStartingRef.current) return
+        poaStartingRef.current = true
         posthog.capture(ANALYTICS_EVENTS.CARD_SUMSUB_OPENED, { source: 'poa-self-heal' })
         setPoaError(null)
-        const response = await initiateSelfHealResubmission('RAIN')
-        if (response.error || !response.data?.token) {
-            // Surfaced inline on the status screen — a silent primary CTA on a
-            // stuck-application screen is worse than no CTA.
-            setPoaError(response.error ?? 'Could not start the upload. Please try again.')
-            return
+        try {
+            const response = await initiateSelfHealResubmission('RAIN')
+            if (response.error || !response.data?.token) {
+                // Surfaced inline on the status screen — a silent primary CTA on
+                // a stuck-application screen is worse than no CTA.
+                setPoaError(response.error ?? 'Could not start the upload. Please try again.')
+                return
+            }
+            setPoaToken(response.data.token)
+        } finally {
+            poaStartingRef.current = false
         }
-        setPoaToken(response.data.token)
     }, [])
     const onUploadProofOfAddress = poaAction && !poaSubmitted ? () => void startPoaUpload() : undefined
 
+    // Once the backend's own state takes over (the rail's sumsub action gives
+    // way to the review-wait state, an approval, or a different ask), drop the
+    // optimistic banner so a later re-offered upload isn't suppressed until
+    // remount.
+    useEffect(() => {
+        if (poaSubmitted && !poaAction) setPoaSubmitted(false)
+    }, [poaSubmitted, poaAction])
+
     // Routes a non-incomplete apply response to the right next screen. Shared
     // by the user-initiated apply path and the post-Sumsub poll, since both
     // need the same main-kyc-required / terms-required / default fan-out.