@12-apps/payments-frontend 3.21.4 → 3.23.0

package/src/components/checkout/checkout-actions.ts

@@ -0,0 +1,387 @@
+import { useCallback, useEffect, useState, type Dispatch, type SetStateAction } from "react";
+
+import { buyerGateError } from "./buyer-gate";
+import type { ConfirmationWait } from "./confirmation-wait";
+import type { CheckoutDecline } from "./decline";
+import { forgetHostedOrder, rememberHostedOrder } from "./hosted-return";
+import { parkedBasket, type CheckoutBasketIdentity } from "./basket";
+import type { CheckoutNavigate } from "./navigate-context";
+import type { CheckoutScreensCopy } from "./screens-copy";
+import type {
+  BuyerContact,
+  BuyerField,
+  BuyerInfo,
+  CheckoutCustomerField,
+  CheckoutOrder,
+  CreateOrderRequest,
+  CreateOrderResult,
+  OrderStatus,
+  PaymentMethod,
+} from "./types";
+import { useResumeEffect, type HostedResume } from "./use-hosted-resume";
+
+/**
+ * The controller's own moving parts, one concern per hook.
+ *
+ * Split out of `./use-checkout-controller.ts` when the resumed leg grew a
+ * decision (FUT-1213), a general parked entry (FUT-1140) and a way out
+ * (FUT-1146) and that file's one exported function reached its size gate. The
+ * seam is the obvious one: everything here is state a step reads, and nothing
+ * here knows the ORDER the steps come in.
+ */
+
+/** Where the flow can be — the step ids, which are the flow's own contract. */
+export type Step = "dados" | "payment" | "status";
+
+/**
+ * The flow's navigation actions, split out of {@link useCheckoutController} for
+ * the 80-line per-function gate.
+ *
+ * `back` is where "the Dados step was skipped" has to be honoured: going back
+ * off Pagamento normally lands on Dados, but for a buyer with a CPF on file
+ * that step is not part of their flow, so the menu is the only honest
+ * destination — until they open it themselves via `editBuyer` ("alterar" on the
+ * payer block), after which it IS part of their flow and back returns to it.
+ */
+export function useCheckoutNav(
+  taxIdOnFile: boolean,
+  goToMenu: () => void,
+  setStep: Dispatch<SetStateAction<Step>>,
+): { back: () => void; editBuyer: (() => void) | undefined } {
+  const [dadosOpened, setDadosOpened] = useState(false);
+  const openDados = useCallback(() => {
+    setDadosOpened(true);
+    setStep("dados");
+  }, [setStep]);
+  const back = useCallback(() => {
+    setStep((current) => {
+      if (current === "payment" && (!taxIdOnFile || dadosOpened)) return "dados";
+      goToMenu();
+      return current;
+    });
+  }, [dadosOpened, goToMenu, setStep, taxIdOnFile]);
+  // Undefined unless Dados was skipped — the payer block keys off its presence,
+  // so the decision lives here rather than being re-derived by every caller.
+  return { back, editBuyer: taxIdOnFile ? openDados : undefined };
+}
+
+/**
+ * WHAT THE CONFIRMATION SCREEN KNOWS ABOUT ITS WAIT, from whichever wait is
+ * live.
+ *
+ * Two can reach that screen and they are mutually exclusive by construction: a
+ * checkout RESUMED from a parked entry polls through `useHostedResume`, and one
+ * that never left this tab polls through the confirmation wait (FUT-1170) — and
+ * that one stands down whenever a resumed order is what put the flow here. So
+ * the merge below is a choice between one live wait and one inert one, never a
+ * blend of two opinions.
+ *
+ * All of it is inert for a checkout with an answer already: with nothing to
+ * wait on both polls are disabled, so the error stays null, no bound elapses,
+ * and none of the actions has a wait to act on.
+ *
+ * `release` stays the resumed leg's alone. "Não consegui pagar" exists because
+ * a provider's own page produces no signal when a buyer abandons it (FUT-1146);
+ * a charge raised and still held on THIS page has no such gap to close.
+ */
+export function resumeSurface(
+  resume: HostedResume,
+  confirming: ConfirmationWait,
+): {
+  awaitingTimedOut: boolean;
+  awaitingError: string | null;
+  awaitingCheckAgain: () => void;
+  /** @deprecated Renamed to `awaitingTimedOut`; kept so the rename ships additively. */
+  resumeTimedOut: boolean;
+  /** @deprecated Renamed to `awaitingError`; kept so the rename ships additively. */
+  resumeError: string | null;
+  /** @deprecated Renamed to `awaitingCheckAgain`; kept so the rename ships additively. */
+  resumeCheckAgain: () => void;
+  resumeRelease: (() => void) | undefined;
+  resumeReleasing: boolean;
+} {
+  const live = resume.order === null ? confirming : resume;
+  return {
+    awaitingTimedOut: live.timedOut,
+    awaitingError: live.error,
+    awaitingCheckAgain: live.checkAgain,
+    // The three old spellings, beside the new ones rather than replaced by them.
+    // This shape is PUBLIC — `CheckoutController` is `ReturnType<typeof
+    // useCheckoutController>` (flows/types.ts:148), re-exported from index.ts,
+    // and `PaymentFlows.useCheckout()` returns it. Dropping three members of it
+    // is a source break for any adopter that hand-composes the flow, and this
+    // release is a patch. The rename was cosmetic; breaking a published type for
+    // it is not a trade worth making, so the old names stay until a major.
+    resumeTimedOut: live.timedOut,
+    resumeError: live.error,
+    resumeCheckAgain: live.checkAgain,
+    resumeRelease: resume.release,
+    resumeReleasing: resume.releasing,
+  };
+}
+
+/**
+ * Open the flow on whatever was resumed, and close it again if the buyer
+ * releases the order (FUT-1140/FUT-1146).
+ *
+ * A LAYOUT effect, through `useResumeEffect`: the decision cannot be made
+ * during render (it waits for the host's cart), and an ordinary effect runs
+ * after paint — so a buyer coming back from a payment would see one frame of
+ * the Dados or Pagamento step before their confirmation replaced it.
+ */
+export function useResumedCheckout(
+  resume: HostedResume,
+  setOrder: Dispatch<SetStateAction<CheckoutOrder | null>>,
+  setStep: Dispatch<SetStateAction<Step>>,
+  setFinalStatus: Dispatch<SetStateAction<OrderStatus | null>>,
+  setMethod: Dispatch<SetStateAction<PaymentMethod | null>>,
+): void {
+  const { order, step, released } = resume;
+  useResumeEffect(() => {
+    if (!order || !step) return;
+    setOrder(order);
+    setStep(step);
+    // The METHOD comes back with it, which matters for a resume that lands on
+    // the payment step: the picker keys off it, and a shopper looking at the
+    // PIX code they were already paying must not also be asked to choose how
+    // to pay. Set through the raw setter on purpose — the public `setMethod`
+    // drops the order on a change, which is the opposite of resuming one.
+    setMethod(order.method);
+  }, [order, step, setOrder, setStep, setMethod]);
+  useResumeEffect(() => {
+    if (!released) return;
+    // Back to a checkout they can actually use, with the basket they are
+    // holding. The order they released is gone from this screen; whether it is
+    // gone at the provider is the server's answer, not ours.
+    setOrder(null);
+    setFinalStatus(null);
+    setStep("payment");
+  }, [released, setOrder, setStep, setFinalStatus]);
+}
+
+/**
+ * The end of a checkout: tell the host, and let the parked entry go.
+ *
+ * PAID fires the host's `onPaid` port. FUT-601 made the SERVER empty the cart
+ * inside the confirmation transaction — but nothing told the SPA, whose cart
+ * provider survives every checkout route change and kept counting the items the
+ * buyer had just bought. A FAILED or EXPIRED order fires nothing: that shopper
+ * still has a basket to retry with, and the host must not be told otherwise.
+ *
+ * The parked entry is dropped on ANY terminal status (FUT-1140). It exists to
+ * carry one payment across a torn-down SPA; once that payment has an answer,
+ * resuming it could only re-show an outcome the buyer has already been given.
+ */
+export function useSettledPort(settled: OrderStatus | null, onPaid: (() => void) | undefined): void {
+  useEffect(() => {
+    if (!settled || settled === "AWAITING_PAYMENT") return;
+    forgetHostedOrder();
+    if (settled === "PAID") onPaid?.();
+  }, [settled, onPaid]);
+}
+
+/**
+ * The create-order refusal the steps render: what to say, which field to
+ * highlight, and the machine CODE that decides how it is presented — an
+ * unresolved charge is not a failed one, and the Pagamento step must not offer
+ * it a "Tentar novamente" (FUT-563). One hook so the three always move
+ * together; they were three `useState`s that could be cleared apart.
+ */
+export function useCreateFailure() {
+  const [message, setMessage] = useState<string | null>(null);
+  const [field, setField] = useState<BuyerField | null>(null);
+  const [code, setCode] = useState<string | null>(null);
+  const clear = useCallback(() => {
+    setMessage(null);
+    setField(null);
+    setCode(null);
+  }, []);
+  const fail = useCallback(
+    (next: { message: string; field?: BuyerField | null; code?: string }) => {
+      setMessage(next.message);
+      setField(next.field ?? null);
+      setCode(next.code ?? null);
+    },
+    [],
+  );
+  return { message, field, code, clear, fail };
+}
+
+
+/**
+ * "Continuar" on the Dados step: gate on what the store's chain demands, then
+ * PERSIST the buyer's details before advancing.
+ *
+ * The write happens HERE and not when a payment is raised, because everything
+ * after this step can fail — no provider configured, a declined card, an
+ * abandoned PIX, a closed tab — and the details must survive all of it.
+ * Fire-and-forget on purpose: making the buyer wait on the write, or blocking
+ * them when it fails, would trade the bug for a worse one. Gated on the
+ * "salvar meus dados" consent (LGPD), which is what the checkbox means.
+ */
+export function useGoToPayment(input: {
+  buyer: BuyerInfo;
+  buyerFields: readonly CheckoutCustomerField[];
+  taxIdOnFile: boolean;
+  saveProfile: boolean;
+  saveBuyerContact: ((contact: BuyerContact) => void) | undefined;
+  validation: CheckoutScreensCopy["validation"];
+  failure: { clear: () => void; fail: (next: { message: string; field?: BuyerField | null }) => void };
+  setStep: Dispatch<SetStateAction<Step>>;
+}): () => void {
+  const { buyer, buyerFields, taxIdOnFile, saveProfile, saveBuyerContact } = input;
+  const { validation, failure, setStep } = input;
+  return useCallback(() => {
+    failure.clear();
+    const complaint = buyerGateError(validation, buyer, buyerFields, taxIdOnFile);
+    if (complaint) {
+      failure.fail(complaint);
+      return;
+    }
+    if (saveProfile) {
+      saveBuyerContact?.({ name: buyer.name, phone: buyer.phone, taxId: buyer.taxId });
+    }
+    setStep("payment");
+  }, [buyer, buyerFields, saveProfile, taxIdOnFile, failure, saveBuyerContact, validation, setStep]);
+}
+
+/**
+ * "Tentar novamente" after a refusal — and WHICH order it goes against.
+ *
+ * A RETRIABLE decline keeps the order (FUT-1145). Minting a new one for every
+ * refused card leaves a trail of failed orders in the buyer's own history for
+ * one purchase they are still trying to make, and the money rule is unchanged
+ * either way: the server refuses a second charge on a payable it has already
+ * settled. `freshInstrument` is the other half — the saved card that just
+ * failed is not chosen for them again.
+ */
+export function useRetryAction(input: {
+  decline: CheckoutDecline | null;
+  order: CheckoutOrder | null;
+  clearError: () => void;
+  setOrder: Dispatch<SetStateAction<CheckoutOrder | null>>;
+  setDecline: Dispatch<SetStateAction<CheckoutDecline | null>>;
+  setFinalStatus: Dispatch<SetStateAction<OrderStatus | null>>;
+  setStep: Dispatch<SetStateAction<Step>>;
+  setFreshInstrument: Dispatch<SetStateAction<boolean>>;
+}): () => void {
+  const { decline, order, clearError, setOrder, setDecline } = input;
+  const { setFinalStatus, setStep, setFreshInstrument } = input;
+  return useCallback(() => {
+    setFinalStatus(null);
+    clearError();
+    setStep("payment");
+    if (decline?.retriable && order) {
+      setFreshInstrument(true);
+      return;
+    }
+    setOrder(null);
+    setDecline(null);
+    forgetHostedOrder();
+  }, [
+    clearError, decline, order, setDecline, setFinalStatus, setFreshInstrument, setOrder, setStep,
+  ]);
+}
+
+/**
+ * Hand the buyer to a redirect provider's own page, if that is where this
+ * charge settles (FUT-556).
+ *
+ * Called BEFORE the order is stored: storing it first would render the PIX or
+ * card step for a provider that returned neither, which is the dead end this
+ * fixes.
+ *
+ * A full navigation rather than the host's router, because the destination is
+ * another origin. The return trip comes back to this same checkout route
+ * carrying `transaction_nsu` + `slug`, which the status poll already reads.
+ *
+ * @returns true when the buyer is on their way and the caller must stop.
+ */
+function handOverToProvider(
+  order: CheckoutOrder,
+  navigate: CheckoutNavigate,
+  tenantSlug?: string,
+  basket?: CheckoutBasketIdentity,
+): boolean {
+  if (!order.hostedCheckoutUrl) return false;
+  // PARK FIRST, navigate second. The order is the only thing the return trip
+  // has to rehydrate from, and the navigation may tear this SPA down before
+  // any later write lands.
+  //
+  // The STORE goes with it: one tab holds one slot, and on a multi-tenant
+  // storefront every store shares an origin. Without the slug, abandoning this
+  // hand-off and opening another store's checkout resumed THIS order there.
+  //
+  // So does the BASKET (FUT-1213): a hand-off nobody completed must not resume
+  // itself over the shopper's next basket, and the only way to tell the two
+  // apart later is to record which basket this one was raised from.
+  rememberHostedOrder(order, {
+    tenantSlug,
+    basket: parkedBasket(basket),
+    handoff: true,
+  });
+  navigate(order.hostedCheckoutUrl);
+  return true;
+}
+
+/**
+ * Raise the order for a chosen method, and decide what happens to it.
+ *
+ * Three outcomes, in order: a refusal the step renders, a HAND-OFF that leaves
+ * this page for the provider's own, and an order raised here.
+ */
+export function useStartPayment(input: {
+  buyer: BuyerInfo;
+  saveProfile: boolean;
+  createOrder: (request: CreateOrderRequest) => Promise<CreateOrderResult>;
+  navigate: CheckoutNavigate;
+  tenantSlug: string | undefined;
+  basket: CheckoutBasketIdentity | undefined;
+  failure: { clear: () => void; fail: (next: { message: string; field?: BuyerField | null; code?: string }) => void };
+  setCreating: Dispatch<SetStateAction<boolean>>;
+  setDecline: Dispatch<SetStateAction<CheckoutDecline | null>>;
+  setOrder: Dispatch<SetStateAction<CheckoutOrder | null>>;
+  setFinalStatus: Dispatch<SetStateAction<OrderStatus | null>>;
+}): (chosen: PaymentMethod, override?: BuyerInfo) => Promise<void> {
+  const { buyer, saveProfile, createOrder, navigate, tenantSlug, basket, failure } = input;
+  const { setCreating, setDecline, setOrder, setFinalStatus } = input;
+  return useCallback(
+    async (chosen: PaymentMethod, override?: BuyerInfo) => {
+      failure.clear();
+      setDecline(null);
+      // THE CHARGE BEING REPLACED IS DROPPED FIRST (FUT-1170), before the raise
+      // rather than after it. Raising a payment means whatever was on screen is
+      // no longer the one being paid, and a provider round trip is long enough
+      // for the difference to matter: "Gerar novo código" left the expired
+      // charge mounted, so its own view polled it, got the terminal EXPIRED it
+      // was always going to get, and bounced the flow to the confirmation
+      // screen — where the new charge then landed with nothing polling it.
+      //
+      // A no-op on every other caller (the auto-raise, the alternate e-mail and
+      // the retry all run with no order held), which is the point: the clear
+      // belongs to what raising a payment MEANS, not to the one path that
+      // noticed.
+      setOrder(null);
+      setFinalStatus(null);
+      setCreating(true);
+      const result = await createOrder({ method: chosen, buyer: override ?? buyer, saveProfile });
+      setCreating(false);
+      if (!result.ok) {
+        failure.fail(result.error);
+        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);
+    },
+    [
+      buyer, saveProfile, createOrder, failure, navigate, tenantSlug, basket,
+      setCreating, setDecline, setOrder, setFinalStatus,
+    ],
+  );
+}

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

@@ -1,8 +1,10 @@
 import { Box } from "@mui/material";
 import { useMemo, type JSX, type ReactNode } from "react";
 
+import type { CheckoutBasketIdentity } from "./basket";
 import { buyerFieldsFor } from "./buyer-fields";
-import { DadosStep, EmptyCart, PaymentStep } from "./checkout-steps";
+import { EmptyCart, PaymentStep } from "./checkout-steps";
+import { DadosStep } from "./dados-step";
 import { ArrowBackIcon } from "./icons";
 import { PaymentStatus } from "./payment-status";
 import type { BuyerInfo, CheckoutProviderConfig, SettlementCheckout } from "./types";
@@ -29,6 +31,18 @@ export interface CheckoutCartView {
   totalItems: number;
   /** Host-rendered discount itemization under the pay-bar total (FUT-246). */
   discountLines?: ReactNode;
+  /**
+   * WHICH basket this is, so a payment raised from another one cannot resume
+   * itself over it (FUT-1213).
+   *
+   * Optional, and absent means the pre-1213 behaviour — a parked payment
+   * resumes on whatever checkout mounts next, which is what shipped and what
+   * this ticket exists to bound. A host supplies it by calling
+   * `basketSignature(lines)` on its own cart and passing `ready: false` while
+   * that cart is still loading; see `./basket.ts` for why the identity is the
+   * LINES and not the cart's id.
+   */
+  identity?: CheckoutBasketIdentity;
 }
 
 /**
@@ -84,6 +98,16 @@ export interface CheckoutFlowProps extends CheckoutHostPorts {
   components?: Partial<CheckoutComponents>;
 }
 
+/**
+ * Whether the host's cart has actually answered yet.
+ *
+ * `true` for every host that wires no identity, which is what it meant before
+ * there was one to wire.
+ */
+function cartLoaded(cart: CheckoutCartView): boolean {
+  return cart.identity?.ready !== false;
+}
+
 /** The pay-bar total override when settling a settlement (else the cart's own totals). */
 function settlementTotalOverride(
   settlement: SettlementCheckout | null | undefined,
@@ -173,12 +197,101 @@ function StatusStep({
       onRegenerate={() => { c.setStep("payment"); void c.startPayment("PIX"); }}
       onBackToMenu={c.goToMenu}
       paidExtra={confirmationExtra}
-      awaitingTimedOut={c.resumeTimedOut}
-      // The resumed leg's own trouble, and the way out of it (FUT-1144). Both
-      // are inert for a checkout that never left this tab — nothing was parked,
-      // so nothing is being polled here.
-      awaitingError={c.resumeError}
-      onCheckAgain={c.resumeCheckAgain}
+      awaitingTimedOut={c.awaitingTimedOut}
+      // How the wait behind this screen is going, and the way out of it
+      // (FUT-1144). It is the resumed leg's wait for a checkout that came back
+      // from a provider's page, and this step's own (FUT-1170) for one that
+      // never left the tab — which used to have no wait at all, and so a
+      // spinner that stood for nothing.
+      awaitingError={c.awaitingError}
+      onCheckAgain={c.awaitingCheckAgain}
+      // The buyer's own way out of a hosted wait with no terminal state
+      // (FUT-1146). Absent — and so unrendered — until the resumed leg has one
+      // to offer, which is every checkout that never left this tab.
+      onNotPaid={c.resumeRelease}
+      releasing={c.resumeReleasing}
+      // WHY a card was refused, when the server said (FUT-1145). Read on
+      // FAILED only, where it picks the sentence and decides whether a retry
+      // could work at all.
+      decline={c.decline}
+    />
+  );
+}
+
+/**
+ * Nothing to check out — and the cart has ANSWERED, which is the half FUT-1213
+ * added.
+ *
+ * A settlement pays already-sent items, so the cart is legitimately empty
+ * there. The guard cannot key on the Dados step either: skipping it (FUT-465)
+ * makes Pagamento the first screen. And it holds until an order exists — once
+ * one does, its lines are snapshotted server-side and the cart no longer speaks
+ * for it.
+ *
+ * A cart still being FETCHED is empty in exactly the way a real one is not, so
+ * a host that wires `identity` gets this screen when its cart is empty rather
+ * than when it is late — which is also the moment the resume decision waits for.
+ *
+ * A RAISE IN FLIGHT is not "nothing to pay for" either (FUT-1170). Raising a
+ * charge now drops the one it replaces before it asks for the new one, so there
+ * is a window with no order held — and a checkout whose cart the host had
+ * already emptied would otherwise swap the buyer onto the empty-cart screen
+ * mid-regenerate, discarding the charge as it arrived.
+ */
+function nothingToPayFor(
+  settlement: SettlementCheckout | null | undefined,
+  cart: CheckoutCartView,
+  c: ReturnType<typeof useCheckoutController>,
+): boolean {
+  if (settlement || !cart.empty || !cartLoaded(cart)) return false;
+  return !c.order && !c.creating && c.step !== "status";
+}
+
+/** Step 2, with the controller's facts and the host's money mapped onto it. */
+function PagamentoStep({
+  c,
+  cart,
+  settlement,
+  providerConfig,
+  tenantSlug,
+  validateApplePayMerchant,
+}: {
+  c: ReturnType<typeof useCheckoutController>;
+  cart: CheckoutCartView;
+  settlement: SettlementCheckout | null | undefined;
+  providerConfig: CheckoutProviderConfig | null | undefined;
+  tenantSlug: string | undefined;
+  validateApplePayMerchant: ((validationURL: string) => Promise<unknown>) | undefined;
+}): JSX.Element {
+  return (
+    <PaymentStep
+      method={c.method}
+      onMethodChange={c.setMethod}
+      order={c.order}
+      buyer={c.buyer}
+      creating={c.creating}
+      createError={c.createError}
+      errorField={c.errorField}
+      errorCode={c.errorCode}
+      onGenerate={(chosen) => void c.startPayment(chosen)}
+      onUseEmail={c.payWithEmail}
+      // Set only for a skipped-Dados flow (the controller decides); the payer
+      // block hides itself when it is absent.
+      onEditBuyer={c.editBuyer}
+      providerConfig={providerConfig}
+      tenantSlug={tenantSlug}
+      // The amount, on the step that asks for it (FUT-1179).
+      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).
+      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).
+      basket={cart.identity}
+      validateApplePayMerchant={validateApplePayMerchant}
+      onResolved={c.handleResolved}
     />
   );
 }
@@ -190,7 +303,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
   // any chain member may need rather than re-opening after the choice. A chain
   // that declares nothing degrades to CPF-required, never to "ask nothing".
   const buyerFields = useMemo(() => buyerFieldsFor(providerConfig?.chain, null), [providerConfig]);
-  const c = useCheckoutController(ports, defaultBuyer, taxIdOnFile, buyerFields, tenantSlug);
+  const c = useCheckoutController(ports, defaultBuyer, taxIdOnFile, buyerFields, tenantSlug, cart.identity);
   const armed = useOneClick({ requested: oneClick, config: providerConfig, taxIdOnFile, step: c.step, method: c.method, setMethod: c.setMethod });
 
   // A settlement settlement pays already-sent kitchen items — the cart is
@@ -200,7 +313,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
   // Pagamento the first screen, so an empty cart would otherwise reach the
   // method picker. It holds until an order exists — once one does, its lines are
   // snapshotted server-side and the cart no longer speaks for it.
-  if (!settlement && cart.empty && !c.order && c.step !== "status") {
+  if (nothingToPayFor(settlement, cart, c)) {
     return <EmptyCart copy={copy.emptyCart} onBack={c.goToMenu} />;
   }
 
@@ -229,24 +342,13 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
 
       {c.step === "payment" ? (
         <OneClickProvider armed={armed}>
-          <PaymentStep
-            method={c.method}
-            onMethodChange={c.setMethod}
-            order={c.order}
-            buyer={c.buyer}
-            creating={c.creating}
-            createError={c.createError}
-            errorField={c.errorField}
-            errorCode={c.errorCode}
-            onGenerate={(chosen) => void c.startPayment(chosen)}
-            onUseEmail={c.payWithEmail}
-            // Set only for a skipped-Dados flow (the controller decides); the
-            // payer block hides itself when it is absent.
-            onEditBuyer={c.editBuyer}
+          <PagamentoStep
+            c={c}
+            cart={cart}
+            settlement={settlement}
             providerConfig={providerConfig}
             tenantSlug={tenantSlug}
             validateApplePayMerchant={validateApplePayMerchant}
-            onResolved={c.handleResolved}
           />
         </OneClickProvider>
       ) : null}