refactor(kyc): render the backend ResolvedRail verdict (step 4)

src/app/(mobile-ui)/qr-pay/__tests__/qr-pay-states.test.tsx

@@ -20,6 +20,7 @@
 // reason message even when the page never touches them.
 type TestRail = Pick<RailCapability, 'id' | 'provider' | 'status' | 'operations'> & {
     reason?: { userMessage: string | null }
+    resolved?: RailCapability['resolved']
 }
 type TestRestriction = { code: string; affectedRailIds: string[]; userMessage?: string | null }
 
@@ -49,7 +50,7 @@
     default: (props: any) => {
         // next/image uses 'fill' boolean; strip non-DOM props
         const { priority, layout, objectFit, fill, ...rest } = props
         return <img {...rest} />
     },
 }))
 
@@ -496,6 +497,7 @@
         canDo: (_op: string, o?: { provider?: string }) =>
             payEnabled && (o?.provider === undefined || o.provider === 'manteca'),
         railsForProvider: (provider: string) => rails.filter((r) => r.provider === provider),
+        nextActions: [],
         restrictionForRail: (railId: string) => restrictions.find((r) => r.affectedRailIds.includes(railId)),
     }
 }
@@ -699,6 +701,36 @@
         expect(screen.getByText('Contact support to continue.')).toBeInTheDocument()
     })
 
+    test('provide-email verdict maps to the unavailable modal, never the document-upload flow', () => {
+        // a fixable verdict whose only fix is adding an email must not open
+        // the Sumsub upload flow (this surface has no email form) — same
+        // mapping rule as deriveProviderRejection
+        mockUseCapabilities.mockReturnValue({
+            ...capabilitiesForGate('provider_rejection_fixable', { userMessage: 'Add your email to continue.' }),
+            railsForProvider: () => [
+                {
+                    id: MANTECA_RAIL_ID,
+                    provider: 'manteca',
+                    status: 'blocked',
+                    resolved: {
+                        status: 'fixable',
+                        blocking: {
+                            code: 'email_required',
+                            userMessage: 'Add your email to continue.',
+                            selfHealable: true,
+                            selfHealKind: 'provide-email',
+                        },
+                    },
+                } as TestRail,
+            ],
+        })
+
+        renderQrPay({ qrCode: 'mercadopago://pay?id=123', type: 'MERCADO_PAGO', t: '1' })
+
+        expect(screen.getByText('QR payments are not available')).toBeInTheDocument()
+        expect(screen.queryByText('Upload document')).not.toBeInTheDocument()
+    })
+
     test('Manteca fixable rejection shows updated-document modal', () => {
         setCapabilitiesGate('provider_rejection_fixable', { userMessage: 'Upload a clearer ID.' })
 

src/app/(mobile-ui)/qr-pay/page.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import { railUserMessage, railVerdict } from '@/utils/capability-gate'
 import { useSearchParams, useRouter } from 'next/navigation'
 import { useState, useCallback, useMemo, useEffect, useContext, useRef } from 'react'
 import { useSafeBack } from '@/hooks/useSafeBack'
@@ -165,7 +166,7 @@
     //   manteca 'pending' → IDENTITY_VERIFICATION_IN_PROGRESS.
     //   otherwise → REQUIRES_IDENTITY_VERIFICATION. While loading → LOADING.
     // userMessage ← the rejecting rail's reason.userMessage (was useProviderRejectionStatus).
-    const { canDo, railsForProvider, isKycApproved, isLoading: isLoadingCapabilities } = useCapabilities()
+    const { canDo, railsForProvider, nextActions, isKycApproved, isLoading: isLoadingCapabilities } = useCapabilities()
     const { user, fetchUser } = useAuth()
 
     // On public routes (qr-pay) auth still auto-fetches via React Query, but trigger a one-shot
@@ -192,42 +193,59 @@
         if (canDo('pay', { provider: 'manteca' })) {
             return { kycGateState: QrKycState.PROCEED_TO_PAY, qrKycUserMessage: null as string | null }
         }
-        const mantecaRails = railsForProvider('manteca')
-        const blockedRail = mantecaRails.find((rail) => rail.status === 'blocked')
-        if (blockedRail) {
-            // Blocked === blocked. The US-nationality refinement is now applied in
-            // the resolver itself (Sumsub-approved + US-restricted → status:enabled
-            // + operations.pay:enabled, caught by canDo above), so a `blocked`
-            // status here is a genuine block.
-            //
+        // Verdict-first via the shared railVerdict collapse (rail.resolved,
+        // BE-derived; legacy fallback for older/cached responses). The
+        // US-nationality refinement is applied in the resolver itself
+        // (Sumsub-approved + US-restricted → operations.pay enabled, caught by
+        // canDo above), so a blocked verdict is genuine.
+        const actionByKey = new Map(nextActions.map((action) => [action.key, action]))
+        const candidates = railsForProvider('manteca').map((rail) => ({
+            rail,
+            verdict: railVerdict(rail, actionByKey),
+        }))
+        // provide-email is NOT a document fix: routing it into the Sumsub
+        // upload flow dead-ends the user, and this surface has no email form —
+        // map it to the blocked modal (same rule as deriveProviderRejection).
+        const isProvideEmail = ({ verdict }: (typeof candidates)[number]) =>
+            verdict.blocking?.selfHealKind === 'provide-email'
+        const blocked = candidates.find(
+            (candidate) => candidate.verdict.status === 'blocked' || isProvideEmail(candidate)
+        )
+        if (blocked) {
             // Country-not-supported is self-fixable: user uploaded a non-AR/BR doc
             // and can verify again with a different one. Split out for the right CTA.
-            if (blockedRail.reason?.code === 'country_not_supported') {
+            // (selfHealKind is the verdict home; the reason-code check covers legacy
+            // responses — the code rides on blocking.code verbatim.)
+            if (
+                !isProvideEmail(blocked) &&
+                (blocked.verdict.blocking?.selfHealKind === 'restart-identity' ||
+                    blocked.verdict.blocking?.code === 'country_not_supported')
+            ) {
                 return {
                     kycGateState: QrKycState.PROVIDER_RESTART_IDENTITY,
-                    qrKycUserMessage: blockedRail.reason.userMessage ?? null,
+                    qrKycUserMessage: railUserMessage(blocked.rail),
                 }
             }
             return {
                 kycGateState: QrKycState.PROVIDER_REJECTION_BLOCKED,
-                qrKycUserMessage: blockedRail.reason?.userMessage ?? null,
+                qrKycUserMessage: railUserMessage(blocked.rail),
             }
         }
-        const fixableRail = mantecaRails.find((rail) => rail.status === 'requires-info')
-        if (fixableRail) {
+        const fixable = candidates.find((candidate) => candidate.verdict.status === 'fixable')
+        if (fixable) {
             return {
                 kycGateState: QrKycState.PROVIDER_REJECTION_FIXABLE,
-                qrKycUserMessage: fixableRail.reason?.userMessage ?? null,
+                qrKycUserMessage: railUserMessage(fixable.rail),
             }
         }
-        if (mantecaRails.some((rail) => rail.status === 'pending')) {
+        if (candidates.some(({ verdict }) => verdict.status === 'pending')) {
             return {
                 kycGateState: QrKycState.IDENTITY_VERIFICATION_IN_PROGRESS,
                 qrKycUserMessage: null as string | null,
             }
         }
         return { kycGateState: QrKycState.REQUIRES_IDENTITY_VERIFICATION, qrKycUserMessage: null as string | null }
-    }, [isLoadingCapabilities, canDo, railsForProvider, user, userFetchSettled])
+    }, [isLoadingCapabilities, canDo, railsForProvider, nextActions, user, userFetchSettled])
 
     const shouldBlockPay = kycGateState !== QrKycState.PROCEED_TO_PAY
 
@@ -250,7 +268,7 @@
         if (sumsubFlow.showWrapper || sumsubFlow.isModalOpen) {
             sumsubFlow.completeFlow()
         }
     }, [kycGateState, sumsubFlow.showWrapper, sumsubFlow.isModalOpen, sumsubFlow.completeFlow])
 
     const queryClient = useQueryClient()
     const [isShaking, setIsShaking] = useState(false)
@@ -361,7 +379,7 @@
         if (isSuccess || !!errorMessage) {
             setLoadingState('Idle')
         }
     }, [isSuccess, errorMessage])
 
     // First fetch for qrcode info — only after KYC gating allows proceeding
     useEffect(() => {
@@ -380,7 +398,7 @@
         }
 
         setIsFirstLoad(false)
     }, [timestamp, paymentProcessor, qrCode])
 
     // Get amount from payment lock (Manteca)
     useEffect(() => {
@@ -395,7 +413,7 @@
             setAmount(paymentLock.paymentAgainstAmount)
             setCurrencyAmount(paymentLock.paymentAssetAmount)
         }
     }, [paymentLock?.code, paymentProcessor])
 
     // Get currency object from payment lock (Manteca)
     useEffect(() => {
@@ -417,7 +435,7 @@
             }
         }
         getCurrencyObject().then(setCurrency)
     }, [paymentLock?.code, paymentProcessor])
 
     const isBlockingError = useMemo(() => {
         // The settling failure says "try again in a few seconds" — keep the Pay
@@ -439,7 +457,7 @@
             // For dynamic QR codes, backend provides the USD amount
             return paymentLock.paymentAgainstAmount
         }
     }, [paymentLock?.code, paymentLock?.paymentAgainstAmount, amount])
 
     // Live card-vs-local-rail markup, driven by Manteca's rate + (for ARS)
     // BCRA's official rate. Used by both the confirm-screen "Save vs card"

src/app/actions/types/users.types.ts

@@ -12,7 +12,6 @@ export interface InitiateKycResponse {
     kycLink: string
     tosLink?: string
     bridgeKycStatus: string
-    tosStatus?: string
     error?: string // will be present on rejections
     reasons?: Array<{
         developer_reason: string

src/components/Home/ActivationCTAs.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import { railUserMessage, railVerdict } from '@/utils/capability-gate'
 import { Button } from '@/components/0_Bruddle/Button'
 import { type ActivationStep } from '@/hooks/useActivationStatus'
 import { Icon, type IconName } from '@/components/Global/Icons/Icon'
@@ -79,7 +80,7 @@ const STEPS: Record<Exclude<ActivationStep, 'completed'>, StepConfig> = {
 export default function ActivationCTAs({ activationStep, onDismissCard }: ActivationCTAsProps) {
     const router = useRouter()
     const { setIsQRScannerOpen, openSupportWithMessage } = useModalsContext()
-    const { rails, channelOf, nextActionsForRail } = useCapabilities()
+    const { rails, channelOf, nextActions } = useCapabilities()
     const { user } = useAuth()
     // Suppress the "Unlock payments" verify CTA while identity is mid-flight
     // (Sumsub processing / action_required). The user already took the verify
@@ -103,14 +104,19 @@ export default function ActivationCTAs({ activationStep, onDismissCard }: Activa
             const channel = channelOf(rail)
             return channel === 'bank' || channel === 'qr-only'
         })
-        const fixableRail = rejectableRails.find((rail) => rail.status === 'requires-info')
-        // Email-blocked rails carry a self-serve provide-email action (same
-        // contract the capability gate reads) — prefer one over an earlier
-        // blocked rail with a terminal reason, since one email fixes them all.
-        const emailBlocked = rejectableRails.find(
-            (rail) => rail.status === 'blocked' && nextActionsForRail(rail.id).some((a) => a.kind === 'provide-email')
+        // Verdict-first via the shared railVerdict collapse (rail.resolved,
+        // BE-derived; legacy fallback for older/cached responses).
+        const actionByKey = new Map(nextActions.map((action) => [action.key, action]))
+        const isEmailFix = (rail: (typeof rejectableRails)[number]) =>
+            railVerdict(rail, actionByKey).blocking?.selfHealKind === 'provide-email'
+        const fixableRail = rejectableRails.find(
+            (rail) => railVerdict(rail, actionByKey).status === 'fixable' && !isEmailFix(rail)
         )
-        const blocked = emailBlocked ?? rejectableRails.find((rail) => rail.status === 'blocked')
+        // Email-blocked rails: prefer one over an earlier blocked rail with a
+        // terminal reason, since one email fixes them all.
+        const emailBlocked = rejectableRails.find(isEmailFix)
+        const blocked =
+            emailBlocked ?? rejectableRails.find((rail) => railVerdict(rail, actionByKey).status === 'blocked')
         return {
             hasFixableRejection: !!fixableRail,
             fixableProvider:
@@ -119,11 +125,14 @@ export default function ActivationCTAs({ activationStep, onDismissCard }: Activa
                     : null,
             hasBlockedRejection: !!blocked,
             // Same precedence the copy/onClick use: email-blocked → fixable → terminal.
-            primaryRejectionMessage: (emailBlocked ?? fixableRail ?? blocked)?.reason?.userMessage ?? null,
+            primaryRejectionMessage: (() => {
+                const surfaced = emailBlocked ?? fixableRail ?? blocked
+                return surfaced ? railUserMessage(surfaced) : null
+            })(),
             blockedRail: blocked,
             isEmailBlocked: !!emailBlocked,
         }
-    }, [rails, channelOf, nextActionsForRail])
+    }, [rails, channelOf, nextActions])
 
     const [showProvideEmail, setShowProvideEmail] = useState(false)
 

src/components/Home/__tests__/ActivationCTAs.test.tsx

@@ -30,6 +30,7 @@ jest.mock('@/hooks/useCapabilities', () => ({
         rails: mockRails,
         channelOf: (rail: { channel: string }) => rail.channel,
         nextActionsForRail: () => [],
+        nextActions: [],
     }),
 }))
 jest.mock('@/context/authContext', () => ({

src/interfaces/interfaces.ts

@@ -188,8 +188,6 @@ export interface User {
     email: string
     profile_picture: string | null
     username: string | null
-    tosStatus?: string
-    tosAcceptedAt?: string
     bridgeCustomerId: string | null
     fullName: string
     telegram: string | null