@ticketboothapp/booking 1.2.123 → 1.2.124

package/src/components/booking/useAdminChangeCheckoutController.ts

@@ -0,0 +1,806 @@
+import { useCallback, useEffect, useRef, useState, type Dispatch, type SetStateAction } from 'react';
+import {
+  cancelReservation,
+  cancelReservationBestEffort,
+  createChangeBookingPaymentIntent,
+  createPaymentIntent,
+  describeStandardTourCapacityConflictMessage,
+  isInsufficientCapacityReserveError,
+  reportReserveCapacityConflictClientContext,
+  type AddOn,
+  type AdminFeAuthoritativeReceipt,
+  type Availability,
+  type ChangeBookingQuotePricingDriftDetail,
+  type ChangeBookingQuoteTicketPricingTrace,
+  type ItineraryDisplayStep,
+  type PricingConfig,
+  type Product,
+  type ReturnOption,
+} from '../../lib/booking-api';
+import {
+  changeFlowBalanceVsOriginal,
+} from '../../lib/booking/change-flow-pricing';
+import type { BookingSourceMetadata } from '../../lib/booking/source-metadata';
+import {
+  buildBookingSourceContext,
+  inferClientBookingSourceFromProductIds,
+} from '../../lib/booking/source-metadata';
+import { formatBookingRefForDisplay } from '../../lib/booking-ref';
+import type { OrderSummary, OrderSummaryTicketLine } from '../../lib/booking/pricing';
+import { BOOKING_FLOW_ABANDON_EVENT } from '../../providers/booking-dialog-provider';
+import { buildChangeBookingCheckoutBreakdown } from './change-booking-checkout-builders';
+import type { ChangeBookingServerPreview } from './change-booking-quote-state';
+import {
+  buildChangeBookingPaidCheckoutModalData,
+  type ChangeBookingSuccessUrlFactory,
+} from './change-booking-payment-modal-builders';
+import type { ChangeBookingFlowProps } from './booking-flow-types';
+import type { CheckoutModalLineItem } from './CheckoutModal';
+import type { Currency } from './CurrencySwitcher';
+import {
+  findMergedAvailabilityForSelection,
+  findMergedReturnVacancies,
+  getAvailabilityOptionId,
+} from './change-booking-flow-helpers';
+import type { ProviderDashboardChangeBookingPayload } from './provider-dashboard-change-booking';
+import {
+  bookingItemsFromQuantities,
+  buildAdminChangeProviderPayload,
+  type AdminChangeAddOnSelection,
+  type AdminChangeBookingItem,
+  type AdminChangeProviderAdditionalAdjustment,
+  type AdminChangeProviderLineOverride,
+} from './admin-change-provider-payload';
+import {
+  buildAdminChangePaymentChoiceData,
+  buildAdminChangePayNowCheckoutModalData,
+  confirmAdminChangeBookingWithoutPayment,
+  type AdminChangeCheckoutModalData,
+  type AdminChangePaymentChoiceData,
+} from './admin-change-payment-choice-runner';
+import {
+  confirmFreeAdminCustomerChange,
+  quoteAdminCustomerChangeForCheckout,
+} from './admin-change-customer-quote-runner';
+
+type AdminCustomReceiptLine = { label: string; amountInput: string; amountSign?: number };
+
+export interface AdminChangeLatestQuote {
+  priceDiff: number;
+  currency: Currency;
+  canProceed: boolean;
+  reasonIfBlocked?: string;
+  changeIntentId?: string;
+  quoteId?: string;
+  pricingQuoteInputsHash?: string;
+  quoteStatus?: string;
+  quoteExpiresAt?: string;
+  pricingVersion?: string;
+  quotedTotal?: number;
+  paymentCreditTotal?: number;
+  serverDisplay?: { total: number; subtotal: number; tax: number };
+  quotePreviousTotalCents?: number;
+  quoteNewTotalCents?: number;
+  serverPreview: ChangeBookingServerPreview;
+  pricingDriftDetail?: ChangeBookingQuotePricingDriftDetail;
+  ticketPricingTrace?: ChangeBookingQuoteTicketPricingTrace | null;
+}
+
+export interface UseAdminChangeCheckoutControllerParams {
+  selectedAvailability: Availability | null;
+  selectedReturnOption: ReturnOption | null;
+  product: Product;
+  quantities: Record<string, number>;
+  totalQuantity: number;
+  missingRequiredReturnSelection: boolean;
+  isProviderDashboardChange: boolean;
+  isChangeBookingContext: boolean;
+  isCustomerSelfServeChange: boolean;
+  isAdmin: boolean;
+  email: string;
+  firstName: string;
+  lastName: string;
+  pickupLocationId: string | null;
+  pickupLocationSkipped: boolean;
+  bookingSourceAttribution: Partial<BookingSourceMetadata>;
+  partnerPortalBooking: boolean;
+  bookingAppMode?: string;
+  t: (key: string) => string;
+  currency: Currency;
+  originalReceipt: ChangeBookingFlowProps['originalReceipt'];
+  initialValues: ChangeBookingFlowProps['initialValues'];
+  addOnSelections: AdminChangeAddOnSelection[];
+  adminCustomLinesAsAdditionalAdjustments: AdminChangeProviderAdditionalAdjustment[];
+  useAdminFeAuthoritativeQuote: boolean;
+  adminFeAuthoritativeReceipt: AdminFeAuthoritativeReceipt;
+  changeFlowClientEstimateDue: number;
+  latestChangeQuote: AdminChangeLatestQuote | null;
+  setLatestChangeQuote: Dispatch<SetStateAction<AdminChangeLatestQuote | null>>;
+  changeFlowNewBookingTotal: number;
+  effectiveSubtotalForCheckout: number;
+  effectiveTax: number;
+  changeFlowInitialTicketCount: number;
+  onChangeBooking?: ChangeBookingFlowProps['onChangeBooking'];
+  cancellationPolicyId: string | null;
+  appliedPromoCode: string | null;
+  displayChangeFlowProposedTotalWithEditableLines: number;
+  providerPricingOverrides: AdminChangeProviderLineOverride[];
+  mergedProviderAdditionalAdjustments: AdminChangeProviderAdditionalAdjustment[];
+  providerApplyAuthoritativeReceipt?: ProviderDashboardChangeBookingPayload['authoritativeReceipt'];
+  onSuccess?: ChangeBookingFlowProps['onSuccess'];
+  totalPrice: number;
+  computeItineraryDisplayForStorage: () => ItineraryDisplayStep[] | null;
+  computeItineraryDisplay: () => ItineraryDisplayStep[] | null;
+  effectivePromoDiscountAmount: number;
+  tax: number;
+  ticketLineItemsForChangeFlowDisplay: OrderSummaryTicketLine[];
+  checkoutReturnLineAmount: number;
+  cancellationPolicyFee: number;
+  effectiveCancellationPolicyLabel: string;
+  addOns: AddOn[];
+  feeLineItems: OrderSummary['feeLineItems'];
+  adminCustomReceiptLines: AdminCustomReceiptLine[];
+  isTaxIncludedInPrice: boolean;
+  originalReceiptPromoAdjustment: {
+    amount: number;
+    label: string | null;
+    type: 'PROMO_CODE' | 'GIFT_CARD' | 'VOUCHER' | 'DISCOUNT';
+  };
+  effectivePromoLineType: string;
+  lockedPromoCode: string | null;
+  termsAcceptedAt: string | null;
+  skipConfirmationCommunications: boolean;
+  disableAutoCommunications: boolean;
+  checkoutModalTicketLinesDisplay: CheckoutModalLineItem[];
+  feeLineItemsWithAddOns: OrderSummary['feeLineItems'];
+  pricingConfig: PricingConfig | null;
+  getSuccessUrl?: ChangeBookingSuccessUrlFactory;
+  reloadAvailabilitiesAfterReserveConflict: () => Promise<Availability[]>;
+  selectedDate: string;
+  setLoading: (loading: boolean) => void;
+  setError: (error: string) => void;
+  onShowManage?: (params: { ref: string; lastName: string }) => void;
+}
+
+function updatePendingChangeBookingSession({
+  totalPrice,
+  currency,
+  selectedAvailability,
+}: {
+  totalPrice: number;
+  currency: Currency;
+  selectedAvailability: Availability;
+}): void {
+  try {
+    const storedBooking = sessionStorage.getItem('pendingBooking');
+    if (!storedBooking) return;
+    const booking = JSON.parse(storedBooking);
+    booking.totalPrice = totalPrice;
+    booking.currency = currency || selectedAvailability.currency || 'CAD';
+    sessionStorage.setItem('pendingBooking', JSON.stringify(booking));
+  } catch (e) {
+    console.warn('Failed to update booking data', e);
+  }
+}
+
+export function useAdminChangeCheckoutController({
+  selectedAvailability,
+  selectedReturnOption,
+  product,
+  quantities,
+  totalQuantity,
+  missingRequiredReturnSelection,
+  isProviderDashboardChange,
+  isChangeBookingContext,
+  isCustomerSelfServeChange,
+  isAdmin,
+  email,
+  firstName,
+  lastName,
+  pickupLocationId,
+  pickupLocationSkipped,
+  bookingSourceAttribution,
+  partnerPortalBooking,
+  bookingAppMode,
+  t,
+  currency,
+  originalReceipt,
+  initialValues,
+  addOnSelections,
+  adminCustomLinesAsAdditionalAdjustments,
+  useAdminFeAuthoritativeQuote,
+  adminFeAuthoritativeReceipt,
+  changeFlowClientEstimateDue,
+  latestChangeQuote,
+  setLatestChangeQuote,
+  changeFlowNewBookingTotal,
+  effectiveSubtotalForCheckout,
+  effectiveTax,
+  changeFlowInitialTicketCount,
+  onChangeBooking,
+  cancellationPolicyId,
+  appliedPromoCode,
+  displayChangeFlowProposedTotalWithEditableLines,
+  providerPricingOverrides,
+  mergedProviderAdditionalAdjustments,
+  providerApplyAuthoritativeReceipt,
+  onSuccess,
+  totalPrice,
+  computeItineraryDisplayForStorage,
+  computeItineraryDisplay,
+  effectivePromoDiscountAmount,
+  tax,
+  ticketLineItemsForChangeFlowDisplay,
+  checkoutReturnLineAmount,
+  cancellationPolicyFee,
+  effectiveCancellationPolicyLabel,
+  addOns,
+  feeLineItems,
+  adminCustomReceiptLines,
+  isTaxIncludedInPrice,
+  originalReceiptPromoAdjustment,
+  effectivePromoLineType,
+  lockedPromoCode,
+  termsAcceptedAt,
+  skipConfirmationCommunications,
+  disableAutoCommunications,
+  checkoutModalTicketLinesDisplay,
+  feeLineItemsWithAddOns,
+  pricingConfig,
+  getSuccessUrl,
+  reloadAvailabilitiesAfterReserveConflict,
+  selectedDate,
+  setLoading,
+  setError,
+  onShowManage,
+}: UseAdminChangeCheckoutControllerParams) {
+  const [showCheckoutModal, setShowCheckoutModal] = useState(false);
+  const [checkoutClientSecret, setCheckoutClientSecret] = useState('');
+  const [checkoutModalData, setCheckoutModalData] = useState<AdminChangeCheckoutModalData | null>(null);
+  const [showAdminPaymentChoice, setShowAdminPaymentChoice] = useState(false);
+  const [adminChoiceData, setAdminChoiceData] = useState<AdminChangePaymentChoiceData | null>(null);
+  const pendingReservationRef = useRef<{ reservationReference: string } | null>(null);
+  const paymentSubmitInFlightRef = useRef(false);
+
+  const cancelPendingReservation = useCallback(() => {
+    if (paymentSubmitInFlightRef.current) return;
+    const pending = pendingReservationRef.current;
+    if (pending) {
+      pendingReservationRef.current = null;
+      cancelReservation(pending.reservationReference).catch(() => {});
+    }
+    setShowCheckoutModal(false);
+    setCheckoutModalData(null);
+    setCheckoutClientSecret('');
+  }, []);
+
+  const cancelPendingReservationBestEffort = useCallback(() => {
+    if (paymentSubmitInFlightRef.current) return;
+    const pending = pendingReservationRef.current;
+    if (pending) {
+      pendingReservationRef.current = null;
+      cancelReservationBestEffort(pending.reservationReference);
+    }
+    setShowCheckoutModal(false);
+    setCheckoutModalData(null);
+    setCheckoutClientSecret('');
+  }, []);
+
+  useEffect(() => {
+    const handleAbandon = () => {
+      cancelPendingReservation();
+    };
+    window.addEventListener(BOOKING_FLOW_ABANDON_EVENT, handleAbandon);
+    return () => window.removeEventListener(BOOKING_FLOW_ABANDON_EVENT, handleAbandon);
+  }, [cancelPendingReservation]);
+
+  useEffect(() => {
+    const handlePageHide = () => {
+      cancelPendingReservationBestEffort();
+    };
+    window.addEventListener('pagehide', handlePageHide);
+    return () => window.removeEventListener('pagehide', handlePageHide);
+  }, [cancelPendingReservationBestEffort]);
+
+  const buildProviderChangePayload = (
+    availabilityProductOptionId: string,
+    bookingItems: AdminChangeBookingItem[],
+  ): ProviderDashboardChangeBookingPayload | null => {
+    return buildAdminChangeProviderPayload({
+      selectedAvailability,
+      availabilityProductOptionId,
+      bookingItems,
+      product,
+      pickupLocationId,
+      selectedReturnOption,
+      addOnSelections,
+      cancellationPolicyId,
+      initialCancellationPolicyId: initialValues?.cancellationPolicyId ?? null,
+      appliedPromoCode,
+      newTotalAmount: displayChangeFlowProposedTotalWithEditableLines,
+      providerPricingOverrides,
+      mergedProviderAdditionalAdjustments,
+      providerApplyAuthoritativeReceipt,
+      previousPassengerCount: changeFlowInitialTicketCount,
+      previousAvailabilityId: initialValues?.availabilityId ?? null,
+      previousReturnAvailabilityId: initialValues?.returnAvailabilityId ?? null,
+    });
+  };
+
+  const finishManageFlow = (bookingReference: string) => {
+    const ref = formatBookingRefForDisplay(bookingReference);
+    const trimmedLastName = lastName.trim();
+    if (onShowManage) {
+      onShowManage({ ref, lastName: trimmedLastName });
+      return;
+    }
+    const params = new URLSearchParams({
+      ref,
+      lastName: trimmedLastName,
+      booking_complete: '1',
+    });
+    window.location.href = `/manage-booking?${params.toString()}`;
+  };
+
+  const handleCheckout = async () => {
+    if (!selectedAvailability || totalQuantity === 0) {
+      setError(t('booking.selectTimeAndTickets'));
+      return;
+    }
+    if (missingRequiredReturnSelection) {
+      setError('Please select a return time for this product.');
+      return;
+    }
+    if (isProviderDashboardChange && !isChangeBookingContext) {
+      setError('Provider change checkout requires the original booking reference.');
+      return;
+    }
+
+    const skipContactFields = isProviderDashboardChange;
+    if (!skipContactFields) {
+      if (!email) {
+        setError(t('booking.enterEmail') || 'Please enter your email address');
+        return;
+      }
+
+      if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+        setError(t('booking.invalidEmail') || 'Please enter a valid email address');
+        return;
+      }
+
+      if (!firstName?.trim()) {
+        setError(t('booking.enterFirstName') || 'Please enter your first name');
+        return;
+      }
+
+      if (!lastName?.trim()) {
+        setError(t('booking.enterLastName') || 'Please enter your last name');
+        return;
+      }
+    }
+
+    if (product.pickupLocations && product.pickupLocations.length > 0 && !pickupLocationId && !pickupLocationSkipped) {
+      setError(t('booking.selectPickupLocation'));
+      return;
+    }
+
+    setLoading(true);
+    setError('');
+    paymentSubmitInFlightRef.current = false;
+
+    try {
+      const bookingItems = bookingItemsFromQuantities(quantities);
+      const availabilityProductOptionId = getAvailabilityOptionId(selectedAvailability);
+
+      if (!availabilityProductOptionId) {
+        setError('No product option selected');
+        setLoading(false);
+        return;
+      }
+
+      const bookingSourceContext = buildBookingSourceContext(bookingSourceAttribution, {
+        clientChannelSource: inferClientBookingSourceFromProductIds(
+          product.productId,
+          availabilityProductOptionId,
+        ),
+        forcePartnerPortalChannel: partnerPortalBooking,
+        forceDashboardSource: bookingAppMode === 'provider-dashboard',
+      });
+
+      const selectedPickupLocation = pickupLocationId
+        ? product.pickupLocations?.find((loc) => loc.id === pickupLocationId)
+        : null;
+      let changeIntentIdForCheckout: string | undefined;
+      let changeBookingReferenceForPaidFlow: string | undefined;
+      let confirmedChangeAmountDueForCheckout: number | null = null;
+
+      if (isCustomerSelfServeChange) {
+        const quoteResult = await quoteAdminCustomerChangeForCheckout({
+          bookingReference: initialValues?.bookingReference,
+          lastName,
+          parentProductId: product.productId,
+          availabilityProductOptionId,
+          selectedAvailability,
+          pickupLocationId: pickupLocationId || null,
+          selectedReturnOption,
+          bookingItems,
+          addOnSelections,
+          manualLineAdjustments: adminCustomLinesAsAdditionalAdjustments,
+          useAdminFeAuthoritativeQuote,
+          adminFeAuthoritativeReceipt,
+          originalReceiptTotal: originalReceipt?.total ?? null,
+          changeFlowClientEstimateDue,
+          latestServerDisplayTotal: latestChangeQuote?.serverDisplay?.total ?? null,
+          changeFlowNewBookingTotal,
+          effectiveSubtotalForCheckout,
+          effectiveTax,
+          changeFlowInitialTicketCount,
+          previousAvailabilityId: initialValues?.availabilityId ?? null,
+          previousReturnAvailabilityId: initialValues?.returnAvailabilityId ?? null,
+          currency,
+        });
+        changeBookingReferenceForPaidFlow = quoteResult.bookingReference;
+        setLatestChangeQuote(quoteResult.mergedQuote);
+        confirmedChangeAmountDueForCheckout = quoteResult.decision.amountDueForCheckout;
+
+        if (quoteResult.decision.kind === 'free') {
+          if (onChangeBooking) {
+            const providerPayload = buildProviderChangePayload(availabilityProductOptionId, bookingItems);
+            if (!providerPayload) {
+              setError('No availability selected');
+              setLoading(false);
+              return;
+            }
+            await onChangeBooking(providerPayload);
+            onSuccess?.({ reservationReference: quoteResult.bookingReference });
+            setLoading(false);
+            return;
+          }
+
+          await confirmFreeAdminCustomerChange(quoteResult.decision.changeIntentId);
+          onSuccess?.({ reservationReference: quoteResult.bookingReference });
+          setLoading(false);
+          return;
+        }
+
+        changeIntentIdForCheckout = quoteResult.decision.changeIntentId;
+      }
+
+      pendingReservationRef.current = null;
+      updatePendingChangeBookingSession({
+        totalPrice,
+        currency,
+        selectedAvailability,
+      });
+
+      const datePart = selectedAvailability.dateTime.split('T')[0];
+      const timePart = selectedAvailability.dateTime.split('T')[1]?.substring(0, 5) || '00:00';
+      const itineraryDisplay = computeItineraryDisplayForStorage() ?? computeItineraryDisplay();
+      const taxForBreakdown = effectivePromoDiscountAmount > 0 ? effectiveTax : tax;
+      const amountDueForCheckout = isCustomerSelfServeChange
+        ? confirmedChangeAmountDueForCheckout ??
+          Math.max(
+            0,
+            changeFlowBalanceVsOriginal({
+              newTotal: displayChangeFlowProposedTotalWithEditableLines,
+              originalReceiptTotal: originalReceipt?.total ?? 0,
+              audience: 'admin',
+            }),
+          )
+        : totalPrice;
+      const checkoutBreakdown = buildChangeBookingCheckoutBreakdown({
+        ticketLineItems: ticketLineItemsForChangeFlowDisplay,
+        totalQuantity,
+        checkoutReturnLineAmount,
+        returnOptionLabel: t('booking.returnOption') || 'Return option',
+        personLabel: t('booking.person') || 'person',
+        peopleLabel: t('booking.people') || 'people',
+        cancellationPolicyFee,
+        cancellationPolicyLabel: effectiveCancellationPolicyLabel,
+        addOnSelections,
+        addOns,
+        feeLineItems,
+        customReceiptLines: adminCustomReceiptLines,
+        isTaxIncludedInPrice,
+        taxForBreakdown,
+        taxLabel: t('booking.tax') !== 'booking.tax' ? t('booking.tax') : 'Taxes and fees',
+        effectivePromoDiscountAmount,
+        appliedPromoCode,
+        discountLabel:
+          originalReceiptPromoAdjustment.label ||
+          originalReceipt?.promoLabel ||
+          (t('booking.discount') || 'Discount'),
+        promoLineType: effectivePromoLineType,
+        amountDueForCheckout,
+        currency,
+        roundingLabel: t('booking.rounding') || 'Rounding',
+      });
+
+      const paymentIntent = isCustomerSelfServeChange
+        ? await createChangeBookingPaymentIntent(
+            (() => {
+              const id = changeIntentIdForCheckout ?? latestChangeQuote?.changeIntentId;
+              if (!id) {
+                throw new Error('Missing change intent for payment.');
+              }
+              return id;
+            })(),
+          )
+        : await createPaymentIntent({
+            productId: product.productId,
+            optionId: availabilityProductOptionId,
+            date: datePart,
+            time: timePart,
+            quantity: totalQuantity,
+            customerEmail: email,
+            customerFirstName: firstName.trim() || undefined,
+            customerLastName: lastName.trim() || undefined,
+            currency,
+            travelerHotel: selectedPickupLocation?.name || undefined,
+            pickupLocationId: pickupLocationId || undefined,
+            itineraryDisplay: itineraryDisplay ?? undefined,
+            returnAvailabilityId: selectedReturnOption?.returnAvailabilityId,
+            promoCode: (lockedPromoCode || appliedPromoCode) || undefined,
+            cancellationPolicyId: cancellationPolicyId || undefined,
+            termsAcceptedAt: termsAcceptedAt ?? undefined,
+            checkoutBreakdown,
+            skipConfirmationCommunications: isAdmin && skipConfirmationCommunications ? true : undefined,
+            disableAutoCommunications: isAdmin && disableAutoCommunications ? true : undefined,
+            ...bookingSourceContext,
+          });
+
+      if (isAdmin) {
+        const adminReservationRef =
+          initialValues?.bookingReference?.trim() ??
+          changeBookingReferenceForPaidFlow ??
+          '';
+        if (!adminReservationRef) {
+          throw new Error('Missing reservation reference for admin payment flow');
+        }
+        setError('');
+        setAdminChoiceData(buildAdminChangePaymentChoiceData({
+          reservationReference: adminReservationRef,
+          checkoutBreakdown,
+          totalAmount: amountDueForCheckout,
+          datePart,
+          timePart,
+          availabilityProductOptionId,
+          itineraryDisplay: itineraryDisplay ?? undefined,
+          clientSecret: paymentIntent.clientSecret ?? '',
+          ticketLinesForModal: checkoutModalTicketLinesDisplay,
+          feeLineItems: feeLineItemsWithAddOns,
+          returnPriceAdjustment: checkoutReturnLineAmount,
+          cancellationPolicyFee,
+          cancellationPolicyLabel: effectiveCancellationPolicyLabel,
+          subtotal: effectiveSubtotalForCheckout,
+          tax: effectivePromoDiscountAmount > 0 ? effectiveTax : tax,
+          totalQuantity,
+          isTaxIncludedInPrice,
+          taxRate: pricingConfig?.taxRate ?? 0,
+          promoDiscountAmount: effectivePromoDiscountAmount > 0 ? effectivePromoDiscountAmount : 0,
+          discountLabel: appliedPromoCode
+            ? `Promo: ${appliedPromoCode}`
+            : (originalReceiptPromoAdjustment.label || originalReceipt?.promoLabel || undefined),
+        }));
+        setShowAdminPaymentChoice(true);
+        setLoading(false);
+        return;
+      }
+
+      setCheckoutClientSecret(paymentIntent.clientSecret ?? '');
+      setCheckoutModalData(
+        buildChangeBookingPaidCheckoutModalData({
+          bookingReference: changeBookingReferenceForPaidFlow,
+          lastName,
+          datePart,
+          ticketLines: checkoutModalTicketLinesDisplay,
+          feeLineItems: feeLineItemsWithAddOns,
+          returnPriceAdjustment: checkoutReturnLineAmount,
+          cancellationPolicyFee,
+          cancellationPolicyLabel: effectiveCancellationPolicyLabel,
+          subtotal: effectiveSubtotalForCheckout,
+          tax: effectivePromoDiscountAmount > 0 ? effectiveTax : tax,
+          total: amountDueForCheckout,
+          totalQuantity,
+          isTaxIncludedInPrice,
+          taxRate: pricingConfig?.taxRate ?? 0,
+          promoDiscountAmount: effectivePromoDiscountAmount > 0 ? effectivePromoDiscountAmount : 0,
+          discountLabel: appliedPromoCode
+            ? `Promo: ${appliedPromoCode}`
+            : (originalReceiptPromoAdjustment.label || originalReceipt?.promoLabel || undefined),
+          previousTotal: isCustomerSelfServeChange ? originalReceipt?.total : undefined,
+          newTotal:
+            isCustomerSelfServeChange && originalReceipt
+              ? displayChangeFlowProposedTotalWithEditableLines
+              : undefined,
+          successUrl: {
+            enabled: isCustomerSelfServeChange,
+            bookingReference: changeBookingReferenceForPaidFlow,
+            lastName,
+            datePart,
+            changeIntentId: changeIntentIdForCheckout,
+            preferHostSuccessUrl: bookingAppMode === 'provider-dashboard',
+            getSuccessUrl,
+          },
+        }),
+      );
+      setShowCheckoutModal(true);
+      setLoading(false);
+    } catch (err) {
+      if (isInsufficientCapacityReserveError(err)) {
+        try {
+          const merged = await reloadAvailabilitiesAfterReserveConflict();
+          const outbound = findMergedAvailabilityForSelection(merged, selectedAvailability);
+          const outboundVacancies = outbound?.vacancies ?? null;
+          const returnVacancies = findMergedReturnVacancies(outbound, selectedReturnOption);
+          setError(
+            describeStandardTourCapacityConflictMessage({
+              partySize: totalQuantity,
+              outboundVacancies,
+              returnVacancies,
+              hasReturnSelection: !!selectedReturnOption,
+            }),
+          );
+          reportReserveCapacityConflictClientContext({
+            flow: 'standard_tour',
+            productId: product.productId,
+            selectedDate: selectedDate || null,
+            outboundDateTime: selectedAvailability?.dateTime ?? null,
+            outboundVacanciesAfterRefresh: outboundVacancies,
+            returnVacanciesAfterRefresh: returnVacancies,
+            partySizeOrPassengers: totalQuantity,
+            hasReturnSelection: !!selectedReturnOption,
+            returnAvailabilityId: selectedReturnOption?.returnAvailabilityId ?? null,
+            reloadAvailabilitiesSucceeded: true,
+          });
+        } catch (reloadErr) {
+          setError(
+            describeStandardTourCapacityConflictMessage({
+              partySize: totalQuantity,
+              outboundVacancies: null,
+              returnVacancies: null,
+              hasReturnSelection: !!selectedReturnOption,
+            }),
+          );
+          reportReserveCapacityConflictClientContext({
+            flow: 'standard_tour',
+            productId: product.productId,
+            selectedDate: selectedDate || null,
+            outboundDateTime: selectedAvailability?.dateTime ?? null,
+            outboundVacanciesAfterRefresh: null,
+            returnVacanciesAfterRefresh: null,
+            partySizeOrPassengers: totalQuantity,
+            hasReturnSelection: !!selectedReturnOption,
+            returnAvailabilityId: selectedReturnOption?.returnAvailabilityId ?? null,
+            reloadAvailabilitiesSucceeded: false,
+            reloadErrorMessage:
+              reloadErr instanceof Error ? reloadErr.message : String(reloadErr),
+          });
+        }
+        setLoading(false);
+        return;
+      }
+      setError(err instanceof Error ? err.message : 'Something went wrong');
+      setLoading(false);
+    }
+  };
+
+  const handleConfirmWithoutPayment = async () => {
+    if (!adminChoiceData) return;
+    setLoading(true);
+    setError('');
+    try {
+      if (onChangeBooking) {
+        if (!selectedAvailability) {
+          setError('No availability selected');
+          setLoading(false);
+          return;
+        }
+        const bookingItems = bookingItemsFromQuantities(quantities);
+        const availabilityProductOptionId =
+          adminChoiceData.availabilityProductOptionId ||
+          getAvailabilityOptionId(selectedAvailability);
+        if (!availabilityProductOptionId) {
+          setError('No product option selected');
+          setLoading(false);
+          return;
+        }
+        const providerPayload = buildProviderChangePayload(availabilityProductOptionId, bookingItems);
+        if (!providerPayload) {
+          setError('No availability selected');
+          setLoading(false);
+          return;
+        }
+        await onChangeBooking(providerPayload);
+        const bookRef = initialValues?.bookingReference?.trim() || adminChoiceData.reservationReference;
+        setShowAdminPaymentChoice(false);
+        setAdminChoiceData(null);
+        onSuccess?.({ reservationReference: bookRef });
+        finishManageFlow(bookRef);
+        setLoading(false);
+        return;
+      }
+
+      if (isChangeBookingContext) {
+        setError(
+          'Confirming a booking change without payment requires your dashboard to pass the provider change handler (onChangeBooking). Use Pay now to complete this change, or wire onChangeBooking in the embed.',
+        );
+        setLoading(false);
+        return;
+      }
+
+      const result = await confirmAdminChangeBookingWithoutPayment({
+        adminChoiceData,
+        bookingSourceAttribution,
+        partnerPortalBooking,
+        forceDashboardSource: bookingAppMode === 'provider-dashboard',
+        productId: product.productId,
+        email,
+        firstName,
+        lastName,
+        currency,
+        travelerHotel: product.pickupLocations?.find((loc) => loc.id === pickupLocationId)?.name || undefined,
+        pickupLocationId: pickupLocationId || undefined,
+        termsAcceptedAt,
+        skipConfirmationCommunications,
+        disableAutoCommunications,
+      });
+      pendingReservationRef.current = null;
+      setShowAdminPaymentChoice(false);
+      setAdminChoiceData(null);
+      onSuccess?.({ reservationReference: adminChoiceData.reservationReference });
+      if (onShowManage) {
+        onShowManage({ ref: result.displayReference, lastName: result.lastName });
+      } else {
+        const params = new URLSearchParams({
+          ref: result.displayReference,
+          lastName: result.lastName,
+          booking_complete: '1',
+        });
+        window.location.href = `/manage-booking?${params.toString()}`;
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to confirm booking');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handlePayNow = () => {
+    if (!adminChoiceData) return;
+    setShowAdminPaymentChoice(false);
+    setCheckoutClientSecret(adminChoiceData.clientSecret);
+    setCheckoutModalData(buildAdminChangePayNowCheckoutModalData(adminChoiceData, lastName));
+    setShowCheckoutModal(true);
+    setAdminChoiceData(null);
+  };
+
+  const handlePaymentSubmitStart = useCallback(() => {
+    paymentSubmitInFlightRef.current = true;
+  }, []);
+
+  const handlePaymentSubmitError = useCallback(() => {
+    paymentSubmitInFlightRef.current = false;
+  }, []);
+
+  const handleAdminPaymentChoiceCancel = useCallback(() => {
+    setShowAdminPaymentChoice(false);
+    setAdminChoiceData(null);
+    setError('');
+  }, [setError]);
+
+  return {
+    showCheckoutModal,
+    checkoutClientSecret,
+    checkoutModalData,
+    showAdminPaymentChoice,
+    adminChoiceData,
+    cancelPendingReservation,
+    handleCheckout,
+    handleConfirmWithoutPayment,
+    handlePayNow,
+    handlePaymentSubmitStart,
+    handlePaymentSubmitError,
+    handleAdminPaymentChoiceCancel,
+  };
+}