(SP:3) [SHOP] harden checkout, wallet flows, shipping coupling, and local smoke coverage

frontend/app/[locale]/shop/cart/capabilities.ts

@@ -0,0 +1,35 @@
+import { isMonobankEnabled } from '@/lib/env/monobank';
+import { isPaymentsEnabled as isStripePaymentsEnabled } from '@/lib/env/stripe';
+
+function isFlagEnabled(value: string | undefined): boolean {
+  return (value ?? '').trim() === 'true';
+}
+
+export function resolveStripeCheckoutEnabled(): boolean {
+  try {
+    return isStripePaymentsEnabled({
+      requirePublishableKey: true,
+      respectStripePaymentsFlag: true,
+    });
+  } catch {
+    return false;
+  }
+}
+
+export function resolveMonobankCheckoutEnabled(): boolean {
+  const paymentsEnabled = isFlagEnabled(process.env.PAYMENTS_ENABLED);
+  if (!paymentsEnabled) return false;
+
+  try {
+    return isMonobankEnabled();
+  } catch {
+    return false;
+  }
+}
+
+export function resolveMonobankGooglePayEnabled(): boolean {
+  const raw = (process.env.SHOP_MONOBANK_GPAY_ENABLED ?? '')
+    .trim()
+    .toLowerCase();
+  return raw === 'true' || raw === '1' || raw === 'yes' || raw === 'on';
+}

frontend/app/[locale]/shop/cart/page.tsx

@@ -1,43 +1,17 @@
 import type { Metadata } from 'next';
 
-import { isMonobankEnabled } from '@/lib/env/monobank';
-
+import {
+  resolveMonobankCheckoutEnabled,
+  resolveMonobankGooglePayEnabled,
+  resolveStripeCheckoutEnabled,
+} from './capabilities';
 import CartPageClient from './CartPageClient';
 
 export const metadata: Metadata = {
   title: 'Cart | DevLovers',
   description: 'Review items in your cart and proceed to checkout.',
 };
 
-function isFlagEnabled(value: string | undefined): boolean {
-  return (value ?? '').trim() === 'true';
-}
-
-function resolveStripeCheckoutEnabled(): boolean {
-  const paymentsEnabled = isFlagEnabled(process.env.PAYMENTS_ENABLED);
-  const stripeFlag = (process.env.STRIPE_PAYMENTS_ENABLED ?? '').trim();
-
-  return (
-    paymentsEnabled && (stripeFlag.length > 0 ? stripeFlag === 'true' : true)
-  );
-}
-
-function resolveMonobankCheckoutEnabled(): boolean {
-  const paymentsEnabled = isFlagEnabled(process.env.PAYMENTS_ENABLED);
-  if (!paymentsEnabled) return false;
-
-  try {
-    return isMonobankEnabled();
-  } catch {
-    return false;
-  }
-}
-
-function resolveMonobankGooglePayEnabled(): boolean {
-  const raw = (process.env.SHOP_MONOBANK_GPAY_ENABLED ?? '').trim().toLowerCase();
-  return raw === 'true' || raw === '1' || raw === 'yes' || raw === 'on';
-}
-
 export default function CartPage() {
   return (
     <CartPageClient

frontend/app/[locale]/shop/checkout/error/page.tsx

@@ -44,6 +44,11 @@ function parseOrderId(searchParams?: SearchParams): string | null {
   return parsed.success ? parsed.data.id : null;
 }
 
+function parseStatusToken(searchParams?: SearchParams): string | null {
+  const raw = getStringParam(searchParams, 'statusToken').trim();
+  return raw.length > 0 ? raw : null;
+}
+
 const SHOP_HERO_CTA_SM = cn(
   SHOP_CTA_BASE,
   SHOP_CTA_INTERACTIVE,
@@ -76,6 +81,7 @@ export default async function CheckoutErrorPage({
       : (searchParams as SearchParams | undefined);
 
   const orderId = parseOrderId(resolvedSearchParams);
+  const statusToken = parseStatusToken(resolvedSearchParams);
 
   if (!orderId) {
     return (
@@ -278,7 +284,11 @@ export default async function CheckoutErrorPage({
 
           {isFailed && order.id ? (
             <Link
-              href={`/shop/checkout/payment/${order.id}`}
+              href={`/shop/checkout/payment/${order.id}${
+                statusToken
+                  ? `?statusToken=${encodeURIComponent(statusToken)}`
+                  : ''
+              }`}
               className={SHOP_HERO_CTA_SM}
             >
               <span

frontend/app/[locale]/shop/checkout/payment/StripePaymentClient.tsx

@@ -37,13 +37,15 @@ import { cn } from '@/lib/utils';
 type PaymentFormProps = {
   orderId: string;
   locale: string;
+  statusToken: string | null;
 };
 
 type StripePaymentClientProps = {
   clientSecret?: string | null;
   publishableKey: string | null;
   paymentsEnabled: boolean;
   orderId: string;
+  statusToken: string | null;
   amountMinor: number;
   currency: string;
   locale: string;
@@ -81,17 +83,23 @@ function buildStripeReturnUrl(params: {
   return new URL(`/${loc}${p}`, window.location.origin).toString();
 }
 
-function nextRouteForPaymentResult(params: {
+export function nextRouteForPaymentResult(params: {
   orderId: string;
+  statusToken: string | null;
   status?: string | null;
 }) {
-  const { orderId, status } = params;
+  const { orderId, status, statusToken } = params;
   const id = encodeURIComponent(orderId);
+  const tokenSuffix = statusToken
+    ? `&statusToken=${encodeURIComponent(statusToken)}`
+    : '';
 
-  const success = buildInAppPath(`/checkout/success?orderId=${id}`);
+  const success = buildInAppPath(
+    `/checkout/success?orderId=${id}${tokenSuffix}`
+  );
   const failure = buildInAppPath(`/checkout/error?orderId=${id}`);
 
-  if (!status) return success;
+  if (!status) return failure;
 
   if (
     status === 'succeeded' ||
@@ -105,7 +113,7 @@ function nextRouteForPaymentResult(params: {
     return failure;
   }
 
-  return success;
+  return failure;
 }
 
 const SHOP_HERO_CTA = cn(
@@ -152,7 +160,7 @@ function HeroCtaInner({ children }: { children: React.ReactNode }) {
   );
 }
 
-function StripePaymentForm({ orderId, locale }: PaymentFormProps) {
+function StripePaymentForm({ orderId, locale, statusToken }: PaymentFormProps) {
   const stripe = useStripe();
   const elements = useElements();
   const router = useRouter();
@@ -175,8 +183,13 @@ function StripePaymentForm({ orderId, locale }: PaymentFormProps) {
 
     try {
       const id = encodeURIComponent(orderId);
+      const tokenSuffix = statusToken
+        ? `&statusToken=${encodeURIComponent(statusToken)}`
+        : '';
 
-      const inAppSuccess = buildInAppPath(`/checkout/success?orderId=${id}`);
+      const inAppSuccess = buildInAppPath(
+        `/checkout/success?orderId=${id}${tokenSuffix}`
+      );
       const inAppFailure = buildInAppPath(`/checkout/error?orderId=${id}`);
 
       const { error, paymentIntent } = await stripe.confirmPayment({
@@ -195,6 +208,7 @@ function StripePaymentForm({ orderId, locale }: PaymentFormProps) {
 
       const next = nextRouteForPaymentResult({
         orderId,
+        statusToken,
         status: paymentIntent?.status ?? null,
       });
 
@@ -243,6 +257,7 @@ export default function StripePaymentClient({
   publishableKey,
   paymentsEnabled,
   orderId,
+  statusToken,
   amountMinor,
   currency,
   locale,
@@ -279,7 +294,7 @@ export default function StripePaymentClient({
         >
           <Link
             href={buildInAppPath(
-              `/checkout/success?orderId=${encodeURIComponent(orderId)}`
+              `/checkout/success?orderId=${encodeURIComponent(orderId)}${statusToken ? `&statusToken=${encodeURIComponent(statusToken)}` : ''}`
             )}
             className={cn(SHOP_HERO_CTA, 'w-full sm:w-auto')}
           >
@@ -340,7 +355,11 @@ export default function StripePaymentClient({
             </p>
           </div>
 
-          <StripePaymentForm orderId={orderId} locale={locale} />
+          <StripePaymentForm
+            orderId={orderId}
+            locale={locale}
+            statusToken={statusToken}
+          />
         </div>
       </Elements>
     </section>

frontend/app/[locale]/shop/checkout/payment/[orderId]/page.tsx

@@ -3,10 +3,12 @@ import { getTranslations } from 'next-intl/server';
 
 import { ClearCartOnMount } from '@/components/shop/ClearCartOnMount';
 import { Link } from '@/i18n/routing';
-import { getStripeEnv } from '@/lib/env/stripe';
+import {
+  getStripeEnv,
+  isPaymentsEnabled as isStripePaymentsEnabled,
+} from '@/lib/env/stripe';
 import { logError } from '@/lib/logging';
-import { OrderNotFoundError } from '@/lib/services/errors';
-import { getOrderSummary } from '@/lib/services/orders';
+import { getCheckoutPaymentPageOrderSummary } from '@/lib/services/orders';
 import { ensureStripePaymentIntentForOrder } from '@/lib/services/orders/payment-attempts';
 import { formatMoney } from '@/lib/shop/currency';
 import {
@@ -48,6 +50,15 @@ function resolveClientSecret(
   return raw;
 }
 
+function parseStatusToken(
+  searchParams?: Record<string, string | string[] | undefined>
+): string | null {
+  const raw = searchParams?.statusToken;
+  const value = Array.isArray(raw) ? raw[0] : raw;
+  const normalized = (value ?? '').trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
 async function buildStatusMessage(status: string) {
   const t = await getTranslations('shop.checkout.payment.statusMessages');
 
@@ -56,6 +67,10 @@ async function buildStatusMessage(status: string) {
   return t('completePayment');
 }
 
+function canInitializeStripeForPaymentStatus(status: string): boolean {
+  return status === 'pending' || status === 'requires_payment';
+}
+
 function shouldClearCart(
   searchParams?: Record<string, string | string[] | undefined>
 ): boolean {
@@ -160,6 +175,10 @@ export default async function PaymentPage(props: PaymentPageProps) {
   const cc = clearCart ? '&clearCart=1' : '';
   const { locale } = params;
   const shopBase = `/shop`;
+  const statusToken = parseStatusToken(searchParams);
+  const statusTokenQuery = statusToken
+    ? `&statusToken=${encodeURIComponent(statusToken)}`
+    : '';
 
   const t = await getTranslations('shop.checkout');
 
@@ -184,51 +203,56 @@ export default async function PaymentPage(props: PaymentPageProps) {
     );
   }
 
-  let order: Awaited<ReturnType<typeof getOrderSummary>>;
+  const orderAccess = await getCheckoutPaymentPageOrderSummary({
+    orderId,
+    statusToken,
+  });
 
-  try {
-    order = await getOrderSummary(orderId);
-  } catch (error) {
-    if (error instanceof OrderNotFoundError) {
+  if (!orderAccess.ok) {
+    if (orderAccess.code === 'STATUS_TOKEN_MISCONFIGURED') {
       return (
         <PageShell
-          title={t('errors.orderNotFound')}
-          description={t('notFoundOrder.message')}
-        >
-          <nav
-            className="mt-6 flex justify-center gap-3"
-            aria-label="Next steps"
-          >
-            <Link href={`${shopBase}/cart`} className={SHOP_OUTLINE_BTN}>
-              {t('actions.goToCart')}
-            </Link>
-
-            <HeroCtaLink href={`${shopBase}/products`}>
-              {t('actions.continueShopping')}
-            </HeroCtaLink>
-          </nav>
-        </PageShell>
+          title={t('errors.unableToLoad')}
+          description={t('errors.tryAgainLater')}
+        />
       );
     }
 
     return (
       <PageShell
-        title={t('errors.unableToLoad')}
-        description={t('errors.tryAgainLater')}
-      />
+        title={t('errors.orderNotFound')}
+        description={t('notFoundOrder.message')}
+      >
+        <nav className="mt-6 flex justify-center gap-3" aria-label="Next steps">
+          <Link href={`${shopBase}/cart`} className={SHOP_OUTLINE_BTN}>
+            {t('actions.goToCart')}
+          </Link>
+
+          <HeroCtaLink href={`${shopBase}/products`}>
+            {t('actions.continueShopping')}
+          </HeroCtaLink>
+        </nav>
+      </PageShell>
     );
   }
+  const order = orderAccess.order;
 
+  const paymentsEnabled = isStripePaymentsEnabled({
+    requirePublishableKey: true,
+    respectStripePaymentsFlag: true,
+  });
   const stripeEnv = getStripeEnv();
-  const paymentsEnabled =
-    stripeEnv.paymentsEnabled && Boolean(stripeEnv.publishableKey);
 
   let clientSecret = resolveClientSecret(searchParams);
   const publishableKey = paymentsEnabled ? stripeEnv.publishableKey : null;
+  const shouldInitStripePaymentIntent = canInitializeStripeForPaymentStatus(
+    order.paymentStatus
+  );
 
   if (
     paymentsEnabled &&
     publishableKey &&
+    shouldInitStripePaymentIntent &&
     (!clientSecret || !clientSecret.trim())
   ) {
     const existingPi = order.paymentIntentId?.trim() ?? '';
@@ -265,7 +289,7 @@ export default async function PaymentPage(props: PaymentPageProps) {
             aria-label="Next steps"
           >
             <HeroCtaLink
-              href={`${shopBase}/checkout/success?orderId=${order.id}${cc}`}
+              href={`${shopBase}/checkout/success?orderId=${order.id}${statusTokenQuery}${cc}`}
             >
               {t('payment.viewConfirmation')}
             </HeroCtaLink>
@@ -338,6 +362,7 @@ export default async function PaymentPage(props: PaymentPageProps) {
             <StripePaymentClient
               clientSecret={clientSecret}
               orderId={order.id}
+              statusToken={statusToken}
               amountMinor={order.totalAmountMinor}
               currency={order.currency}
               publishableKey={publishableKey}