@12-apps/payments-frontend 3.34.3 → 3.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.34.3",
+  "version": "3.35.0",
   "type": "module",
   "sideEffects": false,
   "description": "Browser half of the vendor-agnostic payments platform: plug-and-play MUI components for the per-provider settings page (credential form from each provider's schema, masked hints, verify/enable) and the checkout page (PIX QR + polling, card tokenization, hosted-checkout redirect), plus the headless hooks and fetch clients they build on. Talks only to the host's payments HTTP surface — never to a provider directly. Microfrontend-ready: no app coupling, host injects theme and auth.",

package/src/components/checkout/card-view.tsx

@@ -8,6 +8,7 @@ import {
   type CardTokenizationConfig,
 } from "../../card";
 
+import { useRefreshOnCartChanged } from "./cart-changed";
 import { useCheckoutCopy } from "./copy-context";
 import { UNRESOLVED_CODE } from "./failure-codes";
 import { StalledWait } from "./stalled-wait";
@@ -192,11 +193,11 @@ export function CardView({
     freshInstrument,
     { tenantSlug, basket },
   );
-  // A charge NOBODY can confirm yet is not a decline (FUT-563). Some provider
-  // may be holding the buyer's money, so it gets its own presentation: the
-  // danger heading "Não foi possível pagar" contradicts the body's "não pague
-  // de novo" and pushes the buyer toward exactly the retry it forbids.
+  // A charge NOBODY can confirm yet is not a decline (FUT-563): a provider may
+  // hold the money, and "Não foi possível pagar" over "não pague de novo"
+  // pushes the buyer toward exactly the retry it forbids.
   const unresolved = cc.errorCode === UNRESOLVED_CODE;
+  useRefreshOnCartChanged(cc.errorCode); // re-priced by the host (FUT-1139)
 
   if (cc.submitted) {
     return <SubmittedState card={cc} />;

package/src/components/checkout/cart-changed.tsx

@@ -0,0 +1,273 @@
+import { Box } from "@mui/material";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type JSX,
+  type ReactNode,
+} from "react";
+
+import type { CheckoutBasketIdentity } from "./basket";
+import { useCheckoutCopy } from "./copy-context";
+import type {
+  BuyerInfo,
+  CheckoutOrder,
+  CreateOrderRequest,
+  CreateOrderResult,
+  PaymentMethod,
+} from "./types";
+import { useCheckoutComponents } from "./ui";
+
+/**
+ * THE CART MOVED UNDER A PREPARED PAYMENT (FUT-1139).
+ *
+ * An order is raised the moment the buyer picks a method, and it prices the
+ * cart as it stood THEN. Another tab can add a line, a store can move a price,
+ * a product can stop selling — and the card charge or the PIX code on screen
+ * still asks for the old amount. Paying it settles the old order and the
+ * server closes the cart, so whatever changed was neither charged nor kept.
+ *
+ * Two halves, both here:
+ *
+ * - the SERVER refuses a card charge whose order no longer matches the cart,
+ *   with {@link CART_CHANGED_CODE}, after re-pricing the order to the cart as it
+ *   stands. The card form then re-reads that order, so the pay bar shows the
+ *   amount that will actually be charged before the buyer presses it again;
+ * - the SCREEN notices on its own that the basket it was raised from is not the
+ *   basket in front of it (the host's signature, `./basket.ts`), and says so
+ *   with one control that brings the payment up to date. That is the only
+ *   warning a PIX buyer can get: a QR code is paid outside the app.
+ */
+
+/** The refusal a host answers when the order no longer prices the cart. */
+export const CART_CHANGED_CODE = "CART_CHANGED";
+
+interface RaisedFrom {
+  order: CheckoutOrder;
+  signature: string | null;
+}
+
+/**
+ * Whether the basket in front of the checkout is no longer the one `order` was
+ * raised from.
+ *
+ * The basket is recorded when the ORDER changes — a re-raise or a refresh
+ * hands back a new object, so it is re-recorded and the warning clears — and
+ * only once the host's cart has answered (`ready`): a loading cart reports the
+ * EMPTY signature, and recording that would read every real cart as changed.
+ * A host that passes no basket never sees the warning, which is the behaviour
+ * before this existed.
+ */
+export function useBasketChanged(
+  order: CheckoutOrder | null,
+  basket: CheckoutBasketIdentity | undefined,
+): boolean {
+  const [raised, setRaised] = useState<RaisedFrom | null>(null);
+  const ready = basket?.ready === true;
+  const signature = basket?.signature ?? null;
+  useEffect(() => {
+    setRaised((prev) => {
+      if (order === null) return null;
+      if (prev?.order === order || !ready) return prev;
+      return { order, signature };
+    });
+    // A cart change re-runs this and keeps `prev`: only a NEW order records, so
+    // the raised basket never follows the cart it is compared with.
+  }, [order, ready, signature]);
+  if (order === null || raised === null || raised.order !== order || !ready) return false;
+  return raised.signature !== signature;
+}
+
+/** The step's "bring this payment up to date", with what the buyer must see of it. */
+export interface OrderRefresh {
+  run: () => void;
+  /** A refresh is on its way — the control waits rather than firing twice. */
+  pending: boolean;
+  /** The last refresh failed, in the host's words; null otherwise. */
+  error: string | null;
+}
+
+/**
+ * Re-price the order IN PLACE: ask the host for the order again and swap it in
+ * without dropping the one on screen first.
+ *
+ * Unlike raising a payment (`./start-payment.ts`), nothing is cleared before
+ * the answer: the card form keeps what the buyer typed, and the refusal that
+ * sent us here stays on screen while the amount under it corrects itself. The
+ * answer is routed exactly as a raise is (`route`, which is
+ * `routeRaisedOrder`), so a re-priced order that is already PAID or must finish
+ * on the provider's page goes where a raised one would.
+ *
+ * Three guards, each against something a review found:
+ *
+ * - one refresh at a time — a second tap while one is out does nothing;
+ * - an answer for an order the screen has moved on from (the buyer switched
+ *   method, or raised the payment again) is DROPPED rather than resurrected;
+ * - a failure is KEPT here and shown by {@link CartChangedBoundary}, because the
+ *   step's own create-error slot is hidden whenever an order is on screen.
+ */
+export function useOrderRefresh(input: {
+  order: CheckoutOrder | null;
+  buyer: BuyerInfo;
+  saveProfile: boolean;
+  createOrder: (request: CreateOrderRequest) => Promise<CreateOrderResult>;
+  route: (order: CheckoutOrder) => void;
+}): OrderRefresh {
+  const { order, buyer, saveProfile, createOrder, route } = input;
+  const offline = useCheckoutCopy().screens.transport.offline;
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const current = useRef(order);
+  const inFlight = useRef(false);
+  useEffect(() => {
+    current.current = order;
+  }, [order]);
+  // A failure is about the order it was raised for: once another is on screen
+  // (a method switch, a fresh raise) it is no longer true, and must not stay up.
+  const orderId = order?.orderId;
+  const method = order?.method;
+  useEffect(() => {
+    setError(null);
+  }, [orderId, method]);
+  const run = useCallback(() => {
+    if (!order || inFlight.current) return;
+    inFlight.current = true;
+    setPending(true);
+    setError(null);
+    void createOrder({ method: order.method, buyer, saveProfile })
+      .catch((): CreateOrderResult => ({ ok: false, error: { code: "NETWORK", message: offline, field: null } }))
+      .then((result) => {
+        inFlight.current = false;
+        setPending(false);
+        // The same order still on screen — by id and method, since a re-priced
+        // order comes back as a new object for the same id.
+        const now = current.current;
+        if (!now || now.orderId !== order.orderId || now.method !== order.method) return;
+        if (!result.ok) setError(result.error.message);
+        else route(result.data);
+      });
+  }, [order, buyer, saveProfile, createOrder, route, offline]);
+  return { run, pending, error };
+}
+
+/**
+ * How this step brings a payment up to date with the cart (FUT-1139): a PIX
+ * code is minted again — the amount is IN the code — and a card order is
+ * re-priced in place so the form keeps what was typed.
+ */
+export function paymentRefresh(
+  order: CheckoutOrder | null,
+  onGenerate: (method: PaymentMethod) => void,
+  onRefreshOrder: (() => void) | undefined,
+): (() => void) | null {
+  if (!order) return null;
+  if (order.method === "CARD" && onRefreshOrder) return onRefreshOrder;
+  return () => onGenerate(order.method);
+}
+
+const PaymentRefreshContext = createContext<(() => void) | null>(null);
+
+/** Hands the payment panes the step's "bring this payment up to date". */
+export function PaymentRefreshProvider({
+  refresh,
+  children,
+}: {
+  refresh: (() => void) | null;
+  children: ReactNode;
+}): JSX.Element {
+  return <PaymentRefreshContext.Provider value={refresh}>{children}</PaymentRefreshContext.Provider>;
+}
+
+/**
+ * The card pane's half: a charge the host refused with
+ * {@link CART_CHANGED_CODE} re-reads the order, once per refusal.
+ */
+export function useRefreshOnCartChanged(errorCode: string | null): void {
+  const refresh = useContext(PaymentRefreshContext);
+  // Held in a ref: the step hands down a fresh closure on every render, and
+  // keying the effect on it would re-fire the refresh after each re-price for
+  // as long as the refusal stays on screen.
+  const latest = useRef(refresh);
+  useEffect(() => {
+    latest.current = refresh;
+  }, [refresh]);
+  useEffect(() => {
+    if (errorCode === CART_CHANGED_CODE) latest.current?.();
+  }, [errorCode]);
+}
+
+/**
+ * The payment pane, with the step's warning above it when the cart moved, and
+ * the refresh handed down to the card form. Nothing changes on screen while the
+ * basket is the one the order was raised from.
+ */
+export function CartChangedBoundary({
+  order,
+  basket,
+  creating,
+  onGenerate,
+  refresh,
+  children,
+}: {
+  order: CheckoutOrder | null;
+  /** Absent for a settlement: it pays a balance, not the cart, so its basket is no signal. */
+  basket: CheckoutBasketIdentity | undefined;
+  creating: boolean;
+  onGenerate: (method: PaymentMethod) => void;
+  refresh: OrderRefresh | undefined;
+  children: ReactNode;
+}): JSX.Element {
+  const changed = useBasketChanged(order, basket) && !creating;
+  const run = paymentRefresh(order, onGenerate, refresh?.run);
+  const pending = refresh?.pending ?? false;
+  const error = refresh?.error ?? null;
+  // ONE tree shape whether or not the warning shows: wrapping the pane only
+  // while it does would remount the card form the moment the refresh lands,
+  // dropping what the buyer typed and the refusal that explains the new total.
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 3 }}>
+      {(changed || error) && run ? <CartChangedNotice onRefresh={run} pending={pending} error={error} /> : null}
+      <PaymentRefreshProvider refresh={run}>{children}</PaymentRefreshProvider>
+    </Box>
+  );
+}
+
+/** "Seu carrinho mudou" — what the step says, and the one thing to do about it. */
+function CartChangedNotice({
+  onRefresh,
+  pending = false,
+  error = null,
+}: {
+  onRefresh: () => void;
+  pending?: boolean;
+  /** A refresh that failed, in the host's words: said, with the same control to try again. */
+  error?: string | null;
+}): JSX.Element {
+  const { Alert, Button } = useCheckoutComponents();
+  const copy = useCheckoutCopy().screens.cartChanged;
+  return (
+    <Box data-testid="checkout-cart-changed" sx={{ display: "flex", flexDirection: "column", gap: 1.5 }}>
+      {error ? (
+        <Alert variant="danger" title={copy.refreshFailed} description={error} showIcon data-testid="checkout-cart-changed-error" />
+      ) : (
+        <Alert variant="warning" title={copy.heading} description={copy.support} showIcon />
+      )}
+      <Box>
+        <Button
+          variant="solid"
+          color="primary"
+          size="md"
+          onClick={onRefresh}
+          loading={pending}
+          disabled={pending}
+          dataTestId="checkout-cart-changed-refresh"
+        >
+          {copy.refreshAction}
+        </Button>
+      </Box>
+    </Box>
+  );
+}

package/src/components/checkout/checkout-flow.tsx

@@ -297,6 +297,7 @@ function PagamentoStep({
       errorField={c.errorField}
       errorCode={c.errorCode}
       onGenerate={(chosen) => void c.startPayment(chosen)}
+      refresh={c.refresh}
       onUseEmail={c.payWithEmail}
       // Set only for a skipped-Dados flow (the controller decides); the payer
       // block hides itself when it is absent.
@@ -307,8 +308,7 @@ function PagamentoStep({
       cartTotals={cart}
       totalOverride={settlementTotalOverride(settlement)}
       discountLines={cart.discountLines}
-      // Retrying a refused card: the saved card that failed is not chosen for
-      // them again (FUT-1145).
+      // Retrying a refused card: the failed saved card is not chosen again (FUT-1145).
       freshInstrument={c.freshInstrument}
       // The card path parks an order of its own for a 3-D Secure challenge, so
       // it needs the same basket the flow was mounted for (FUT-1213).

package/src/components/checkout/checkout-steps.tsx

@@ -3,6 +3,7 @@ import { useEffect, useRef, type JSX, type ReactNode } from "react";
 
 import type { CheckoutBasketIdentity } from "./basket";
 import { displayTotals, PayBarTotal } from "./checkout-totals";
+import { CartChangedBoundary, type OrderRefresh } from "./cart-changed";
 import { useCheckoutCopy } from "./copy-context";
 import { useMethodChoice } from "./method-choice";
 import { MethodPicker } from "./method-picker";
@@ -180,6 +181,11 @@ interface PaymentStepProps {
  */
   errorCode?: string | null;
   onGenerate: (method: PaymentMethod) => void;
+  /**
+   * Re-price the raised order IN PLACE, keeping the card form (FUT-1139). Absent,
+   * the step falls back to raising the payment again.
+   */
+  refresh?: OrderRefresh;
   onUseEmail: (email: string) => void;
   /**
    * Present ⇒ the buyer reached this step without a Dados step (FUT-465), so
@@ -240,6 +246,7 @@ export function PaymentStep({
   errorField,
   errorCode,
   onGenerate,
+  refresh,
   onUseEmail,
   onEditBuyer,
   providerConfig,
@@ -261,11 +268,8 @@ export function PaymentStep({
   return (
     <PixStageProvider stage={pixStage}>
       <Box sx={{ display: "flex", flexDirection: "column", gap: 3 }}>
-        {/* THE AMOUNT, before anything asks for it (FUT-1179). At the top rather
-            than in a sticky bar of its own: this step's actions belong to the
-            pane below it — the PIX code, the card form's own pay bar, the
-            hand-off button — and a second bar would put two "pay" controls on
-            one screen. */}
+        {/* THE AMOUNT, before anything asks for it (FUT-1179) — at the top, not in a
+            bar of its own: a second bar would put two "pay" controls on one screen. */}
         <PaymentStepTotal money={{ order, cartTotals, totalOverride, discountLines }} />
 
         {/* Self-hiding: renders only for a flow whose Dados step was skipped. */}
@@ -278,20 +282,22 @@ export function PaymentStep({
         )}
 
         <StepColumn full={order?.method === "PIX"}>
-          <PaymentBody
-            order={order}
-            buyer={buyer}
-            providerConfig={config}
-            method={method}
-            tenantSlug={tenantSlug}
-            onResolved={onResolved}
-            onStart={choice.onStart}
-            creating={creating}
-            pollIntervalMs={pollIntervalMs}
-            freshInstrument={freshInstrument}
-            basket={basket}
-            validateApplePayMerchant={validateApplePayMerchant}
-          />
+          <CartChangedBoundary {...{ order, creating, onGenerate, refresh }} basket={totalOverride ? undefined : basket}>
+            <PaymentBody
+              order={order}
+              buyer={buyer}
+              providerConfig={config}
+              method={method}
+              tenantSlug={tenantSlug}
+              onResolved={onResolved}
+              onStart={choice.onStart}
+              creating={creating}
+              pollIntervalMs={pollIntervalMs}
+              freshInstrument={freshInstrument}
+              basket={basket}
+              validateApplePayMerchant={validateApplePayMerchant}
+            />
+          </CartChangedBoundary>
         </StepColumn>
 
         <StepColumn>

package/src/components/checkout/mui-defaults.tsx

@@ -19,15 +19,21 @@ import {
   CircularProgress,
   FormControl,
   FormControlLabel,
+  FormHelperText,
   FormLabel,
+  InputLabel,
+  OutlinedInput,
   Radio,
   RadioGroup as MuiRadioGroup,
   Step,
   StepLabel,
   Stepper as MuiStepper,
-  TextField,
   Typography,
+  styled,
+  useThemeProps,
 } from '@mui/material';
+import type { TextFieldProps } from '@mui/material';
+import { useId } from 'react';
 import type { JSX } from 'react';
 
 import type {
@@ -93,25 +99,170 @@ function DefaultButton({ variant = 'solid', color = 'primary', size = 'md', full
   );
 }
 
-function DefaultInput({ label, type = 'text', inputMode, fullWidth, required, autoComplete, placeholder, maxLength, value, error, helperText, endAdornment, onChange, onBlur, ...rest }: CheckoutInputProps): JSX.Element {
-  return (
-    <TextField
-      label={label}
-      type={type}
-      size="small"
-      fullWidth={fullWidth}
-      required={required}
-      placeholder={placeholder}
-      value={value}
-      error={error}
-      helperText={helperText}
-      onChange={onChange}
-      onBlur={onBlur}
-      slotProps={{
+type OwnerState = Record<string, unknown>;
+type SlotProps = Record<string, unknown> | ((ownerState: OwnerState) => Record<string, unknown>) | undefined;
+
+/**
+ * `TextField`'s root, by name and with its `ownerState`: a theme's
+ * `components.MuiTextField` (`styleOverrides`, including functions reading
+ * `ownerState`, and `variants`) applies exactly as it did to `TextField`.
+ */
+const TextFieldRoot = styled(FormControl, {
+  name: 'MuiTextField',
+  slot: 'Root',
+  overridesResolver: (_props, styles) => styles.root,
+})<{ ownerState: OwnerState }>({});
+
+/** A theme's slot props may be a function of `ownerState`, as `useSlot` allows. */
+function slotPropsOf(slotProps: SlotProps, ownerState: OwnerState): Record<string, unknown> {
+  return (typeof slotProps === 'function' ? slotProps(ownerState) : slotProps) ?? {};
+}
+
+/** `TextField`'s `ownerState`, for the outlined, non-select field this slot is. */
+function ownerStateOf(props: TextFieldProps): OwnerState {
+  return {
+    ...props,
+    autoFocus: false,
+    color: props.color ?? 'primary',
+    disabled: props.disabled ?? false,
+    error: props.error ?? false,
+    fullWidth: props.fullWidth ?? false,
+    multiline: false,
+    required: props.required ?? false,
+    select: false,
+    variant: 'outlined',
+  };
+}
+
+/**
+ * The slot's own props, run through the theme's `MuiTextField` defaults the way
+ * `TextField` runs them (`useDefaultProps` is `useThemeProps` by another name).
+ */
+function useTextFieldProps({ label, type = 'text', inputMode, fullWidth, required, autoComplete, placeholder, maxLength, value, error, helperText, endAdornment, onChange, onBlur, ...rest }: CheckoutInputProps): TextFieldProps {
+  return useThemeProps({
+    name: 'MuiTextField',
+    props: {
+      label,
+      type,
+      size: 'small',
+      fullWidth,
+      required,
+      placeholder,
+      value,
+      error,
+      helperText,
+      onChange,
+      onBlur,
+      slotProps: {
         htmlInput: { inputMode, maxLength, autoComplete, 'data-testid': rest['data-testid'] },
         input: { endAdornment },
-      }}
-    />
+      },
+    } as TextFieldProps,
+  });
+}
+
+/**
+ * What `TextField` consumes by name rather than handing to its root. A key LIST
+ * rather than a destructure, which would bind every one of them only to drop it.
+ */
+const CONSUMED_BY_FIELD: ReadonlySet<string> = new Set([
+  'autoComplete', 'autoFocus', 'children', 'className', 'color', 'defaultValue', 'disabled', 'error',
+  'FormHelperTextProps', 'fullWidth', 'helperText', 'id', 'InputLabelProps', 'inputProps', 'InputProps',
+  'inputRef', 'label', 'maxRows', 'minRows', 'multiline', 'name', 'onBlur', 'onChange', 'onFocus',
+  'placeholder', 'required', 'rows', 'select', 'SelectProps', 'slotProps', 'slots', 'type', 'value',
+  'variant',
+]);
+
+/**
+ * The slot props as `TextField` resolves them: the legacy `InputProps`,
+ * `InputLabelProps`, `inputProps` and `FormHelperTextProps` first, then
+ * `slotProps` over them.
+ */
+function slotPropsFor(props: TextFieldProps): Record<string, SlotProps> {
+  return {
+    input: props.InputProps as SlotProps,
+    inputLabel: props.InputLabelProps as SlotProps,
+    htmlInput: props.inputProps as SlotProps,
+    formHelperText: props.FormHelperTextProps as SlotProps,
+    ...((props.slotProps ?? {}) as Record<string, SlotProps>),
+  };
+}
+
+/** The root: what `TextField` did not consume, then the props it hands the root by name. */
+function rootPropsOf(props: TextFieldProps, ownerState: OwnerState): Record<string, unknown> {
+  return {
+    ...Object.fromEntries(Object.entries(props).filter(([key]) => !CONSUMED_BY_FIELD.has(key))),
+    ownerState,
+    className: ['MuiTextField-root', (props.classes as { root?: string } | undefined)?.root, props.className]
+      .filter(Boolean)
+      .join(' '),
+    disabled: ownerState.disabled,
+    error: ownerState.error,
+    fullWidth: ownerState.fullWidth,
+    required: ownerState.required,
+    color: ownerState.color,
+    variant: 'outlined',
+  };
+}
+
+/** The input: the props `TextField` names, then the theme's and the slot's `input` slot props. */
+function inputPropsOf(props: TextFieldProps, ownerState: OwnerState, ids: { id: string; helperTextId?: string }): Record<string, unknown> {
+  const slots = slotPropsFor(props);
+  const shrink = slotPropsOf(slots.inputLabel, ownerState).shrink;
+  return {
+    'aria-describedby': ids.helperTextId,
+    autoComplete: props.autoComplete,
+    autoFocus: ownerState.autoFocus,
+    defaultValue: props.defaultValue,
+    fullWidth: ownerState.fullWidth,
+    name: props.name,
+    inputRef: props.inputRef,
+    onFocus: props.onFocus,
+    type: props.type,
+    value: props.value,
+    id: ids.id,
+    onBlur: props.onBlur,
+    onChange: props.onChange,
+    placeholder: props.placeholder,
+    inputProps: slotPropsOf(slots.htmlInput, ownerState),
+    label: props.label,
+    ...(shrink === undefined ? {} : { notched: shrink }),
+    ...slotPropsOf(slots.input, ownerState),
+  };
+}
+
+/**
+ * An outlined text field, composed from the parts MUI's `TextField` composes
+ * (FUT-3402). `TextField` itself imports `Select` unconditionally, and through
+ * it `Menu`, `MenuList`, `Popover` and `List`; this slot is in every host's
+ * checkout bundle whether or not the host fills it, so it paid for a dropdown
+ * it can never render.
+ *
+ * Same DOM and the same theme hooks — `defaultProps`, `styleOverrides`,
+ * `variants`, slot props — pinned by `default-input-parity.test.tsx`, with two
+ * deliberate exceptions: a theme default `variant` other than `outlined`, and
+ * `slots` replacing a part, are not honoured. Either would need the very
+ * components this slot exists to leave out; a host that wants them fills the
+ * `Input` slot.
+ */
+function DefaultInput(slotProps: CheckoutInputProps): JSX.Element {
+  const props = useTextFieldProps(slotProps);
+  const ownerState = ownerStateOf(props);
+  const generatedId = useId();
+  const id = props.id ?? generatedId;
+  const helperTextId = props.helperText ? `${id}-helper-text` : undefined;
+  const slots = slotPropsFor(props);
+  const { label, helperText } = props;
+  return (
+    <TextFieldRoot {...(rootPropsOf(props, ownerState) as { ownerState: OwnerState })}>
+      {label != null && label !== '' ? (
+        <InputLabel htmlFor={id} id={`${id}-label`} {...slotPropsOf(slots.inputLabel, ownerState)}>{label}</InputLabel>
+      ) : null}
+      <OutlinedInput {...inputPropsOf(props, ownerState, { id, helperTextId })} />
+      {helperText ? (
+        <FormHelperText id={helperTextId} {...slotPropsOf(slots.formHelperText, ownerState)}>{helperText}</FormHelperText>
+      ) : null}
+    </TextFieldRoot>
   );
 }
 

package/src/components/checkout/screens-copy.ts

@@ -266,6 +266,21 @@ export interface HostedHandoverCopy {
   preparing: string;
 }
 
+/**
+ * The cart changed after this payment was prepared (FUT-1139): another tab, a
+ * price the store moved, a line it stopped selling. The charge prepared for the
+ * OLD basket must not be the one paid, so the step says so and offers the one
+ * control that brings the payment up to date.
+ */
+export interface CartChangedCopy {
+  heading: string;
+  support: string;
+  /** Re-prepares the payment for the cart as it stands now. */
+  refreshAction: string;
+  /** The heading over a refresh that failed; the host's own sentence is the body. */
+  refreshFailed: string;
+}
+
 /** What the browser says when the wire itself failed. */
 export interface CheckoutTransportCopy {
   /** A refusal whose envelope carried no sentence of its own. */
@@ -298,6 +313,7 @@ export interface CheckoutScreensCopy {
   hosted: HostedHandoverCopy;
   transport: CheckoutTransportCopy;
   validation: CheckoutValidationCopy;
+  cartChanged: CartChangedCopy;
   /** The step wrapper's own wait, while the charge is being raised. */
   generatingPayment: string;
   /**

package/src/components/checkout/screens-en-US.ts

@@ -143,6 +143,12 @@ export const EN_US_CHECKOUT_SCREENS_COPY: CheckoutScreensCopy = {
     invalidResponse: 'Invalid response from the server.',
     offline: 'Could not connect. Check your connection and try again.',
   },
+  cartChanged: {
+    heading: 'Your cart changed',
+    support: 'This payment was prepared for your previous cart. Update it to pay the right amount.',
+    refreshAction: 'Update payment',
+    refreshFailed: 'Could not update the payment',
+  },
   validation: {
     taxIdInvalid: 'That CPF is not valid.',
     nameRequired: 'Enter your name.',

package/src/components/checkout/screens-pt-BR.ts

@@ -129,6 +129,12 @@ export const PT_BR_CHECKOUT_SCREENS_COPY: CheckoutScreensCopy = {
     invalidResponse: 'Resposta inválida do servidor.',
     offline: 'Não foi possível conectar. Verifique sua conexão e tente novamente.',
   },
+  cartChanged: {
+    heading: 'Seu carrinho mudou',
+    support: 'O pagamento foi preparado para o carrinho anterior. Atualize para pagar o valor certo.',
+    refreshAction: 'Atualizar pagamento',
+    refreshFailed: 'Não foi possível atualizar o pagamento',
+  },
   validation: {
     taxIdInvalid: 'CPF inválido.',
     nameRequired: 'Informe seu nome.',

package/src/components/checkout/start-payment.ts

@@ -124,28 +124,57 @@ export function useStartPayment(input: {
         failure.fail(result.error);
         return;
       }
-      // NOTHING LEFT TO PAY — see the docblock. Parked first for the same
-      // reason every other raised order is: the confirmation this is about to
-      // show has to survive a tab the phone discards on the way to it.
-      if (result.data.status !== "AWAITING_PAYMENT") {
-        rememberHostedOrder(result.data, { tenantSlug, basket: parkedBasket(basket) });
-        setOrder(result.data);
-        setFinalStatus(result.data.status);
-        setStep("status");
-        return;
-      }
-      if (handOverToProvider(result.data, navigate, tenantSlug, basket)) return;
-      // PARKED EVEN THOUGH NOBODY IS LEAVING (FUT-1140). A low-memory phone
-      // discards this tab while the shopper is in their bank app, and the SPA
-      // that comes back has never heard of the order it raised — so the buyer
-      // meets an empty cart and a retry button instead of the confirmation for
-      // the payment they just made.
-      rememberHostedOrder(result.data, { tenantSlug, basket: parkedBasket(basket) });
-      setOrder(result.data);
+      routeRaisedOrder(result.data, { navigate, tenantSlug, basket, setOrder, setFinalStatus, setStep });
     },
     [
       buyer, saveProfile, createOrder, failure, navigate, tenantSlug, basket,
       setCreating, setDecline, setOrder, setFinalStatus, setStep,
     ],
   );
-}
+}
+
+/**
+ * What becomes of an order the host just raised — or re-priced (FUT-1139): the
+ * three outcomes of {@link useStartPayment} after its refusal branch, shared so
+ * a refresh routes a PAID or handed-off answer exactly as a raise does.
+ */
+export function routeRaisedOrder(
+  order: CheckoutOrder,
+  ctx: {
+    navigate: CheckoutNavigate;
+    tenantSlug: string | undefined;
+    basket: CheckoutBasketIdentity | undefined;
+    setOrder: Dispatch<SetStateAction<CheckoutOrder | null>>;
+    setFinalStatus: Dispatch<SetStateAction<OrderStatus | null>>;
+    setStep: Dispatch<SetStateAction<Step>>;
+  },
+): void {
+  const { navigate, tenantSlug, basket, setOrder, setFinalStatus, setStep } = ctx;
+  // NOTHING LEFT TO PAY — see the docblock. Parked first for the same
+  // reason every other raised order is: the confirmation this is about to
+  // show has to survive a tab the phone discards on the way to it.
+  if (order.status !== "AWAITING_PAYMENT") {
+    rememberHostedOrder(order, { tenantSlug, basket: parkedBasket(basket) });
+    setOrder(order);
+    setFinalStatus(order.status);
+    setStep("status");
+    return;
+  }
+  if (handOverToProvider(order, navigate, tenantSlug, basket)) return;
+  // PARKED EVEN THOUGH NOBODY IS LEAVING (FUT-1140). A low-memory phone
+  // discards this tab while the shopper is in their bank app, and the SPA
+  // that comes back has never heard of the order it raised — so the buyer
+  // meets an empty cart and a retry button instead of the confirmation for
+  // the payment they just made.
+  rememberHostedOrder(order, { tenantSlug, basket: parkedBasket(basket) });
+  setOrder(order);
+}
+
+/** {@link routeRaisedOrder}, bound to one checkout and stable while its inputs are. */
+export function useRaisedOrderRoute(ctx: Parameters<typeof routeRaisedOrder>[1]): (order: CheckoutOrder) => void {
+  const { navigate, tenantSlug, basket, setOrder, setFinalStatus, setStep } = ctx;
+  return useCallback(
+    (order: CheckoutOrder) => routeRaisedOrder(order, { navigate, tenantSlug, basket, setOrder, setFinalStatus, setStep }),
+    [navigate, tenantSlug, basket, setOrder, setFinalStatus, setStep],
+  );
+}

package/src/components/checkout/use-checkout-controller.ts

@@ -11,7 +11,8 @@ import {
   useSettledPort,
   type Step,
 } from "./checkout-actions";
-import { useStartPayment } from "./start-payment";
+import { useOrderRefresh } from "./cart-changed";
+import { useRaisedOrderRoute, useStartPayment } from "./start-payment";
 import { useConfirmationWait } from "./confirmation-wait";
 import { useCheckoutCopy } from "./copy-context";
 
@@ -144,6 +145,9 @@ export function useCheckoutController(
   const { payWithEmail, handleResolved } = useResolutionActions({
     buyer, method, startPayment, setBuyerState, setDecline, setFinalStatus, setStep,
   });
+  // Re-price the order in place when the cart moved under it (FUT-1139), routed as a raise is.
+  const route = useRaisedOrderRoute({ navigate, tenantSlug, basket, setOrder, setFinalStatus, setStep });
+  const refresh = useOrderRefresh({ order, buyer, saveProfile, createOrder, route });
   const retry = useRetryAction({
     decline, order, clearError, setOrder, setDecline, setFinalStatus, setStep, setFreshInstrument,
   });
@@ -166,6 +170,6 @@ export function useCheckoutController(
     ...resumeSurface(resume, confirming),
     createError: failure.message, errorField: failure.field, errorCode: failure.code,
     goToMenu: onExitToMenu, back, editBuyer,
-    goToPayment, startPayment, payWithEmail, handleResolved, retry, completed,
+    goToPayment, startPayment, refresh, payWithEmail, handleResolved, retry, completed,
   };
 }

package/src/index.ts

@@ -118,6 +118,7 @@ export {
 // pack section by section types the section it is writing (FUT-760).
 export type {
   CardPaneCopy,
+  CartChangedCopy,
   CheckoutScreensCopy,
   CheckoutTransportCopy,
   CheckoutValidationCopy,