@12-apps/payments-frontend 3.21.3 → 3.22.0

package/src/components/checkout/transport.ts

@@ -96,10 +96,20 @@ export interface CheckoutTransport {
 export type CheckoutTransportBinding = Omit<CheckoutTransport, "copy"> &
   Partial<Pick<CheckoutTransport, "copy">>;
 
-/** The eight calls the buyer checkout makes, pre-bound to a {@link CheckoutTransport}. */
+/** The nine calls the buyer checkout makes, pre-bound to a {@link CheckoutTransport}. */
 export interface CheckoutClient {
   getConfig(tenantSlug: string): Promise<Result<CheckoutProviderConfig>>;
   getStatus(ref: string): Promise<Result<OrderStatus>>;
+  /**
+   * `POST /release` (FUT-1146): the buyer says they did not pay, and the
+   * charge they were sent away for has no terminal state of its own.
+   *
+   * Answers the payable's status AFTER the server has re-asked the provider,
+   * so a payment that actually succeeded comes back `PAID` and nothing is
+   * released — the race against a late webhook resolves in the shopper's
+   * favour rather than against it.
+   */
+  releaseCheckout(input: { orderId: string }): Promise<Result<OrderStatus>>;
   charge(input: ChargeCardInput): Promise<Result<ChargeOutcome>>;
   /** A wallet instrument against the same `/charge` route (FUT-471/472). */
   chargeWallet(input: ChargeWalletInput): Promise<Result<ChargeOutcome>>;
@@ -266,6 +276,16 @@ export function createCheckoutClient(transport: CheckoutTransport): CheckoutClie
         { method: "GET" },
       ),
 
+    releaseCheckout: (input) =>
+      // The settlement hints ride in the QUERY, exactly as the poll's do: they
+      // are the only way a hosted provider can be asked anything at all, so a
+      // release must carry them or the server decides "not paid" from a
+      // question it was never able to put.
+      call<OrderStatus>(`/release?${new URLSearchParams(returnedSettlement()).toString()}`, {
+        method: "POST",
+        body: JSON.stringify({ orderId: input.orderId }),
+      }),
+
     charge: (input) =>
       call<ChargeOutcome>("/charge", { method: "POST", body: flatChargeBody(input) }),
 

package/src/components/checkout/types.ts

@@ -9,6 +9,8 @@
  * the ports declared on `CheckoutFlowProps`.
  */
 
+import type { CheckoutDecline, CheckoutDeclineReason } from "./decline";
+
 /** Payment methods offered at checkout. Mirrors `Payment.method` (FUT-42). */
 export type PaymentMethod = "PIX" | "CARD";
 
@@ -34,6 +36,16 @@ export type OrderStatus = "AWAITING_PAYMENT" | "PAID" | "FAILED" | "EXPIRED";
 /** Terminal states — polling stops once the order reaches one of these. */
 export const TERMINAL_STATUSES: readonly OrderStatus[] = ["PAID", "FAILED", "EXPIRED"];
 
+/**
+ * What a payment pane calls once the charge has an answer.
+ *
+ * The refusal rides along OPTIONALLY (FUT-1145): a pane that has one hands it
+ * over so the confirmation screen can say which refusal this was and whether
+ * another instrument could work, and every caller that has nothing to add keeps
+ * calling this with one argument exactly as before.
+ */
+export type OnCheckoutResolved = (status: OrderStatus, decline?: CheckoutDecline | null) => void;
+
 /** Buyer contact captured at checkout. */
 export interface BuyerInfo {
   name?: string;
@@ -358,8 +370,20 @@ export interface CheckoutProviderConfig {
  * present when the provider demands the buyer finish the charge on ITS page —
  * Stripe's redirect-based 3-D Secure — and the client then hands the buyer
  * over exactly as it does for a redirect provider's link (FUT-556).
+ *
+ * `declineReason` / `retriable` ride along on a refusal (FUT-1145). The server
+ * has classified every acquirer decline since FUT-340 — 33 PagBank codes with
+ * issuer sub-reasons, each carrying the vendor's own retry verdict — and then
+ * answered `{ status }` and threw the classification away, so an expired card,
+ * a stolen card and "attempts exhausted, do not retry" all reached the buyer as
+ * "Pagamento não concluído. Você pode tentar novamente."
+ *
+ * BOTH OPTIONAL, and the degrade direction is today's behaviour: a server that
+ * sends neither renders exactly the generic refusal it always did.
  */
 export interface ChargeOutcome {
   status: OrderStatus;
   hostedCheckoutUrl?: string;
+  declineReason?: CheckoutDeclineReason;
+  retriable?: boolean;
 }

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

@@ -22,12 +22,12 @@ import {
   type CardInstruments,
   type RefreshBrowserKey,
 } from "./card-instruments";
+import { handOverToChallenge, reportResolved, type ChallengeScope } from "./card-outcome";
 import { useCheckoutClientApi } from "./client-context";
-import { rememberHostedOrder } from "./hosted-return";
-import { useCheckoutNavigate, type CheckoutNavigate } from "./navigate-context";
+import { useCheckoutNavigate } from "./navigate-context";
 import type { CardChainLink } from "./method-capability";
 import { useOneClickArmed, useOneClickPay } from "./one-click";
-import type { BuyerInfo, CheckoutOrder, OrderStatus } from "./types";
+import type { BuyerInfo, CheckoutOrder, OnCheckoutResolved, OrderStatus } from "./types";
 import { usePaymentPolling } from "./use-payment-polling";
 import type { CardCopy } from "../../card/copy";
 import { useCheckoutCopy } from "./copy-context";
@@ -40,7 +40,17 @@ const EMPTY_CARD: CardDetails = { number: "", holder: "", expiry: "", cvv: "" };
  * actually charge are offered. The slug arrives as an argument (the host's
  * routing owns it); absent, the list is unscoped, exactly as before FUT-697.
  */
-function useSavedCards(tenantSlug: string | undefined): {
+function useSavedCards(
+  tenantSlug: string | undefined,
+  /**
+   * The buyer is here because a card was REFUSED (FUT-1145), so the saved card
+   * this would otherwise preselect is the one that just failed. The list is
+   * still offered — another saved card may well work — but nothing is chosen
+   * for them, which puts the form in front of a buyer whose only untried
+   * instrument is a new one.
+   */
+  freshInstrument: boolean,
+): {
   savedCards: SavedCard[];
   selection: string;
   setSelection: (id: string) => void;
@@ -55,12 +65,12 @@ function useSavedCards(tenantSlug: string | undefined): {
       if (!active) return;
       setSavedCards(cards);
       const first = cards[0];
-      if (first) setSelection(first.id);
+      if (first && !freshInstrument) setSelection(first.id);
     });
     return () => {
       active = false;
     };
-  }, [tenantSlug, client]);
+  }, [tenantSlug, client, freshInstrument]);
 
   return { savedCards, selection, setSelection };
 }
@@ -164,24 +174,6 @@ type CardSubmit = Pick<
  */
 const CARD_AWAITING_WAIT_MS = 90_000;
 
-/**
- * Hand the buyer to the provider's authentication page (FUT-698) — Stripe's
- * redirect-based 3-D Secure. Park the order and navigate, the same trip a
- * redirect provider's link takes (FUT-556): the return lands back on this
- * checkout route, where the hosted-resume machinery polls the parked order.
- */
-function handOverToChallenge(
-  order: CheckoutOrder,
-  url: string,
-  navigate: CheckoutNavigate,
-): void {
-  // PARK FIRST. The navigation may not come back to a live SPA at all, and a
-  // return trip that finds nothing parked lands the buyer on a blank
-  // confirmation after they have paid.
-  rememberHostedOrder(order);
-  navigate(url);
-}
-
 /** The buyer's card is invalid — block the submit and show which field. */
 function blockedByForm(form: CardFormState): boolean {
   if (!form.usingNewCard) return false;
@@ -257,10 +249,13 @@ function useCardSubmit(
   order: CheckoutOrder,
   buyer: BuyerInfo,
   providerConfig: CardTokenizationConfig,
-  onResolved: (status: OrderStatus) => void,
+  onResolved: OnCheckoutResolved,
   pollIntervalMs: number,
   form: CardFormState,
   providerChain: readonly CardChainLink[],
+  /** WHOSE store and WHICH basket this charge is for — parked with a 3DS
+   *  hand-off, which is otherwise resumable over any basket anywhere. */
+  scope: ChallengeScope,
 ): CardSubmit {
   const [submitting, setSubmitting] = useState(false);
   const [submitted, setSubmitted] = useState(false);
@@ -319,11 +314,11 @@ function useCardSubmit(
     // 3-D Secure (FUT-698): the buyer must finish on the provider's page.
     // `submitting` stays true on purpose — the tab is navigating away.
     if (charged.data.hostedCheckoutUrl) {
-      return handOverToChallenge(order, charged.data.hostedCheckoutUrl, navigate);
+      return handOverToChallenge(order, charged.data.hostedCheckoutUrl, navigate, scope);
     }
-    // A business outcome (e.g. declined → FAILED) shows the status screen;
-    // an accepted charge begins polling for the async confirmation.
-    if (charged.data.status !== "AWAITING_PAYMENT") onResolved(charged.data.status);
+    // A business outcome shows the status screen, carrying the refusal the
+    // server classified (FUT-1145); an accepted charge begins polling.
+    if (charged.data.status !== "AWAITING_PAYMENT") reportResolved(charged.data, onResolved);
     else setSubmitted(true);
   };
 
@@ -338,7 +333,7 @@ export function useCardCheckout(
   order: CheckoutOrder,
   buyer: BuyerInfo,
   providerConfig: CardTokenizationConfig,
-  onResolved: (status: OrderStatus) => void,
+  onResolved: OnCheckoutResolved,
   pollIntervalMs: number,
   /** The store whose saved cards may be offered (host routing owns the slug). */
   tenantSlug?: string,
@@ -347,8 +342,12 @@ export function useCardCheckout(
    * per entry so a card charge can fail over. Omitted ⇒ the head alone.
    */
   providerChain: readonly CardChainLink[] = [],
+  /** Do not preselect a saved card — the last one was refused (FUT-1145). */
+  freshInstrument = false,
+  /** WHOSE store and WHICH basket, for the 3-D Secure hand-off's parked order. */
+  scope: ChallengeScope = {},
 ): CardCheckout {
-  const { savedCards, selection, setSelection } = useSavedCards(tenantSlug);
+  const { savedCards, selection, setSelection } = useSavedCards(tenantSlug, freshInstrument);
   const [card, setCard] = useState<CardDetails>(EMPTY_CARD);
   const [fieldErrors, setFieldErrors] = useState<CardFieldErrors>({});
   const [saveCard, setSaveCard] = useState(false);
@@ -373,6 +372,7 @@ export function useCardCheckout(
     pollIntervalMs,
     { card, usingNewCard, selection, saveCard, validate, setFieldErrors },
     providerChain,
+    scope,
   );
   // The tap a one-click buyer already made (`./one-click.tsx`). Nothing about
   // the charge differs — this only presses the button, and only while a SAVED

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

@@ -1,13 +1,24 @@
-import { useCallback, useEffect, useMemo, useState, type Dispatch, type SetStateAction } from "react";
-
-import { buyerGateError } from "./buyer-gate";
+import { useCallback, useMemo, useState } from "react";
+
+import type { CheckoutBasketIdentity } from "./basket";
+import {
+  resumeSurface,
+  useCheckoutNav,
+  useCreateFailure,
+  useGoToPayment,
+  useResumedCheckout,
+  useRetryAction,
+  useSettledPort,
+  useStartPayment,
+  type Step,
+} from "./checkout-actions";
 import { useCheckoutCopy } from "./copy-context";
 
-import { rememberHostedOrder, takeHostedOrder } from "./hosted-return";
-import { useCheckoutNavigate, type CheckoutNavigate } from "./navigate-context";
+import { forgetHostedOrder } from "./hosted-return";
+import { useCheckoutNavigate } from "./navigate-context";
+import type { CheckoutDecline } from "./decline";
 import type {
   BuyerContact,
-  BuyerField,
   BuyerInfo,
   CheckoutOrder,
   CreateOrderRequest,
@@ -16,9 +27,7 @@ import type {
   OrderStatus,
   PaymentMethod,
 } from "./types";
-import { usePaymentPolling } from "./use-payment-polling";
-
-type Step = "dados" | "payment" | "status";
+import { useHostedResume } from "./use-hosted-resume";
 
 const STEP_ORDER: Step[] = ["dados", "payment", "status"];
 
@@ -57,233 +66,6 @@ export interface CheckoutHostPorts {
   onPaid?: () => void;
 }
 
-/**
- * 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.
- */
-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 };
-}
-
-/**
- * Where checkout opens: on the outcome for a buyer returning from a hosted
- * provider, on Pagamento when their CPF is already on file, else on Dados.
- */
-function initialStep(resuming: boolean, taxIdOnFile: boolean): Step {
-  if (resuming) return "status";
-  return taxIdOnFile ? "payment" : "dados";
-}
-
-/**
- * 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,
-): 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.
-  rememberHostedOrder(order, tenantSlug);
-  navigate(order.hostedCheckoutUrl);
-  return true;
-}
-
-/**
- * How long the resumed screen keeps asking, and how often.
- *
- * TWO RATES, because one rate cannot serve this wait. The interval decides two
- * things that pull opposite ways: how fast a buyer WHO PAID is told so, and
- * what an abandoned checkout costs for the rest of the window. Every poll is a
- * provider round trip, so a slow rate is cheap and leaves a paying buyer
- * watching a spinner seconds longer than they need to — and the person on this
- * screen has almost always paid. A single number picks one of them to lose;
- * this shipped at a flat 5 s and picked the wrong one.
- *
- * So: 2.5 s for the first two minutes, which is where essentially every real
- * webhook lands (it fires within seconds of the payment, and this rate matches
- * what card and PIX already use), then 10 s for the remaining thirteen. A
- * confirmation is at most 2.5 s late, and an abandoned checkout costs ~126
- * polls instead of the 360 a flat 2.5 s would have.
- *
- * Fifteen minutes because by then a webhook that was ever coming has come. Past
- * that the answer will not change while the buyer watches: the scheduled
- * reconciliation is what rescues a genuinely late one, and it does that whether
- * the tab is open or not.
- *
- * The BOUND is that wall-clock window, not a poll count (FUT-1144). The two are
- * the same number for a healthy wait — 48 × 2.5 s + 78 × 10 s = 15 min — and
- * they part company for the wait that needed bounding: a poll that FAILS
- * incremented nothing, so a connection that never came back left this screen
- * asking, and spinning, with no end at all. A clock cannot be stopped by the
- * failure it is measuring.
- *
- * The card wait is bounded at 90 s (`CARD_AWAITING_WAIT_MS`) because a card
- * authorises inline and a buyer is holding their phone. This leg is the other
- * shape: the buyer has already been off to another site and back, and may
- * legitimately still be finishing there.
- */
-const HOSTED_RESUME_FAST_MS = 2_500;
-const HOSTED_RESUME_SLOW_MS = 10_000;
-/** Two minutes at the fast rate, before the wait is worth economising on. */
-const HOSTED_RESUME_FAST_POLLS = (2 * 60_000) / HOSTED_RESUME_FAST_MS;
-/** Thirteen more at the slow one — 15 minutes all told. */
-const HOSTED_RESUME_WINDOW_MS = 15 * 60_000;
-
-/**
- * The leg of checkout that resumes after a hosted provider sent the buyer back
- * (FUT-556).
- *
- * The SPA was torn down by the redirect, so the order is rehydrated from the
- * parked copy — once, on first render — and polled here rather than in a PIX or
- * card view, because a redirect provider produced neither. The webhook is still
- * what settles the order; this only tells the buyer that it did.
- *
- * And it stops telling them eventually. This poll was the one unbounded wait
- * left in checkout — card and wallet both cap theirs — so a buyer who came back
- * from a payment they never completed got "Confirmando seu pagamento… isso
- * costuma levar alguns segundos" and a spinner, truthfully forever. The screen
- * had no way to reach a terminal state, because the ORDER has none: expiry is
- * PIX-only, and a redirect charge carries no QR window to lapse. `timedOut` is
- * what the screen says instead of spinning.
- *
- * `error` is the half that was dropped on the floor (FUT-1144), and dropping it
- * is what made this leg the SILENT one. The poll below has always been able to
- * fail; this hook returned `status` and `timedOut` and nothing else, so a leg
- * whose every request was failing looked identical to one still waiting — the
- * spinner, forever, with the reason a `console`-less browser away. It is
- * surfaced now, together with the wait's own `checkAgain`, because a screen that
- * says "we cannot reach the payment" and offers nothing to press is only half
- * of an answer.
- */
-function useHostedResume(tenantSlug?: string): {
-  order: CheckoutOrder | null;
-  status: OrderStatus | null;
-  timedOut: boolean;
-  error: string | null;
-  checkAgain: () => void;
-} {
-  const [order] = useState(() => takeHostedOrder(tenantSlug));
-  const { status, timedOut, error, checkAgain } = usePaymentPolling(order?.orderId ?? null, {
-    enabled: Boolean(order),
-    intervalMs: HOSTED_RESUME_FAST_MS,
-    slowAfterPolls: HOSTED_RESUME_FAST_POLLS,
-    slowIntervalMs: HOSTED_RESUME_SLOW_MS,
-    maxWaitMs: HOSTED_RESUME_WINDOW_MS,
-  });
-  return { order, status, timedOut, error, checkAgain };
-}
-
-/**
- * What the resumed leg contributes to the controller's surface.
- *
- * `resumeTimedOut` is only ever true on that leg — `useHostedResume` is the
- * sole caller that bounds its wait, and a buyer who never left has a card or
- * PIX view reporting its own. `resumeError` and `resumeCheckAgain` are the
- * transient failure and the buyer's way out of it (FUT-1144).
- *
- * All three are inert for a checkout that never left this tab: with nothing
- * parked the poll is disabled, so the error stays null, the bound never
- * elapses, and the action has no wait to restart.
- */
-function resumeSurface(resume: ReturnType<typeof useHostedResume>): {
-  resumeTimedOut: boolean;
-  resumeError: string | null;
-  resumeCheckAgain: () => void;
-} {
-  return {
-    resumeTimedOut: resume.timedOut,
-    resumeError: resume.error,
-    resumeCheckAgain: resume.checkAgain,
-  };
-}
-
-/**
- * Fire the host's `onPaid` port once the order settles PAID.
- *
- * 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. The server was
- * right and the screen was stale; this is where the host is told to catch up.
- *
- * PAID only. A FAILED or EXPIRED order fires nothing — that shopper still has
- * a basket to retry with, and the host must not be told otherwise.
- */
-function usePaidPort(settled: OrderStatus | null, onPaid: (() => void) | undefined): void {
-  useEffect(() => {
-    if (settled !== "PAID") return;
-    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.
- */
-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 };
-}
-
 /**
  * All checkout state + handlers, so the checkout flow stays presentational.
  * - `setMethod` drops any order raised for the previous method (no stale QR/form).
@@ -295,6 +77,8 @@ function useCreateFailure() {
  *   being saved.
  * - `startPayment` raises the order (PIX → QR, CARD → chargeable); `payWithEmail`
  *   re-raises with a corrected e-mail for the merchant-email rejection.
+ * - `retry` re-charges the SAME order when the refusal says another instrument
+ *   could work (FUT-1145), and raises a fresh one when it does not.
  *
  * @param taxIdOnFile The buyer already has a CPF saved (FUT-465) ⇒ the Dados
  *   step has nothing left to ask, so checkout opens on Pagamento and `back`
@@ -304,6 +88,9 @@ function useCreateFailure() {
  * @param buyerFields What the store's chain declares it needs from the buyer
  *   (FUT-595). Absent ⇒ CPF-required, which is what this gate demanded before
  *   there was a declaration to read — never "ask nothing".
+ * @param basket WHICH basket this checkout is for (FUT-1213). Absent ⇒ the
+ *   pre-1213 behaviour: a parked payment resumes on whatever checkout mounts
+ *   next. See `./basket.ts` for why it is a signature of the lines.
  */
 export function useCheckoutController(
   ports: CheckoutHostPorts,
@@ -311,71 +98,64 @@ export function useCheckoutController(
   taxIdOnFile = false,
   buyerFields: readonly CheckoutCustomerField[] = CPF_ONLY,
   tenantSlug?: string,
+  basket?: CheckoutBasketIdentity,
 ) {
   const { createOrder, saveBuyerContact, onExitToMenu, onPaid } = ports;
   const validation = useCheckoutCopy().screens.validation;
   const navigate = useCheckoutNavigate();
-  const resume = useHostedResume(tenantSlug);
-  const [step, setStep] = useState<Step>(initialStep(Boolean(resume.order), taxIdOnFile));
+  const resume = useHostedResume(tenantSlug, basket);
+  const [step, setStep] = useState<Step>(taxIdOnFile ? "payment" : "dados");
   // No method pre-selected: the Pagamento step shows just the picker until the
   // buyer chooses PIX or card, then that method's order is raised and its UI
   // revealed. Avoids raising a throwaway PIX charge for a buyer who wants card.
   const [method, setMethodState] = useState<PaymentMethod | null>(null);
   const [buyer, setBuyerState] = useState<BuyerInfo>(defaultBuyer ?? {});
   const [saveProfile, setSaveProfile] = useState(true);
-  const [order, setOrder] = useState<CheckoutOrder | null>(resume.order);
+  const [order, setOrder] = useState<CheckoutOrder | null>(null);
   const [finalStatus, setFinalStatus] = useState<OrderStatus | null>(null);
+  const [decline, setDecline] = useState<CheckoutDecline | null>(null);
+  const [freshInstrument, setFreshInstrument] = useState(false);
   const [creating, setCreating] = useState(false);
   const failure = useCreateFailure();
+  useResumedCheckout(resume, setOrder, setStep, setFinalStatus, setMethodState);
 
   const clearError = failure.clear;
   const setBuyer = useCallback((next: BuyerInfo) => { setBuyerState(next); clearError(); }, [clearError]);
   const { back, editBuyer } = useCheckoutNav(taxIdOnFile, onExitToMenu, setStep);
   const setMethod = useCallback((next: PaymentMethod) => {
-    setMethodState((prev) => { if (prev !== next) { setOrder(null); clearError(); } return next; });
+    setMethodState((prev) => {
+      if (prev !== next) { setOrder(null); forgetHostedOrder(); clearError(); }
+      return next;
+    });
   }, [clearError]);
-  const goToPayment = useCallback(() => {
-    clearError();
-    const complaint = buyerGateError(validation, buyer, buyerFields, taxIdOnFile);
-    if (complaint) { failure.fail(complaint); return; }
-    // Persist the buyer's details HERE, on "Continuar" — not when a payment is
-    // raised. 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.
-    if (saveProfile) {
-      saveBuyerContact?.({ name: buyer.name, phone: buyer.phone, taxId: buyer.taxId });
-    }
-    setStep("payment");
-  }, [buyer, buyerFields, saveProfile, taxIdOnFile, clearError, saveBuyerContact, validation]);
-  const startPayment = useCallback(async (chosen: PaymentMethod, override?: BuyerInfo) => {
-    clearError();
-    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)) return;
-    setOrder(result.data);
-    setFinalStatus(null);
-  }, [buyer, saveProfile, createOrder, clearError, navigate, tenantSlug]);
+  const goToPayment = useGoToPayment({
+    buyer, buyerFields, taxIdOnFile, saveProfile, saveBuyerContact, validation, failure, setStep,
+  });
+  const startPayment = useStartPayment({
+    buyer, saveProfile, createOrder, navigate, tenantSlug, basket, failure,
+    setCreating, setDecline, setOrder, setFinalStatus,
+  });
   const payWithEmail = useCallback((email: string) => {
     if (!method) return;
     const next = { ...buyer, email };
     setBuyerState(next);
     void startPayment(method, next);
   }, [buyer, method, startPayment]);
-  const handleResolved = useCallback((s: OrderStatus) => { setFinalStatus(s); setStep("status"); }, []);
-  const retry = useCallback(() => {
-    setOrder(null); setFinalStatus(null); clearError(); setStep("payment");
-  }, [clearError]);
+  const handleResolved = useCallback((s: OrderStatus, refusal?: CheckoutDecline | null) => {
+    setDecline(refusal ?? null);
+    setFinalStatus(s);
+    setStep("status");
+  }, []);
+  const retry = useRetryAction({
+    decline, order, clearError, setOrder, setDecline, setFinalStatus, setStep, setFreshInstrument,
+  });
   const completed = useMemo(() => new Set(STEP_ORDER.slice(0, STEP_ORDER.indexOf(step))), [step]);
-  usePaidPort(finalStatus ?? resume.status, onPaid);
+  useSettledPort(finalStatus ?? resume.status, onPaid);
 
   return {
     step, setStep, method, setMethod, buyer, setBuyer, saveProfile, setSaveProfile,
     order, finalStatus: finalStatus ?? resume.status, creating,
+    decline, freshInstrument,
     ...resumeSurface(resume),
     createError: failure.message, errorField: failure.field, errorCode: failure.code,
     goToMenu: onExitToMenu, back, editBuyer,