From d252d7f173b1e1b9b9cb0cecbf6edbf7683d52a0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Jos=C3=A9=20Ram=C3=ADrez?= <artjjrn@gmail.com>
Date: Fri, 19 Jun 2026 05:55:37 -0300
Subject: [PATCH 01/10] feat(card-details): render Rain dispute status in the
 receipt drawer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Companion to peanut-api-ts#1037 (Rain dispute webhook handling).

Plumb extraData.dispute through the history transformer into the
TransactionDetails.cardPayment block, render a "Disputed — <label>" row
under the existing decline / cancellation / pending notes, and append an
"Evidence requested" row when Rain has prompted the user for docs.

Pill override: while the dispute is pending or inReview, flip the status
pill to pending — a settled spend that's actively contested isn't really
COMPLETED from the user's POV. Terminal dispute states (accepted /
resolvedByMerchant / rejected / canceled) restore the underlying status.
Suppress the existing "Authorized, awaiting settlement or reversal"
sub-row when an active dispute is the reason for the pending pill — the
dispute row IS the status story there.
---
 .../provider-rows/CardPaymentRows.tsx         | 51 ++++++++++++++++++-
 .../__tests__/dispute-label.test.ts           | 21 ++++++++
 .../transactionTransformer.ts                 | 43 ++++++++++++++++
 src/utils/history.utils.ts                    | 15 ++++++
 4 files changed, 128 insertions(+), 2 deletions(-)
 create mode 100644 src/components/TransactionDetails/provider-rows/__tests__/dispute-label.test.ts

diff --git a/src/components/TransactionDetails/provider-rows/CardPaymentRows.tsx b/src/components/TransactionDetails/provider-rows/CardPaymentRows.tsx
index 552df0a35..e7f57ef28 100644
--- a/src/components/TransactionDetails/provider-rows/CardPaymentRows.tsx
+++ b/src/components/TransactionDetails/provider-rows/CardPaymentRows.tsx
@@ -3,7 +3,7 @@
 import Image from 'next/image'
 import { type ReactNode } from 'react'
 import { PaymentInfoRow } from '@/components/Payment/PaymentInfoRow'
-import { type TransactionDetails } from '@/components/TransactionDetails/transactionTransformer'
+import { type DisputeStatus, type TransactionDetails } from '@/components/TransactionDetails/transactionTransformer'
 import { friendlyDeclineReason } from '@/utils/cardDeclineReason'
 import { getFlagUrl } from '@/constants/countryCurrencyMapping'
 import { extractMerchantIso2 } from '@/components/TransactionDetails/transaction-details.utils'
@@ -27,6 +27,30 @@ function parseCents(value: string | null | undefined): number | null {
     return Number.isFinite(n) ? n : null
 }
 
+/**
+ * Friendly copy for the dispute status row. The drawer shows ONE row labeled
+ * "Dispute" with the status-mapped text. Keep terminal-state copy actionable:
+ * "Resolved by merchant refund" / "Accepted (refund issued)" both signal that
+ * money has been returned (or is being returned), which is the user's actual
+ * concern at that point.
+ */
+export function disputeStatusLabel(status: DisputeStatus): string {
+    switch (status) {
+        case 'pending':
+            return 'Disputed — Awaiting review'
+        case 'inReview':
+            return 'Disputed — In review'
+        case 'accepted':
+            return 'Disputed — Accepted (refund issued)'
+        case 'rejected':
+            return 'Disputed — Rejected'
+        case 'canceled':
+            return 'Disputed — Cancelled'
+        case 'resolvedByMerchant':
+            return 'Disputed — Resolved by merchant refund'
+    }
+}
+
 /**
  * Whether CardPaymentRows would render any visible sub-row for this
  * transaction. The row-config in the receipt uses this to gate the
@@ -65,6 +89,7 @@ export function hasCardPaymentRowsContent(transaction: TransactionDetails): bool
     if (card.cancellationReason === 'auth_reversed' || card.cancellationReason === 'auth_expired_uncaptured') {
         return true
     }
+    if (card.dispute) return true
     return false
 }
 
@@ -198,7 +223,11 @@ export function CardPaymentRows({
         card.cancellationReason === 'auto_closed' ||
         card.cancellationReason === 'auth_reversed' ||
         card.cancellationReason === 'auth_expired_uncaptured'
-    if (transaction.status === 'pending' && !card.isRefund && !hasCancellationNote) {
+    // Active disputes flip the pill to pending too (see transactionTransformer),
+    // but the dispute row IS the status — the spend already settled, so
+    // "Authorized, awaiting settlement" is a lie next to "Disputed — In review".
+    const hasActiveDispute = card.dispute?.status === 'pending' || card.dispute?.status === 'inReview'
+    if (transaction.status === 'pending' && !card.isRefund && !hasCancellationNote && !hasActiveDispute) {
         subRows.push({
             key: 'pendingNote',
             label: 'Status',
@@ -206,6 +235,24 @@ export function CardPaymentRows({
         })
     }
 
+    // Dispute lifecycle. One row for the status; an additional row when Rain
+    // has requested evidence so the user knows to upload it. Both render
+    // regardless of the spend's status — disputes outlive the spend lifecycle.
+    if (card.dispute) {
+        subRows.push({
+            key: 'disputeStatus',
+            label: 'Dispute',
+            value: disputeStatusLabel(card.dispute.status),
+        })
+        if (card.dispute.evidenceRequestedMessage) {
+            subRows.push({
+                key: 'disputeEvidenceRequest',
+                label: 'Evidence requested',
+                value: card.dispute.evidenceRequestedMessage,
+            })
+        }
+    }
+
     if (subRows.length === 0) return null
 
     return (
diff --git a/src/components/TransactionDetails/provider-rows/__tests__/dispute-label.test.ts b/src/components/TransactionDetails/provider-rows/__tests__/dispute-label.test.ts
new file mode 100644
index 000000000..46afb2519
--- /dev/null
+++ b/src/components/TransactionDetails/provider-rows/__tests__/dispute-label.test.ts
@@ -0,0 +1,21 @@
+// Locks in the Disputed-status row copy. Keep changes here in sync with the
+// BE's dispute event handler in src/ledger/rain-mapper.ts so the FE label
+// always covers every status string the BE may write.
+
+import { disputeStatusLabel } from '../CardPaymentRows'
+import { type DisputeStatus } from '@/components/TransactionDetails/transactionTransformer'
+
+const CASES: Array<[DisputeStatus, string]> = [
+    ['pending', 'Disputed — Awaiting review'],
+    ['inReview', 'Disputed — In review'],
+    ['accepted', 'Disputed — Accepted (refund issued)'],
+    ['rejected', 'Disputed — Rejected'],
+    ['canceled', 'Disputed — Cancelled'],
+    ['resolvedByMerchant', 'Disputed — Resolved by merchant refund'],
+]
+
+describe('disputeStatusLabel', () => {
+    test.each(CASES)('%s → %s', (status: DisputeStatus, label: string) => {
+        expect(disputeStatusLabel(status)).toBe(label)
+    })
+})
diff --git a/src/components/TransactionDetails/transactionTransformer.ts b/src/components/TransactionDetails/transactionTransformer.ts
index b93e28a91..c528675b6 100644
--- a/src/components/TransactionDetails/transactionTransformer.ts
+++ b/src/components/TransactionDetails/transactionTransformer.ts
@@ -18,6 +18,9 @@ import { PEANUT_WALLET_CHAIN } from '@/constants/zerodev.consts'
 import { type HistoryEntryPerkReward, type ChargeEntry } from '@/services/services.types'
 import { dispatchStrategy, isIntentKind, type IntentKind } from './strategies/registry'
 
+/** Rain dispute lifecycle status values. Source: Rain dispute.* webhooks. */
+export type DisputeStatus = 'pending' | 'inReview' | 'accepted' | 'rejected' | 'canceled' | 'resolvedByMerchant'
+
 // Mirror of peanut-api-ts `enum TransactionProvider`. Receipts that branch
 // on provider (e.g. Manteca-specific deposit-info row) use this typed
 // value via `extraDataForDrawer.provider` for positive identity rather
@@ -374,6 +377,17 @@ export interface TransactionDetails {
             parentRainTxId: string | null
             rainTransactionId: string | null
             isRefund: boolean
+            /** Populated when Rain has fired any dispute.* webhook for this
+             *  spend. Status drives the drawer's "Disputed — <label>" badge;
+             *  evidenceRequestedMessage prompts the user to upload docs. */
+            dispute: {
+                status: DisputeStatus
+                type: string | null
+                resolvedAt: string | null
+                textEvidence: string | null
+                evidenceRequestedMessage: string | null
+                chargebackRainTxId: string | null
+            } | null
         }
     }
     sourceView?: 'status' | 'history'
@@ -459,6 +473,19 @@ export function mapTransactionDataForDrawer(entry: HistoryEntry): MappedTransact
     // map raw entry.status via the shared helper.
     if (!strategyOverrodeUiStatus) uiStatus = mapEntryStatusToUiStatus(entry, direction)
 
+    // Active dispute trumps the underlying spend's status — a card spend
+    // that's been contested isn't really "completed" from the user's POV,
+    // even though Rain settled it. Flip the pill to `pending` while the
+    // dispute is open. Terminal dispute states (accepted / resolvedByMerchant
+    // / rejected / canceled) restore the underlying status: the chargeback
+    // for accepted disputes arrives as a separate credit transaction; the
+    // others left the original spend standing. Status discrimination beyond
+    // the pill lives on the "Disputed — <label>" sub-row.
+    const disputeStatus = (entry.extraData?.dispute as { status?: string } | null | undefined)?.status
+    if (disputeStatus === 'pending' || disputeStatus === 'inReview') {
+        uiStatus = 'pending'
+    }
+
     // parse the amount from the usdamount string in extradata
     const amount = entry.extraData?.usdAmount
         ? parseFloat(String(entry.extraData.usdAmount).replace(/[^\d.-]/g, ''))
@@ -576,6 +603,22 @@ export function mapTransactionDataForDrawer(entry: HistoryEntry): MappedTransact
                           parentRainTxId: entry.extraData?.parentRainTxId as string | null,
                           rainTransactionId: entry.extraData?.rainTransactionId as string | null,
                           isRefund: !!entry.extraData?.parentRainTxId,
+                          // Dispute lifecycle — null when Rain hasn't fired
+                          // any dispute.* webhook for this spend.
+                          dispute: (() => {
+                              const d = entry.extraData?.dispute as Record<string, unknown> | null | undefined
+                              if (!d || typeof d !== 'object') return null
+                              const status = d.status as DisputeStatus | undefined
+                              if (!status) return null
+                              return {
+                                  status,
+                                  type: (d.type as string | undefined) ?? null,
+                                  resolvedAt: (d.resolvedAt as string | undefined) ?? null,
+                                  textEvidence: (d.textEvidence as string | undefined) ?? null,
+                                  evidenceRequestedMessage: (d.evidenceRequestedMessage as string | undefined) ?? null,
+                                  chargebackRainTxId: (d.chargebackRainTxId as string | undefined) ?? null,
+                              }
+                          })(),
                       }
                     : undefined,
             perkReward: entry.extraData?.perkReward as HistoryEntryPerkReward | undefined,
diff --git a/src/utils/history.utils.ts b/src/utils/history.utils.ts
index ebcc5a485..3edeca5cf 100644
--- a/src/utils/history.utils.ts
+++ b/src/utils/history.utils.ts
@@ -137,6 +137,21 @@ export interface HistoryEntryExtraData {
     merchantLogo?: string | null
     merchantId?: string | null
 
+    // Dispute lifecycle. Set when Rain has fired any dispute.* webhook for
+    // the spend. Transformer narrows into TransactionDetails.cardPayment.dispute.
+    dispute?: {
+        rainDisputeId?: string
+        status?: 'pending' | 'inReview' | 'accepted' | 'rejected' | 'canceled' | 'resolvedByMerchant'
+        type?: string
+        createdAt?: string
+        resolvedAt?: string | null
+        textEvidence?: string | null
+        evidenceRequestedMessage?: string | null
+        evidenceRequestedAt?: string | null
+        chargebackRainTxId?: string | null
+        chargebackCreatedAt?: string | null
+    } | null
+
     // Perk reward + claim metadata. Shapes match
     // TransactionDetails.extraDataForDrawer.perk* — kept loose here to
     // avoid a cross-import; transformer narrows.

From 0babb57df3bea449ab6f28b6b492810010d51f72 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Jos=C3=A9=20Ram=C3=ADrez?= <artjjrn@gmail.com>
Date: Fri, 19 Jun 2026 06:10:00 -0300
Subject: [PATCH 02/10] fix(card-details): nonBlank evidence text + runtime
 guard dispute status (CR)

---
 .../provider-rows/CardPaymentRows.tsx         |  8 +++++--
 .../transactionTransformer.ts                 | 21 ++++++++++++++++---
 2 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/src/components/TransactionDetails/provider-rows/CardPaymentRows.tsx b/src/components/TransactionDetails/provider-rows/CardPaymentRows.tsx
index e7f57ef28..805985bab 100644
--- a/src/components/TransactionDetails/provider-rows/CardPaymentRows.tsx
+++ b/src/components/TransactionDetails/provider-rows/CardPaymentRows.tsx
@@ -244,11 +244,15 @@ export function CardPaymentRows({
             label: 'Dispute',
             value: disputeStatusLabel(card.dispute.status),
         })
-        if (card.dispute.evidenceRequestedMessage) {
+        // Rain prompt text is free-form prose; the same nonBlank gate the
+        // decline-reason row uses keeps whitespace-only payloads from
+        // rendering an empty "Evidence requested" row.
+        const evidenceMessage = nonBlank(card.dispute.evidenceRequestedMessage)
+        if (evidenceMessage) {
             subRows.push({
                 key: 'disputeEvidenceRequest',
                 label: 'Evidence requested',
-                value: card.dispute.evidenceRequestedMessage,
+                value: evidenceMessage,
             })
         }
     }
diff --git a/src/components/TransactionDetails/transactionTransformer.ts b/src/components/TransactionDetails/transactionTransformer.ts
index c528675b6..4a33340be 100644
--- a/src/components/TransactionDetails/transactionTransformer.ts
+++ b/src/components/TransactionDetails/transactionTransformer.ts
@@ -21,6 +21,19 @@ import { dispatchStrategy, isIntentKind, type IntentKind } from './strategies/re
 /** Rain dispute lifecycle status values. Source: Rain dispute.* webhooks. */
 export type DisputeStatus = 'pending' | 'inReview' | 'accepted' | 'rejected' | 'canceled' | 'resolvedByMerchant'
 
+const DISPUTE_STATUSES: ReadonlySet<string> = new Set([
+    'pending',
+    'inReview',
+    'accepted',
+    'rejected',
+    'canceled',
+    'resolvedByMerchant',
+])
+
+function isDisputeStatus(value: unknown): value is DisputeStatus {
+    return typeof value === 'string' && DISPUTE_STATUSES.has(value)
+}
+
 // Mirror of peanut-api-ts `enum TransactionProvider`. Receipts that branch
 // on provider (e.g. Manteca-specific deposit-info row) use this typed
 // value via `extraDataForDrawer.provider` for positive identity rather
@@ -608,10 +621,12 @@ export function mapTransactionDataForDrawer(entry: HistoryEntry): MappedTransact
                           dispute: (() => {
                               const d = entry.extraData?.dispute as Record<string, unknown> | null | undefined
                               if (!d || typeof d !== 'object') return null
-                              const status = d.status as DisputeStatus | undefined
-                              if (!status) return null
+                              // Type-guard d.status — any non-DisputeStatus string from
+                              // the wire (sandbox drift, schema bump) should drop the
+                              // whole block rather than leak through.
+                              if (!isDisputeStatus(d.status)) return null
                               return {
-                                  status,
+                                  status: d.status,
                                   type: (d.type as string | undefined) ?? null,
                                   resolvedAt: (d.resolvedAt as string | undefined) ?? null,
                                   textEvidence: (d.textEvidence as string | undefined) ?? null,

From 3af8fd64960e853ed435531dfc227bd3ac206a20 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Jos=C3=A9=20Ram=C3=ADrez?= <artjjrn@gmail.com>
Date: Fri, 19 Jun 2026 16:20:47 -0300
Subject: [PATCH 03/10] fix(card): prioritize card CTA for eligible users over
 region-picker KYC
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Card-eligible users (skip badge or admin grant — both collapse into
cardInfo.hasCardAccess on the BE) were funneled to the region picker first:
the home activation funnel only surfaced the card step after KYC + funding,
and the carousel KYC prompt always pointed at /profile/identity-verification.

For EU/NA users that picker maps the region intent to bridge-requirements and
auto-enrolls Bridge bank rails, whose DB checks fail on many EU addresses —
surfacing as a "blocked by Bridge / proof of address" detour for people who
only ever wanted a card.

Surface the card step first whenever the user is eligible and cardless,
routing them to /card (KYC runs on rain-requirements — no regionIntent, no
Bridge rails), and stop showing the region-picker carousel CTA to eligible
users.
---
 src/hooks/useActivationStatus.ts  | 29 ++++++++++++++++++++---------
 src/hooks/useHomeCarouselCTAs.tsx |  8 +++++++-
 2 files changed, 27 insertions(+), 10 deletions(-)

diff --git a/src/hooks/useActivationStatus.ts b/src/hooks/useActivationStatus.ts
index 49d5de06a..b89b3458b 100644
--- a/src/hooks/useActivationStatus.ts
+++ b/src/hooks/useActivationStatus.ts
@@ -100,15 +100,26 @@ export function useActivationStatus(): ActivationStatus {
             }
         }
 
-        // Insert the card step between `deposit` and `outbound`: user has
-        // funded but hasn't taken the card yet. Skipped if they can't access
-        // the card flow, already have a card, or explicitly dismissed.
-        if (activationStep === 'outbound') {
-            const hasCardAccess = cardInfo?.hasCardAccess ?? false
-            const hasCard = !!findActiveCard(overview)
-            if (hasCardAccess && !hasCard && !cardDismissed) {
-                activationStep = 'card'
-            }
+        // Card takes priority for eligible users. An eligible user is one who
+        // holds a skip badge (e.g. WAITLIST_SKIP) or an explicit admin grant —
+        // both collapse into `cardInfo.hasCardAccess` on the BE, so gating here
+        // IS gating on the badge. If they don't yet hold a card and haven't
+        // dismissed the nudge, steer them straight to the card step (→ /card),
+        // overriding verify/deposit/outbound.
+        //
+        // Why this beats the old "insert between deposit and outbound" rule:
+        // the /card flow runs KYC on the `rain-requirements` Sumsub level,
+        // which does NOT send a regionIntent and does NOT enroll Bridge bank
+        // rails. The verify step instead routes to the region picker, where an
+        // EU/NA user gets `bridge-requirements` + auto-enrolled Bridge rails —
+        // the source of the "blocked by Bridge / proof of address" detours for
+        // users who only ever wanted a card. Surfacing card first keeps them
+        // off that path. Also fires for already-activated users who simply
+        // never took the card (the funnel would otherwise be `completed`).
+        const hasCardAccess = cardInfo?.hasCardAccess ?? false
+        const hasCard = !!findActiveCard(overview)
+        if (hasCardAccess && !hasCard && !cardDismissed) {
+            activationStep = 'card'
         }
 
         return { isActivated, activatedAt, activationStep }
diff --git a/src/hooks/useHomeCarouselCTAs.tsx b/src/hooks/useHomeCarouselCTAs.tsx
index e3ab5fc72..ee587386e 100644
--- a/src/hooks/useHomeCarouselCTAs.tsx
+++ b/src/hooks/useHomeCarouselCTAs.tsx
@@ -295,7 +295,13 @@ export const useHomeCarouselCTAs = () => {
             })
         }
 
-        if (!hasKycApproval && !isInFlight) {
+        // Don't push card-eligible users (skip badge / admin grant) to the
+        // region picker. This CTA routes to /profile/identity-verification,
+        // where EU/NA users get `bridge-requirements` + Bridge bank rails — the
+        // detour we steer eligible users away from (they go to /card instead,
+        // which KYCs on `rain-requirements`). `=== false` so we suppress while
+        // card-info is still loading too, mirroring the card-pioneer gate above.
+        if (!hasKycApproval && !isInFlight && hasCardAccessGranted === false) {
             _carouselCTAs.push({
                 id: 'kyc-prompt',
                 title: (

From 78534396be10c6cb3017565efd3b82404952b287 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Jos=C3=A9=20Ram=C3=ADrez?= <artjjrn@gmail.com>
Date: Fri, 19 Jun 2026 17:19:23 -0300
Subject: [PATCH 04/10] fix(card): redirect eligible-no-card users from region
 picker to /card
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extends the card-priority behavior to the region picker. When a user has
card access (skip badge / admin grant -> cardInfo.hasCardAccess) but no
active card, handleStartKyc now sends them to /card — whose KYC runs on the
rain-requirements Sumsub level (no regionIntent, no Bridge/Manteca rail
enrollment) — instead of starting region KYC, regardless of which region
they selected. Card-holders fall through and can still unlock bank regions.
---
 .../Profile/views/UnlockedRegions.view.tsx    | 24 ++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/src/components/Profile/views/UnlockedRegions.view.tsx b/src/components/Profile/views/UnlockedRegions.view.tsx
index 092056610..ace056e11 100644
--- a/src/components/Profile/views/UnlockedRegions.view.tsx
+++ b/src/components/Profile/views/UnlockedRegions.view.tsx
@@ -21,6 +21,10 @@ import Image from 'next/image'
 import { useSafeBack } from '@/hooks/useSafeBack'
 import { useState, useCallback, useRef, useMemo } from 'react'
 import { type KYCRegionIntent } from '@/app/actions/types/sumsub.types'
+import { useRouter } from 'next/navigation'
+import { useCardInfo } from '@/hooks/useCardInfo'
+import { useRainCardOverview } from '@/hooks/useRainCardOverview'
+import { findActiveCard } from '@/components/Card/cardState.utils'
 
 type ModalVariant = 'start' | 'processing' | 'action_required' | 'rejected'
 
@@ -59,6 +63,14 @@ function getModalVariant(rail: RailCapability | undefined, hasSumsubAction: bool
 
 const UnlockedRegions = () => {
     const onBack = useSafeBack('/profile', { replace: true })
+    const router = useRouter()
+    // Card-priority guard: an eligible user (skip badge / admin grant →
+    // hasCardAccess) without an active card is steered to /card from the region
+    // picker (see handleStartKyc), regardless of region. `hasActiveCard` excludes
+    // users who already hold a card so they can still unlock bank regions here.
+    const { hasCardAccess } = useCardInfo()
+    const { overview } = useRainCardOverview()
+    const hasActiveCard = useMemo(() => !!findActiveCard(overview), [overview])
     const { rails, isKycApproved, railsForProvider, nextActionsForRail } = useCapabilities()
     // MIGRATION-REVIEW: unlockedRegions/lockedRegions previously came from
     // `useIdentityVerification` (raw rails + Sumsub flags). Now derived from the
@@ -152,6 +164,16 @@ const UnlockedRegions = () => {
     }, [])
 
     const handleStartKyc = useCallback(async () => {
+        // Card takes priority for eligible users: if the user has card access but
+        // no active card yet, send them to /card (KYC on rain-requirements — no
+        // regionIntent, no Bridge/Manteca rail enrollment) instead of starting
+        // region KYC, for ANY region they picked. Card-holders fall through and
+        // can still unlock bank regions here.
+        if (hasCardAccess === true && !hasActiveCard) {
+            setSelectedRegion(null)
+            router.push('/card')
+            return
+        }
         const intent = selectedRegion ? getRegionIntent(selectedRegion.path) : undefined
         if (intent) setActiveRegionIntent(intent)
         setErrorAcknowledged(false)
@@ -166,7 +188,7 @@ const UnlockedRegions = () => {
         // Fresh-KYC safe: the BE's cross-region branches all require an
         // APPROVED verification, so for first-time users the flag is a no-op.
         await flow.handleInitiateKyc(intent, undefined, true)
-    }, [flow.handleInitiateKyc, selectedRegion])
+    }, [flow.handleInitiateKyc, selectedRegion, hasCardAccess, hasActiveCard, router])
 
     // re-submission: skip StartVerificationView since user already consented
     const handleResubmitKyc = useCallback(async () => {

From d3fb0fa30808643b7cdc441534bb48a13eee4d62 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Jos=C3=A9=20Ram=C3=ADrez?= <artjjrn@gmail.com>
Date: Fri, 19 Jun 2026 17:26:08 -0300
Subject: [PATCH 05/10] fix(card): keep hasActiveCard tri-state before
 region-picker redirect

Address CodeRabbit (Major): while useRainCardOverview is still loading,
treating `overview` as "no active card" could bounce a card-holder to /card
before it resolves. Make hasActiveCard tri-state (undefined while loading)
and only redirect on an explicit `false`.
---
 src/components/Profile/views/UnlockedRegions.view.tsx | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/components/Profile/views/UnlockedRegions.view.tsx b/src/components/Profile/views/UnlockedRegions.view.tsx
index ace056e11..7660728c5 100644
--- a/src/components/Profile/views/UnlockedRegions.view.tsx
+++ b/src/components/Profile/views/UnlockedRegions.view.tsx
@@ -70,7 +70,12 @@ const UnlockedRegions = () => {
     // users who already hold a card so they can still unlock bank regions here.
     const { hasCardAccess } = useCardInfo()
     const { overview } = useRainCardOverview()
-    const hasActiveCard = useMemo(() => !!findActiveCard(overview), [overview])
+    // Tri-state: undefined while the overview is still loading, so a card-holder
+    // isn't briefly treated as "no card" and bounced to /card before it resolves.
+    const hasActiveCard = useMemo<boolean | undefined>(() => {
+        if (!overview) return undefined
+        return !!findActiveCard(overview)
+    }, [overview])
     const { rails, isKycApproved, railsForProvider, nextActionsForRail } = useCapabilities()
     // MIGRATION-REVIEW: unlockedRegions/lockedRegions previously came from
     // `useIdentityVerification` (raw rails + Sumsub flags). Now derived from the
@@ -169,7 +174,7 @@ const UnlockedRegions = () => {
         // regionIntent, no Bridge/Manteca rail enrollment) instead of starting
         // region KYC, for ANY region they picked. Card-holders fall through and
         // can still unlock bank regions here.
-        if (hasCardAccess === true && !hasActiveCard) {
+        if (hasCardAccess === true && hasActiveCard === false) {
             setSelectedRegion(null)
             router.push('/card')
             return

From e710de91ba610bd1b0ab415aa0ea058fb55252dd Mon Sep 17 00:00:00 2001
From: peanut <balinda.centar@gmail.com>
Date: Fri, 19 Jun 2026 19:20:02 +0200
Subject: [PATCH 06/10] feat(add-money): flag BRL-via-PIX onramp as under
 maintenance (warn-only)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PIX deposits via Manteca (Brazil) are currently unstable/intermittent. We want
users to still see and use the option, but to know it may be delayed or fail —
so this surfaces a warning without removing the path.

- new config lever underMaintenanceConfig.pixBrazilOnrampMaintenance (warn-only,
  Brazil-scoped — does not touch the Argentina/ARS Manteca onramp or QR pay,
  which the existing coarse disabledPaymentProviders:['MANTECA'] lever would)
- "Maintenance" tag on the Pix option in /add-money/brazil (stays clickable)
- warning banner inside the deposit flow (/add-money/brazil/manteca)

Flip the flag to false when PIX deposits are stable again. Frontend-only: the
API still accepts PIX deposits by design (warn-only).
---
 .../__tests__/add-money-states.test.tsx       |  21 +++
 .../AddMoney/components/InputAmountStep.tsx   |   4 +
 .../AddMoney/components/MantecaAddMoney.tsx   |  15 +++
 .../AddWithdraw/AddWithdrawCountriesList.tsx  | 121 ++++++++++--------
 .../AddWithdrawCountriesList.test.tsx         |  60 ++++++++-
 src/config/underMaintenance.config.ts         |  17 +++
 6 files changed, 184 insertions(+), 54 deletions(-)

diff --git a/src/app/(mobile-ui)/add-money/__tests__/add-money-states.test.tsx b/src/app/(mobile-ui)/add-money/__tests__/add-money-states.test.tsx
index 4e67893f2..d749e8a0e 100644
--- a/src/app/(mobile-ui)/add-money/__tests__/add-money-states.test.tsx
+++ b/src/app/(mobile-ui)/add-money/__tests__/add-money-states.test.tsx
@@ -1503,6 +1503,27 @@ describe('GROUP 8: InputAmountStep Component', () => {
         expect(screen.getByText('Continue')).not.toBeDisabled()
     })
 
+    test('renders maintenanceBanner and keeps Continue enabled (warn-only)', () => {
+        renderWithProviders(
+            <InputAmountStep
+                tokenAmount="100"
+                setTokenAmount={jest.fn()}
+                onSubmit={jest.fn()}
+                isLoading={false}
+                error={null}
+                setCurrencyAmount={jest.fn()}
+                limitsValidation={{ isBlocking: false, isWarning: false, currency: 'USD' }}
+                limitsCurrency="USD"
+                onBack={jest.fn()}
+                maintenanceBanner={<div data-testid="pix-maintenance">PIX deposits are under maintenance</div>}
+            />
+        )
+
+        expect(screen.getByTestId('pix-maintenance')).toBeInTheDocument()
+        // warn-only: the banner is informational and must not block submission
+        expect(screen.getByText('Continue')).not.toBeDisabled()
+    })
+
     test('Continue disabled when limits blocking', () => {
         const { getLimitsWarningCardProps } = require('@/features/limits/utils')
         getLimitsWarningCardProps.mockReturnValue({
diff --git a/src/components/AddMoney/components/InputAmountStep.tsx b/src/components/AddMoney/components/InputAmountStep.tsx
index dc6b78dac..4aa528ee3 100644
--- a/src/components/AddMoney/components/InputAmountStep.tsx
+++ b/src/components/AddMoney/components/InputAmountStep.tsx
@@ -30,6 +30,8 @@ interface InputAmountStepProps {
     // required - must be provided by caller based on the payment flow's currency (ARS, BRL, USD)
     limitsCurrency: LimitCurrency
     onBack: () => void
+    // optional warning banner rendered at the top of the step (e.g. PIX-under-maintenance)
+    maintenanceBanner?: React.ReactNode
 }
 
 const InputAmountStep = ({
@@ -46,6 +48,7 @@ const InputAmountStep = ({
     limitsValidation,
     limitsCurrency,
     onBack,
+    maintenanceBanner,
 }: InputAmountStepProps) => {
     if (currencyData?.isLoading) {
         return <PeanutLoading />
@@ -63,6 +66,7 @@ const InputAmountStep = ({
         <div className="flex min-h-[inherit] flex-col justify-start space-y-8">
             <NavHeader title="Add Money" onPrev={onBack} />
             <div className="my-auto flex flex-grow flex-col justify-center gap-4 md:my-0">
+                {maintenanceBanner}
                 <div className="text-sm font-bold">How much do you want to add?</div>
 
                 <AmountInput
diff --git a/src/components/AddMoney/components/MantecaAddMoney.tsx b/src/components/AddMoney/components/MantecaAddMoney.tsx
index e402bf540..a43a54724 100644
--- a/src/components/AddMoney/components/MantecaAddMoney.tsx
+++ b/src/components/AddMoney/components/MantecaAddMoney.tsx
@@ -25,6 +25,8 @@ import { useQueryStates, parseAsString, parseAsStringEnum } from 'nuqs'
 import { useLimitsValidation } from '@/features/limits/hooks/useLimitsValidation'
 import posthog from 'posthog-js'
 import { ANALYTICS_EVENTS } from '@/constants/analytics.consts'
+import InfoCard from '@/components/Global/InfoCard'
+import underMaintenanceConfig, { PIX_BRAZIL_ONRAMP_MAINTENANCE } from '@/config/underMaintenance.config'
 
 // Step type for URL state
 type MantecaStep = 'inputAmount' | 'depositDetails'
@@ -70,6 +72,9 @@ const MantecaAddMoney: FC = () => {
         return countryData.find((country) => country.type === 'country' && country.path === selectedCountryPath)
     }, [selectedCountryPath])
     const onBack = useSafeBack(addMoneyCountryUrl(selectedCountryPath))
+    // BRL-via-PIX onramp warn-only maintenance flag (see underMaintenance.config.ts).
+    // Brazil-scoped so the Argentina/ARS Manteca onramp is unaffected.
+    const showPixMaintenance = selectedCountry?.id === 'BR' && underMaintenanceConfig.pixBrazilOnrampMaintenance
     // The pool→full upgrade gate asks "did the user clear ID verification?",
     // not "do they have an enabled rail elsewhere?" — read the identity
     // signal directly (Sumsub-cleared the human) instead of the old
@@ -280,6 +285,16 @@ const MantecaAddMoney: FC = () => {
                     limitsValidation={limitsValidation}
                     limitsCurrency={limitsValidation.currency}
                     onBack={onBack}
+                    maintenanceBanner={
+                        showPixMaintenance ? (
+                            <InfoCard
+                                variant="warning"
+                                icon="alert"
+                                title={PIX_BRAZIL_ONRAMP_MAINTENANCE.title}
+                                description={PIX_BRAZIL_ONRAMP_MAINTENANCE.description}
+                            />
+                        ) : undefined
+                    }
                 />
             </>
         )
diff --git a/src/components/AddWithdraw/AddWithdrawCountriesList.tsx b/src/components/AddWithdraw/AddWithdrawCountriesList.tsx
index 0005b3f54..6698a3044 100644
--- a/src/components/AddWithdraw/AddWithdrawCountriesList.tsx
+++ b/src/components/AddWithdraw/AddWithdrawCountriesList.tsx
@@ -35,6 +35,7 @@ import { getRegionIntent } from '@/utils/regions.utils'
 import { useTosGuard } from '@/hooks/useTosGuard'
 import { BridgeTosStep } from '@/components/Kyc/BridgeTosStep'
 import { useModalsContext } from '@/context/ModalsContext'
+import underMaintenanceConfig, { PIX_BRAZIL_ONRAMP_MAINTENANCE } from '@/config/underMaintenance.config'
 
 interface AddWithdrawCountriesListProps {
     flow: 'add' | 'withdraw'
@@ -426,58 +427,76 @@ const AddWithdrawCountriesList = ({ flow }: AddWithdrawCountriesListProps) => {
             <div className="space-y-2">
                 <h2 className="text-base font-bold">{title}</h2>
                 <div className="flex flex-col">
-                    {paymentMethods.map((method, index) => (
-                        <ActionListCard
-                            key={method.id}
-                            isDisabled={method.isSoon}
-                            title={method.title}
-                            description={method.description}
-                            descriptionClassName={'text-xs'}
-                            leftIcon={
-                                typeof method.icon === 'string' || method.icon === undefined ? (
-                                    <AvatarWithBadge
-                                        icon={method.icon as IconName}
-                                        name={method.title ?? method.id}
-                                        size="extra-small"
-                                        inlineStyle={{
-                                            backgroundColor:
-                                                method.icon === ('bank' as IconName)
-                                                    ? '#FFC900'
-                                                    : method.id === 'crypto-add' || method.id === 'crypto-withdraw'
-                                                      ? '#FFC900'
-                                                      : getColorForUsername(method.title).lightShade,
-                                            color: method.icon === ('bank' as IconName) ? 'black' : 'black',
-                                        }}
-                                    />
-                                ) : (
-                                    <Image
-                                        src={method.icon as StaticImageData}
-                                        alt={method.id}
-                                        className="h-8 w-8 rounded-full"
-                                        width={32}
-                                        height={32}
-                                    />
-                                )
-                            }
-                            rightContent={method.isSoon ? <StatusBadge status="soon" size="small" /> : null}
-                            onClick={() => {
-                                if (flow === 'withdraw') {
-                                    handleWithdrawMethodClick(method)
-                                } else if (method.path) {
-                                    handleAddMethodClick(method)
+                    {paymentMethods.map((method, index) => {
+                        // BRL-via-PIX onramp is warn-only under maintenance: tag the Pix option but
+                        // keep it clickable (do not set isDisabled).
+                        const isPixOnrampUnderMaintenance =
+                            flow === 'add' &&
+                            method.id === 'pix-add' &&
+                            underMaintenanceConfig.pixBrazilOnrampMaintenance
+                        return (
+                            <ActionListCard
+                                key={method.id}
+                                isDisabled={method.isSoon}
+                                title={method.title}
+                                description={method.description}
+                                descriptionClassName={'text-xs'}
+                                leftIcon={
+                                    typeof method.icon === 'string' || method.icon === undefined ? (
+                                        <AvatarWithBadge
+                                            icon={method.icon as IconName}
+                                            name={method.title ?? method.id}
+                                            size="extra-small"
+                                            inlineStyle={{
+                                                backgroundColor:
+                                                    method.icon === ('bank' as IconName)
+                                                        ? '#FFC900'
+                                                        : method.id === 'crypto-add' || method.id === 'crypto-withdraw'
+                                                          ? '#FFC900'
+                                                          : getColorForUsername(method.title).lightShade,
+                                                color: method.icon === ('bank' as IconName) ? 'black' : 'black',
+                                            }}
+                                        />
+                                    ) : (
+                                        <Image
+                                            src={method.icon as StaticImageData}
+                                            alt={method.id}
+                                            className="h-8 w-8 rounded-full"
+                                            width={32}
+                                            height={32}
+                                        />
+                                    )
                                 }
-                            }}
-                            position={
-                                paymentMethods.length === 1
-                                    ? 'single'
-                                    : index === 0
-                                      ? 'first'
-                                      : index === paymentMethods.length - 1
-                                        ? 'last'
-                                        : 'middle'
-                            }
-                        />
-                    ))}
+                                rightContent={
+                                    method.isSoon ? (
+                                        <StatusBadge status="soon" size="small" />
+                                    ) : isPixOnrampUnderMaintenance ? (
+                                        <StatusBadge
+                                            status="pending"
+                                            customText={PIX_BRAZIL_ONRAMP_MAINTENANCE.badge}
+                                            size="small"
+                                        />
+                                    ) : null
+                                }
+                                onClick={() => {
+                                    if (flow === 'withdraw') {
+                                        handleWithdrawMethodClick(method)
+                                    } else if (method.path) {
+                                        handleAddMethodClick(method)
+                                    }
+                                }}
+                                position={
+                                    paymentMethods.length === 1
+                                        ? 'single'
+                                        : index === 0
+                                          ? 'first'
+                                          : index === paymentMethods.length - 1
+                                            ? 'last'
+                                            : 'middle'
+                                }
+                            />
+                        )
+                    })}
                 </div>
             </div>
         )
diff --git a/src/components/AddWithdraw/__tests__/AddWithdrawCountriesList.test.tsx b/src/components/AddWithdraw/__tests__/AddWithdrawCountriesList.test.tsx
index 972c92fd6..e6329cfab 100644
--- a/src/components/AddWithdraw/__tests__/AddWithdrawCountriesList.test.tsx
+++ b/src/components/AddWithdraw/__tests__/AddWithdrawCountriesList.test.tsx
@@ -15,8 +15,9 @@
  * gate is NOT ready — so the fix didn't just delete the guard wholesale.
  */
 import React from 'react'
-import { render, screen, fireEvent } from '@testing-library/react'
+import { render, screen, fireEvent, within } from '@testing-library/react'
 import AddWithdrawCountriesList from '../AddWithdrawCountriesList'
+import underMaintenanceConfig from '@/config/underMaintenance.config'
 
 // ---- routing ----
 const mockPush = jest.fn()
@@ -41,6 +42,13 @@ jest.mock('@/components/AddMoney/consts', () => ({
                     icon: 'bank',
                     path: '/add-money/testland/bank',
                 },
+                {
+                    id: 'pix-add',
+                    title: 'Pix',
+                    description: 'Instant transfers',
+                    icon: 'pix',
+                    path: '/add-money/brazil/manteca',
+                },
             ],
             // id contains 'default-bank-withdraw' → routes through checkBridgeGate
             // (not the Manteca direct path), so it exercises the same gate.
@@ -128,8 +136,13 @@ jest.mock('@/utils/regions.utils', () => ({ getRegionIntent: () => 'STANDARD' })
 
 jest.mock('@/components/ActionListCard', () => ({
     ActionListCard: (props: any) => (
-        <button data-testid={`method-${props.title?.toLowerCase()}`} onClick={props.onClick}>
+        <button
+            data-testid={`method-${props.title?.toLowerCase()}`}
+            onClick={props.isDisabled ? undefined : props.onClick}
+            disabled={props.isDisabled}
+        >
             {props.title}
+            {props.rightContent}
         </button>
     ),
 }))
@@ -137,7 +150,10 @@ jest.mock('@/components/Global/NavHeader', () => ({
     __esModule: true,
     default: () => <div data-testid="nav-header" />,
 }))
-jest.mock('@/components/Global/Badges/StatusBadge', () => ({ __esModule: true, default: () => <span /> }))
+jest.mock('@/components/Global/Badges/StatusBadge', () => ({
+    __esModule: true,
+    default: (props: any) => <span data-testid="status-badge">{props.customText ?? props.status}</span>,
+}))
 jest.mock('@/components/Profile/AvatarWithBadge', () => ({ __esModule: true, default: () => <span /> }))
 jest.mock('@/components/Global/EmptyStates/EmptyState', () => ({ __esModule: true, default: () => <div /> }))
 jest.mock('@/components/AddWithdraw/DynamicBankAccountForm', () => ({ DynamicBankAccountForm: () => <div /> }))
@@ -220,3 +236,41 @@ describe('AddWithdrawCountriesList — bank gate', () => {
         expect(screen.getByTestId('initiate-kyc-modal')).toBeInTheDocument()
     })
 })
+
+/**
+ * BRL-via-PIX onramp is unstable, so the Pix option is flagged "under maintenance"
+ * (config: pixBrazilOnrampMaintenance) — warn-only: it stays visible and clickable.
+ */
+describe('AddWithdrawCountriesList — PIX onramp maintenance tag', () => {
+    beforeEach(() => {
+        mockPush.mockClear()
+        // a ready gate so a click can navigate — proving the option is not blocked
+        setCapabilities('ready', [{ status: 'enabled', channel: 'bank', country: 'US' }])
+    })
+
+    afterEach(() => {
+        underMaintenanceConfig.pixBrazilOnrampMaintenance = true
+    })
+
+    it('tags the Pix option "Maintenance" but keeps it clickable (warn-only)', () => {
+        underMaintenanceConfig.pixBrazilOnrampMaintenance = true
+
+        render(<AddWithdrawCountriesList flow="add" />)
+
+        const pixCard = screen.getByTestId('method-pix')
+        expect(within(pixCard).getByText('Maintenance')).toBeInTheDocument()
+
+        // warn-only: still navigates into the deposit flow
+        fireEvent.click(pixCard)
+        expect(mockPush).toHaveBeenCalledWith('/add-money/brazil/manteca')
+    })
+
+    it('shows no maintenance tag when the flag is off, and never tags non-Pix methods', () => {
+        underMaintenanceConfig.pixBrazilOnrampMaintenance = false
+
+        render(<AddWithdrawCountriesList flow="add" />)
+
+        expect(within(screen.getByTestId('method-pix')).queryByText('Maintenance')).toBeNull()
+        expect(within(screen.getByTestId('method-bank')).queryByText('Maintenance')).toBeNull()
+    })
+})
diff --git a/src/config/underMaintenance.config.ts b/src/config/underMaintenance.config.ts
index 125116194..abbf63fb8 100644
--- a/src/config/underMaintenance.config.ts
+++ b/src/config/underMaintenance.config.ts
@@ -34,6 +34,12 @@
  *    - card pioneer modal, carousel cta, and perk rewards hidden from home
  *    - set to false to enable the feature
  *
+ * 7. pixBrazilOnrampMaintenance: warn-only flag for the BRL-via-PIX onramp (Manteca Brazil deposit)
+ *    - shows a "Maintenance" tag on the Pix option in /add-money/brazil
+ *    - shows a warning banner inside the deposit flow (/add-money/brazil/manteca)
+ *    - does NOT block deposits — the option stays usable (warn-only)
+ *    - set to false when PIX deposits are stable again
+ *
  * note: if either mode is enabled, the maintenance banner will show everywhere
  *
  * I HOPE WE NEVER NEED TO USE THIS...
@@ -49,6 +55,7 @@ interface MaintenanceConfig {
     disableXchainWithdraw: boolean
     disableXchainSend: boolean
     disableCardPioneers: boolean
+    pixBrazilOnrampMaintenance: boolean
 }
 
 const underMaintenanceConfig: MaintenanceConfig = {
@@ -58,10 +65,20 @@ const underMaintenanceConfig: MaintenanceConfig = {
     disableXchainWithdraw: true, // set to true to disable cross-chain withdrawals (only allows USDC on Arbitrum)
     disableXchainSend: true, // set to true to disable cross-chain sends (claim, request payments - only allows USDC on Arbitrum)
     disableCardPioneers: true, // set to false to enable the Card Pioneers waitlist feature
+    pixBrazilOnrampMaintenance: true, // set to false when BRL-via-PIX deposits are stable again
 }
 
 // shared user-facing copy for cross-chain disabled paths — keep wording aligned with TokenSelector banner
 export const CROSS_CHAIN_DISABLED_MESSAGE =
     'Cross-chain claims are temporarily unavailable. Try claiming to an external wallet on the same chain as the link, or try again later.'
 
+// shared user-facing copy for the BRL-via-PIX onramp maintenance warning — keep the list tag and
+// the in-flow banner aligned
+export const PIX_BRAZIL_ONRAMP_MAINTENANCE = {
+    badge: 'Maintenance',
+    title: 'PIX deposits are under maintenance',
+    description:
+        'PIX deposits are currently unstable and may be delayed or fail. You can still continue, but service may be unreliable until this is resolved.',
+}
+
 export default underMaintenanceConfig

From ac488e7052a2a1cd1c4674bda45b5167355b7392 Mon Sep 17 00:00:00 2001
From: Hugo Montenegro <h@hugo0.com>
Date: Tue, 23 Jun 2026 11:30:11 -0700
Subject: [PATCH 07/10] fix(claim): preserve send-link password across the
 auth/KYC redirect

A new recipient who opens a send link, registers/KYCs, and is redirected
back to /claim hit a 404 'Send link not found' and could not claim
(TASK-20193). The claim pubKey is derived from the link's #p= password
fragment; the guest -> /setup -> KYC -> /claim flow fully remounts the page
and the fragment comes back mangled (the c/v/i query survives), so the
remounted page derives the wrong pubKey and 404s.

Proven in prod: the failing GET used a pubKey absent from the DB while the
real link at the same deposit slot (c=42161,v=v4.4,i=181) exists and is
completed.

Fix: resolveClaimLink keys the pristine link by its deposit slot (which the
redirect preserves) in localStorage on first open; first write wins, so the
correct password stays authoritative even if a later remount arrives with a
broken fragment. Slot-local + client-only, so nothing new is exposed.
---
 src/components/Claim/Claim.tsx                | 14 ++++--
 .../__tests__/resolveClaimLink.test.ts        | 47 +++++++++++++++++++
 src/services/sendLinks.ts                     | 40 +++++++++++++++-
 3 files changed, 97 insertions(+), 4 deletions(-)
 create mode 100644 src/services/__tests__/resolveClaimLink.test.ts

diff --git a/src/components/Claim/Claim.tsx b/src/components/Claim/Claim.tsx
index 1a3ed11d3..04da70171 100644
--- a/src/components/Claim/Claim.tsx
+++ b/src/components/Claim/Claim.tsx
@@ -14,7 +14,13 @@ import { EHistoryUserRole } from '@/hooks/useTransactionHistory'
 import { useUserInteractions } from '@/hooks/useUserInteractions'
 import { useWallet } from '@/hooks/wallet/useWallet'
 import type { RecipientType } from '@/interfaces/interfaces'
-import { ESendLinkStatus, getParamsFromLink, sendLinksApi, type ClaimLinkData } from '@/services/sendLinks'
+import {
+    ESendLinkStatus,
+    getParamsFromLink,
+    resolveClaimLink,
+    sendLinksApi,
+    type ClaimLinkData,
+} from '@/services/sendLinks'
 import {
     getInitialsFromName,
     getTokenDetails,
@@ -408,7 +414,9 @@ export const Claim = ({}) => {
     useEffect(() => {
         const pageUrl = typeof window !== 'undefined' ? window.location.href : ''
         if (pageUrl) {
-            setLinkUrl(pageUrl) // TanStack Query will automatically fetch when linkUrl changes
+            // resolveClaimLink restores the pristine `#p=` password if an auth/KYC
+            // redirect mangled the current URL's fragment (TASK-20193).
+            setLinkUrl(resolveClaimLink(pageUrl)) // TanStack Query will automatically fetch when linkUrl changes
         }
     }, [])
 
@@ -526,7 +534,7 @@ export const Claim = ({}) => {
                     transaction={selectedTransaction}
                     setIsLoading={setisLinkCancelling}
                     isLoading={isLinkCancelling}
-                    onClose={() => setLinkUrl(window.location.href)}
+                    onClose={() => setLinkUrl(resolveClaimLink(window.location.href))}
                 />
             )}
         </PageContainer>
diff --git a/src/services/__tests__/resolveClaimLink.test.ts b/src/services/__tests__/resolveClaimLink.test.ts
new file mode 100644
index 000000000..f3c6639f9
--- /dev/null
+++ b/src/services/__tests__/resolveClaimLink.test.ts
@@ -0,0 +1,47 @@
+/** @jest-environment jsdom */
+import { resolveClaimLink } from '@/services/sendLinks'
+import { generateKeysFromString, getParamsFromLink } from '@/utils/peanut-link.utils'
+
+// A v4.4 Arbitrum claim link: c/v/i live in the query (survive the redirect),
+// the password lives in the `#p=` fragment (mangled by the redirect).
+const BASE = 'https://peanut.me/claim?c=42161&v=v4.4&i=181'
+const PRISTINE = `${BASE}#p=abcdef0123456789`
+// What the claim page looks like after the auth/KYC redirect remounts it with a
+// corrupted fragment — same deposit slot, different (wrong) password.
+const CORRUPTED = `${BASE}&step=bank#p=WRONGwrongWRONG`
+
+const pubKeyOf = (link: string) => generateKeysFromString(getParamsFromLink(link).password).address
+
+beforeEach(() => localStorage.clear())
+
+describe('resolveClaimLink (TASK-20193)', () => {
+    it('restores the pristine password after a redirect mangles the fragment', () => {
+        // 1) recipient first opens the link → pristine password is captured
+        expect(resolveClaimLink(PRISTINE)).toBe(PRISTINE)
+
+        // 2) the post-redirect remount arrives with a corrupted fragment, which
+        // on its own derives the wrong pubKey (the prod 404 root cause)...
+        expect(pubKeyOf(CORRUPTED)).not.toBe(pubKeyOf(PRISTINE))
+
+        // 3) ...but resolveClaimLink serves the pristine link, so the fetch uses
+        // the correct pubKey instead of 404ing.
+        const resolved = resolveClaimLink(CORRUPTED)
+        expect(resolved).toBe(PRISTINE)
+        expect(pubKeyOf(resolved)).toBe(pubKeyOf(PRISTINE))
+    })
+
+    it('first write wins — a later mangled load cannot overwrite a good capture', () => {
+        resolveClaimLink(PRISTINE)
+        resolveClaimLink(CORRUPTED)
+        expect(resolveClaimLink(`${BASE}#p=yetAnotherWrongOne`)).toBe(PRISTINE)
+    })
+
+    it('passes through links without a deposit slot untouched', () => {
+        const noSlot = 'https://peanut.me/claim#p=orphan'
+        expect(resolveClaimLink(noSlot)).toBe(noSlot)
+    })
+
+    it('passes through non-URL input without throwing', () => {
+        expect(resolveClaimLink('not a url')).toBe('not a url')
+    })
+})
diff --git a/src/services/sendLinks.ts b/src/services/sendLinks.ts
index 1dba64b87..cd14bdfd8 100644
--- a/src/services/sendLinks.ts
+++ b/src/services/sendLinks.ts
@@ -1,4 +1,4 @@
-import { jsonParse, jsonStringify } from '@/utils/general.utils'
+import { jsonParse, jsonStringify, getFromLocalStorage, saveToLocalStorage } from '@/utils/general.utils'
 import { generateKeysFromString, getParamsFromLink } from '@/utils/peanut-link.utils'
 import type { SendLink } from '@/services/services.types'
 import { serverFetch } from '@/utils/api-fetch'
@@ -12,6 +12,44 @@ export { getParamsFromLink } from '@/utils/peanut-link.utils'
 
 export type ClaimLinkData = SendLink & { link: string; password: string }
 
+const CLAIM_LINK_SLOT_PREFIX = 'claim-link-slot'
+// KYC review between opening a link and returning to claim can span days.
+const CLAIM_LINK_TTL_SECONDS = 7 * 24 * 60 * 60
+
+/**
+ * Resolve the link used to fetch + claim a send link, hardened against the
+ * auth/KYC redirect mangling the URL's `#p=` password fragment (TASK-20193).
+ *
+ * The recipient opens `/claim?c=&v=&i=#p=<password>`; the password derives the
+ * deterministic pubKey the backend is keyed on. The guest → /setup → KYC →
+ * /claim flow fully remounts the page, and across that multi-hop redirect the
+ * fragment can come back corrupted while the `c/v/i` query survives — so the
+ * remounted page derives the WRONG pubKey and gets a 404 "Send link not found",
+ * dead-ending the claim.
+ *
+ * Fix: key the pristine link by its deposit slot (chain:version:index, which
+ * the redirect preserves) in localStorage when the link is first opened.
+ * First write wins, so the correct password stays authoritative even if a
+ * later remount arrives with a broken fragment.
+ */
+export const resolveClaimLink = (currentLink: string): string => {
+    if (typeof window === 'undefined') return currentLink
+    let params: ReturnType<typeof getParamsFromLink>
+    try {
+        params = getParamsFromLink(currentLink)
+    } catch {
+        return currentLink
+    }
+    // Without a real deposit slot we can't key the link — leave it untouched.
+    if (!params.chainId || Number.isNaN(params.depositIdx)) return currentLink
+
+    const key = `${CLAIM_LINK_SLOT_PREFIX}::${params.chainId}:${params.contractVersion}:${params.depositIdx}`
+    const stored = getFromLocalStorage(key)
+    if (typeof stored === 'string' && stored) return stored // pristine link wins
+    if (params.password) saveToLocalStorage(key, currentLink, CLAIM_LINK_TTL_SECONDS)
+    return currentLink
+}
+
 type CreateLinkBody = {
     pubKey: string
     reference?: string

From 4b56290f08ceffb4d8bccf8e5f7386358cb660f0 Mon Sep 17 00:00:00 2001
From: Hugo Montenegro <h@hugo0.com>
Date: Tue, 23 Jun 2026 11:36:44 -0700
Subject: [PATCH 08/10] test(claim): stub resolveClaimLink in the sendLinks
 mock

claim-states mounts <Claim/>, which now calls resolveClaimLink; the module
mock must expose it or the suite throws 'resolveClaimLink is not a function'.
---
 src/components/Claim/__tests__/claim-states.test.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/components/Claim/__tests__/claim-states.test.tsx b/src/components/Claim/__tests__/claim-states.test.tsx
index ecca0edb6..e99acc139 100644
--- a/src/components/Claim/__tests__/claim-states.test.tsx
+++ b/src/components/Claim/__tests__/claim-states.test.tsx
@@ -157,6 +157,7 @@ jest.mock('@/services/sendLinks', () => ({
     },
     sendLinksApi: mockSendLinksApi,
     getParamsFromLink: (...args: any[]) => mockGetParamsFromLink(...args),
+    resolveClaimLink: (link: string) => link,
 }))
 
 jest.mock('@/utils/peanut-link.utils', () => ({

From c35249d76f629dfd06fa334dd8265b3190d65e96 Mon Sep 17 00:00:00 2001
From: Hugo Montenegro <h@hugo0.com>
Date: Tue, 23 Jun 2026 11:57:41 -0700
Subject: [PATCH 09/10] fix(security): pass localStorage key as a console arg,
 not a format string

CodeQL flagged externally-controlled-format-string (high): resolveClaimLink
builds the localStorage key from user-controlled URL params, which then reached
saveToLocalStorage's console.log as the format string. Pass key as a trailing
arg so a %s/%d in a link can't be interpreted as a format specifier.
---
 src/utils/general.utils.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/utils/general.utils.ts b/src/utils/general.utils.ts
index b1810da67..8b9e69bbd 100644
--- a/src/utils/general.utils.ts
+++ b/src/utils/general.utils.ts
@@ -137,7 +137,9 @@ export const saveToLocalStorage = (key: string, data: any, expirySeconds?: numbe
         } else {
             localStorage.removeItem(`${key}-expiry`)
         }
-        console.log(`Saved ${key} to localStorage:`, data)
+        // key is passed as an argument (not interpolated into the format string)
+        // so a user-controlled key can't act as a console format string (CodeQL).
+        console.log('Saved to localStorage:', key, data)
     } catch (error) {
         Sentry.captureException(error)
         console.error('Error saving to localStorage:', error)

From ab7b70f6169b3f8ef7c8e11662dc12a4a6897edc Mon Sep 17 00:00:00 2001
From: Hugo Montenegro <h@hugo0.com>
Date: Tue, 23 Jun 2026 11:47:01 -0700
Subject: [PATCH 10/10] fix(claim): show the backend's bank-account error
 verbatim
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When adding a bank account for a send-link payout fails, the backend now
returns a curated, user-facing message (e.g. 'we couldn't verify your bank's
billing address — check city/state/ZIP'). Routing it through ErrorHandler
collapsed it into the generic 'contact support' fallback, hiding the
actionable detail. Surface response.error verbatim for this path; keep FE
Sentry capture. (TASK-20194, companion to peanut-api-ts external-account fix)
---
 src/components/Claim/Link/views/BankFlowManager.view.tsx | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/components/Claim/Link/views/BankFlowManager.view.tsx b/src/components/Claim/Link/views/BankFlowManager.view.tsx
index 975ab3a9b..f66aacdef 100644
--- a/src/components/Claim/Link/views/BankFlowManager.view.tsx
+++ b/src/components/Claim/Link/views/BankFlowManager.view.tsx
@@ -396,7 +396,13 @@ export const BankFlowManager = (props: IClaimScreenProps) => {
                     payloadWithCountry
                 )
                 if ('error' in externalAccountResponse && externalAccountResponse.error) {
-                    throw new Error(String(externalAccountResponse.error))
+                    // The backend returns a curated, user-facing message for bank-account
+                    // validation failures (e.g. an unverifiable billing address). Surface it
+                    // verbatim — routing it through ErrorHandler would collapse it into the
+                    // generic "contact support" fallback, hiding the actionable detail. (TASK-20194)
+                    const accountError = String(externalAccountResponse.error)
+                    Sentry.captureException(new Error(`External account creation failed: ${accountError}`))
+                    return { error: accountError }
                 }
                 if (!('id' in externalAccountResponse)) {
                     throw new Error('Failed to create external account')