Stripe External Redirect Navigation Fix

Solution

Use sessionStorage to explicitly track when returning from an external redirect:

1. Create a utility for tracking external returns

// Session storage key for tracking external payment returns
const EXTERNAL_RETURN_KEY = 'external_payment_return';

/**
 * Mark that the user just returned from an external site (e.g., Stripe).
 * Call this when handling payment returns or other external redirects.
 */
export function markExternalReturn() {
  if (typeof sessionStorage !== 'undefined') {
    sessionStorage.setItem(EXTERNAL_RETURN_KEY, 'true');
  }
}

/**
 * Clear the external return flag. Call after handling.
 */
export function clearExternalReturn() {
  if (typeof sessionStorage !== 'undefined') {
    sessionStorage.removeItem(EXTERNAL_RETURN_KEY);
  }
}

/**
 * Check if the user just returned from an external site.
 */
export function hasExternalReturn(): boolean {
  if (typeof sessionStorage === 'undefined') return false;
  return sessionStorage.getItem(EXTERNAL_RETURN_KEY) === 'true';
}

2. Mark external return when handling payment callback

// In your payment return handler (e.g., /settings?payment=success)
function PaymentReturnHandler() {
  const searchParams = useSearchParams();

  useEffect(() => {
    const payment = searchParams.get("payment");

    if (payment === "success" || payment === "cancelled") {
      // Mark that we returned from external payment
      markExternalReturn();

      // ... handle payment verification
    }
  }, [searchParams]);
}

3. Check flag in BackButton before using history

function BackButton({ fallback = '/app' }) {
  const router = useRouter();

  const handleBack = () => {
    // Check if we explicitly marked an external return (most reliable)
    const markedExternal = hasExternalReturn();

    // Fallback checks (less reliable but catch edge cases)
    const referrer = typeof document !== 'undefined' ? document.referrer : '';
    const host = typeof window !== 'undefined' ? window.location.host : '';
    const isExternalReferrer = referrer && !referrer.includes(host);
    const historyTooShort = typeof window !== 'undefined' && window.history.length <= 2;

    if (markedExternal || isExternalReferrer || historyTooShort) {
      clearExternalReturn(); // Clear flag after use
      router.push(fallback);
    } else {
      router.back();
    }
  };

  return <button onClick={handleBack}>Back</button>;
}

Verification

1. Go to your payment page (e.g., /settings)
2. Click "Purchase" to go to Stripe checkout
3. Complete payment (use test card 4242 4242 4242 4242)
4. After redirect back to your app, click the back button
5. Expected: Navigate to your app's home/fallback page (e.g., /app)
6. Before fix: Would navigate back to Stripe checkout

Example

Full implementation in a Next.js settings page with Stripe:

// components/ui/BackButton.tsx
'use client';

import { useRouter } from 'next/navigation';

const EXTERNAL_RETURN_KEY = 'external_payment_return';

// Static method pattern allows: BackButton.markExternalReturn()
BackButton.markExternalReturn = function() {
  if (typeof sessionStorage !== 'undefined') {
    sessionStorage.setItem(EXTERNAL_RETURN_KEY, 'true');
  }
};

export function BackButton({ fallback = '/app' }) {
  const router = useRouter();

  const handleBack = () => {
    const hasExternal = sessionStorage?.getItem(EXTERNAL_RETURN_KEY) === 'true';

    if (hasExternal) {
      sessionStorage.removeItem(EXTERNAL_RETURN_KEY);
      router.push(fallback);
    } else {
      router.back();
    }
  };

  return (
    <button onClick={handleBack} aria-label="Go back">
      ← Back
    </button>
  );
}

// app/settings/page.tsx
function PaymentReturnHandler() {
  const searchParams = useSearchParams();

  useEffect(() => {
    if (searchParams.get("payment") === "success") {
      BackButton.markExternalReturn(); // Mark before clearing URL

      // Handle payment verification...

      router.replace("/settings"); // Clean URL
    }
  }, [searchParams]);
}

export default function SettingsPage() {
  return (
    <>
      <PaymentReturnHandler />
      <BackButton fallback="/app" />
      {/* ... */}
    </>
  );
}

Notes

1. sessionStorage vs localStorage: Use sessionStorage because it's tab-specific. If user opens multiple tabs, each has its own payment flow state.

2. Security: This flag only affects UX navigation, not payment security. Payment verification must still happen server-side with Stripe session validation.

3. Flag cleanup: Always clear the flag after use to prevent it from affecting future navigation in the same session.

4. Multiple fallback checks: Keep the document.referrer and history.length checks as fallbacks for edge cases, but don't rely on them for Stripe.

5. Why not just use Link?: Using a simple <Link href="/"> works but loses the "back" behavior for internal navigation. The sessionStorage approach gives you the best of both: proper back navigation internally, fallback for external returns.

References

• Stripe Checkout Integration
• MDN: Referrer-Policy
• Next.js Navigation