@12-apps/payments-frontend 3.21.4 → 3.23.0

package/src/flows/pipeline/stable-plugins.ts

@@ -0,0 +1,72 @@
+/**
+ * THE DEV-MODE ASSERTION THAT KEEPS HOOK ORDER HONEST (FUT-1216 risk 1).
+ *
+ * Every registered step, gate and settlement method may declare a `useFacts()`,
+ * and the engine calls them in ARRAY ORDER on every render. React's hook
+ * identity is positional, so the order — and therefore the membership — of
+ * those arrays is part of the component's hook signature.
+ *
+ * A host that builds them inline (`steps={[scheduleStep, addressStep]}` in
+ * JSX, or `const GATES = gates.filter(...)` in a component body) hands the
+ * engine a NEW array every render. Today that usually still works, which is
+ * the danger: it works right up until a filter's answer changes and a
+ * `useFacts` disappears from the middle of the list, at which point React
+ * silently pairs the wrong state with the wrong plugin. There is no error, no
+ * warning, and the symptom is a checkout that reads another plugin's facts.
+ *
+ * So this refuses the shape rather than the symptom. In a development build a
+ * plugin array that is not identity-stable across renders THROWS, naming the
+ * array and the fix: hoist it to module scope, or memoise it. In production it
+ * does nothing at all — a live checkout must never be taken down by a wiring
+ * complaint, and by then the shape has been provable for the host's whole dev
+ * and test cycle.
+ */
+import { useRef } from "react";
+
+/** Whether this bundle is a development one. */
+function inDevelopment(): boolean {
+  // `process` is absent in a plain browser and replaced at build time by every
+  // bundler a host is likely to use; both readings are guarded so neither can
+  // throw inside a render.
+  try {
+    return typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production";
+  } catch {
+    return false;
+  }
+}
+
+/** What a host is told when it rebuilds an array per render. */
+function unstablePluginMessage(name: string): string {
+  return (
+    `createPaymentFlows: \`${name}\` must be the SAME array on every render. ` +
+    "Every registered plugin's `useFacts()` runs in array order, so React's hook " +
+    "order is a function of this array's membership — a fresh array per render " +
+    "will eventually pair one plugin's state with another's, silently. Hoist it " +
+    "to module scope (`const STEPS = [...]`) or memoise it. This check runs in " +
+    "development builds only."
+  );
+}
+
+/**
+ * Assert one plugin array is the same object it was last render.
+ *
+ * `undefined` is stable by definition — a host that registers nothing has
+ * nothing to keep still — and the FIRST render has nothing to compare with.
+ */
+export function useStablePluginArray(
+  name: string,
+  array: readonly unknown[] | undefined,
+): void {
+  const seen = useRef<readonly unknown[] | undefined>(array);
+  if (array === undefined || seen.current === undefined) return;
+  if (seen.current === array) return;
+  // THROWN BEFORE THE REF MOVES, and that ordering is the whole assertion.
+  // React answers a failed concurrent render by retrying the root
+  // synchronously; a check that had already recorded the new array would pass
+  // on that retry, React would report itself recovered, and the misconfigured
+  // host would see nothing at all. Refusing again is what puts the complaint
+  // in front of an error boundary — and what keeps it there until the array is
+  // actually hoisted.
+  if (inDevelopment()) throw new Error(unstablePluginMessage(name));
+  seen.current = array;
+}

package/src/flows/pipeline/steps/buyer-steps.tsx

@@ -0,0 +1,297 @@
+/**
+ * THE TWO STEPS BEFORE ANY MONEY MOVES (FUT-1240): who is paying, and how.
+ *
+ * Both are thin wrappers over screens this package already ships — exactly as
+ * `flows/screens-*.tsx` wrap the components today. What is new is that their
+ * PLACE in the walk is declared rather than switched on, and that the
+ * buyer-details step's "was it skipped, and has it been opened since" lives in
+ * a slice the engine parks instead of in a `useState` a reload forgets.
+ */
+import { Box } from "@mui/material";
+import type { JSX } from "react";
+
+import { PaymentErrorPanel } from "../../../components/checkout/payment-error-panel";
+import { useCheckoutComponents } from "../../../components/checkout/ui";
+import type { PaymentMethod } from "../../../components/checkout/types";
+import { usePipelineActions } from "../actions";
+import { isPackageMethod } from "../methods";
+import type {
+  AnySettlementMethod,
+  CheckoutContext,
+  CheckoutStep,
+  CheckoutStepRender,
+} from "../types";
+
+export const DADOS_STEP_ID = "dados";
+export const METHOD_STEP_ID = "method";
+
+/**
+ * The server's own code for "the chain asked for a field this buyer has not
+ * given" — and the code the local gate raises, so a refusal the browser can
+ * see and one the server sends land on the same step, worded the same way.
+ */
+export const BUYER_FIELD_CODE = "MISSING_BUYER_FIELD";
+
+/** Whether the shopper has opened the buyer-details step, and finished it. */
+interface DadosSlice {
+  /**
+   * A shopper whose CPF is on file never sees this step — until they press
+   * "alterar", after which it IS part of their flow and back returns to it.
+   * That is the whole of `useCheckoutNav`'s `dadosOpened`.
+   */
+  opened: boolean;
+  done: boolean;
+}
+
+const DADOS_INITIAL: DadosSlice = Object.freeze({ opened: false, done: false });
+
+/** Trust nothing out of storage: two booleans, or nothing at all. */
+export function parseDadosSlice(raw: unknown): DadosSlice | null {
+  if (typeof raw !== "object" || raw === null) return null;
+  const candidate = raw as Partial<DadosSlice>;
+  if (typeof candidate.opened !== "boolean") return null;
+  if (typeof candidate.done !== "boolean") return null;
+  return { opened: candidate.opened, done: candidate.done };
+}
+
+/** The buyer-details slice as the whole walk reads it. */
+export function dadosSliceOf(ctx: CheckoutContext): DadosSlice {
+  return parseDadosSlice(ctx.slices[DADOS_STEP_ID]) ?? DADOS_INITIAL;
+}
+
+function DadosView({ ctx, error }: CheckoutStepRender<DadosSlice>): JSX.Element {
+  const actions = usePipelineActions();
+  const BuyerDetails = actions.screens.BuyerDetails;
+  const field = error?.field ?? null;
+  return (
+    <BuyerDetails
+      value={ctx.buyer}
+      onChange={actions.setBuyer}
+      method={isPackageMethod(ctx.method) ? ctx.method : null}
+      onContinue={actions.continueFromDados}
+      error={field && error ? { field, message: error.message } : null}
+    />
+  );
+}
+
+/**
+ * WHO IS PAYING.
+ *
+ * `applies` is the FUT-465 skip, stated as a fact rather than as an initial
+ * step: a shopper with a CPF on file has nothing left to answer here, so the
+ * step is not part of their walk — which is also why back off the next step
+ * takes them to the catalog rather than to a form they never saw.
+ */
+export const dadosStep: CheckoutStep<DadosSlice> = {
+  id: DADOS_STEP_ID,
+  phase: "details",
+  order: 0,
+  label: "dados",
+  applies(ctx) {
+    return !ctx.taxIdOnFile || dadosSliceOf(ctx).opened;
+  },
+  complete(_ctx, _facts, slice) {
+    return slice.done;
+  },
+  slice: {
+    initial: () => DADOS_INITIAL,
+    persist: "session",
+    parse: parseDadosSlice,
+  },
+  // The two refusals that are ABOUT a field on this form. Anything else the
+  // create can answer is not something retyping a name will fix.
+  answersCodes: [BUYER_FIELD_CODE, "EMAIL_EQUALS_MERCHANT"],
+  contribute(ctx) {
+    return { buyer: ctx.buyer };
+  },
+  render(props) {
+    return <DadosView {...props} />;
+  },
+};
+
+/** Which settlement method the shopper picked. */
+interface MethodSlice {
+  chosen: string | null;
+}
+
+const METHOD_INITIAL: MethodSlice = Object.freeze({ chosen: null });
+
+/** A method id is a string or nothing — never an object a shopper edited in. */
+function parseMethodSlice(raw: unknown): MethodSlice | null {
+  if (typeof raw !== "object" || raw === null) return null;
+  const chosen = (raw as Partial<MethodSlice>).chosen;
+  if (chosen === null) return { chosen: null };
+  return typeof chosen === "string" ? { chosen } : null;
+}
+
+/** The chosen method, as the engine reads it back out of the slices. */
+export function methodSliceOf(slices: Readonly<Record<string, unknown>>): MethodSlice {
+  return parseMethodSlice(slices[METHOD_STEP_ID]) ?? METHOD_INITIAL;
+}
+
+/** One registered method as a tile, for the methods the package cannot draw. */
+function MethodTiles({ ctx }: { ctx: CheckoutContext }): JSX.Element {
+  const { Button, Text } = useCheckoutComponents();
+  const actions = usePipelineActions();
+  return (
+    <Box role="radiogroup" data-testid="checkout-method" sx={{ display: "flex", gap: 1 }}>
+      {actions.offered.map((method) => {
+        const tile = method.tile(actions.copy);
+        return (
+          <Box key={method.id} sx={{ flex: 1, minWidth: 0 }}>
+            <Button
+              variant={ctx.method === method.id ? "solid" : "outline"}
+              color="primary"
+              size="md"
+              fullWidth
+              onClick={() => actions.choose(method.id)}
+              dataTestId={`checkout-method-${method.id}`}
+            >
+              {tile.label}
+            </Button>
+            {tile.hint === undefined ? null : (
+              <Text variant="caption" size="xs" color="secondary" as="p">
+                {tile.hint}
+              </Text>
+            )}
+          </Box>
+        );
+      })}
+    </Box>
+  );
+}
+
+/**
+ * HOW they are paying.
+ *
+ * The package's own picker renders whenever the offer is the package's own two
+ * methods — with its disabled-card caption and its sole-method preselect
+ * intact, because those are decisions about PIX and CARD specifically. A host
+ * that registers a method of its own gets the generic tiles, which is the only
+ * shape that can draw a method this package has never heard of.
+ */
+function MethodView({ ctx, error }: CheckoutStepRender<MethodSlice>): JSX.Element {
+  const actions = usePipelineActions();
+  const MethodChoice = actions.screens.MethodChoice;
+  const packageOnly = actions.offered.every((method) => isPackageMethod(method.id));
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
+      <PayerBlock ctx={ctx} />
+      {packageOnly ? (
+        <MethodChoice
+          value={isPackageMethod(ctx.method) ? ctx.method : null}
+          onChange={(method: PaymentMethod) => actions.choose(method)}
+        />
+      ) : (
+        <MethodTiles ctx={ctx} />
+      )}
+      <MethodRefusal error={error} />
+    </Box>
+  );
+}
+
+/**
+ * A REFUSAL THE PICKER HAS TO DRAW, because it is where the shopper is.
+ *
+ * The routing hands a step every refusal nobody more specific claimed — the
+ * unclaimed ones, and the ones whose gate is passing and therefore drawing
+ * nothing (`refusal-routing.ts`). Raising the payable fails from HERE, so this
+ * is the step those land on, and a picker that ignored the prop would leave the
+ * shopper tapping a tile that answers nothing.
+ *
+ * `PaymentErrorPanel` rather than a bare Alert: it is the same panel the flat
+ * flow's Pagamento step draws, and it carries the rule that matters most — an
+ * UNRESOLVED charge gets a warning and NO retry, because some provider may be
+ * holding the buyer's money and a retry mints a second order.
+ *
+ * `emailFlagged` is FALSE here and cannot be otherwise: the one refusal that
+ * offer answers, `EMAIL_EQUALS_MERCHANT`, is claimed by the buyer-details step
+ * (`dadosStep.answersCodes`), so the routing sends that shopper to the form
+ * holding the e-mail field instead of offering a second copy of it under a
+ * picker. `onUseEmail` is consequently unreachable, and is the buyer-details
+ * door rather than a no-op so that it stays true if the claim ever moves.
+ */
+function MethodRefusal({ error }: { error: CheckoutStepRender<MethodSlice>["error"] }): JSX.Element | null {
+  const actions = usePipelineActions();
+  const openDados = actions.editBuyer;
+  if (!error) return null;
+  return (
+    <PaymentErrorPanel
+      message={error.message}
+      emailFlagged={false}
+      code={error.code}
+      onUseEmail={() => openDados?.()}
+      onRetry={actions.place}
+    />
+  );
+}
+
+/**
+ * WHO IS BEING CHARGED, and the door back to changing it.
+ *
+ * Drawn only for a shopper whose buyer-details step was SKIPPED — the same
+ * rule the flat flow applies, and for the same reason: a shopper who filled
+ * the form themselves is looking at what they just typed, and a summary of it
+ * is a second copy of the same screen. Its presence is `editBuyer`'s presence,
+ * which the engine derives once (`deriveNav`) rather than each caller guessing.
+ */
+function PayerBlock({ ctx }: { ctx: CheckoutContext }): JSX.Element | null {
+  const actions = usePipelineActions();
+  const PayerSummary = actions.screens.PayerSummary;
+  if (!actions.editBuyer) return null;
+  return <PayerSummary buyer={ctx.buyer} onEdit={actions.editBuyer} />;
+}
+
+/** A chosen method whose descriptor wants a review has not finished this step. */
+function methodSettled(ctx: CheckoutContext, methods: readonly AnySettlementMethod[]): boolean {
+  if (ctx.method === null) return false;
+  const descriptor = methods.find((entry) => entry.id === ctx.method);
+  if (descriptor?.Review && ctx.order === null) return false;
+  return true;
+}
+
+/** Built over the MERGED descriptor list, which is a factory-scope constant. */
+export function buildMethodStep(
+  methods: readonly AnySettlementMethod[],
+): CheckoutStep<MethodSlice> {
+  return {
+    id: METHOD_STEP_ID,
+    phase: "before-pay",
+    order: 0,
+    label: "payment",
+    applies(ctx) {
+      return ctx.outcome === null;
+    },
+    complete(ctx) {
+      return methodSettled(ctx, methods);
+    },
+    slice: {
+      initial: () => METHOD_INITIAL,
+      persist: "session",
+      parse: parseMethodSlice,
+    },
+    render(props) {
+      return <MethodStepBody {...props} methods={methods} />;
+    },
+  };
+}
+
+/** The picker, or the chosen descriptor's own review of what is about to happen. */
+function MethodStepBody(
+  props: CheckoutStepRender<MethodSlice> & { methods: readonly AnySettlementMethod[] },
+): JSX.Element {
+  const actions = usePipelineActions();
+  const descriptor = props.methods.find((entry) => entry.id === props.ctx.method);
+  const Review = descriptor?.Review;
+  if (Review && props.ctx.order === null) {
+    return (
+      <Review
+        ctx={props.ctx}
+        place={actions.place}
+        placing={actions.placing}
+        error={props.error}
+      />
+    );
+  }
+  return <MethodView {...props} />;
+}

package/src/flows/pipeline/steps/index.ts

@@ -0,0 +1,54 @@
+/**
+ * The SEVEN screens this package already shipped, wrapped as steps (FUT-1240).
+ *
+ * Buyer details, the method picker, the Pix pane, the card pane, the hand-off
+ * interstitial, the return from one, and the confirmation. Each wrapper is
+ * thin by design: the behaviour stays in `components/checkout/*` and in the
+ * screens `flows/screens-*.tsx` already binds, and what is added here is only
+ * WHERE each one sits in a walk that is derived rather than switched on.
+ *
+ * The RETURN step is the one that is not a bare wrapper, and the reason is
+ * worth stating: `screens.HostedReturn` owns its own read of the parked entry,
+ * which is right for a host mounting it at a dedicated return route and wrong
+ * inside a checkout that already knows the slug and the basket. So the step
+ * runs `useHostedResume` — the package's own FUT-1213 rule, deferral and
+ * server ASK included — and renders the confirmation while it waits.
+ */
+import type { FlowsRuntime } from "../../runtime";
+import type { AnyCheckoutStep, AnySettlementMethod } from "../types";
+
+import { buildMethodStep, dadosStep } from "./buyer-steps";
+import { buildResumeStep, cardStep, handoffStep, pixStep } from "./pay-steps";
+import { statusStep } from "./status-step";
+
+export {
+  BUYER_FIELD_CODE,
+  DADOS_STEP_ID,
+  METHOD_STEP_ID,
+  dadosSliceOf,
+  methodSliceOf,
+} from "./buyer-steps";
+export { HANDOFF_STEP_ID, RESUME_STEP_ID } from "./pay-steps";
+export { STATUS_STEP_ID } from "./status-step";
+
+/**
+ * The package's own steps, built once per factory.
+ *
+ * The returned array is a factory-scope constant — never rebuilt — because
+ * every registered plugin's `useFacts()` runs in array order and React's hook
+ * identity is positional. See `stable-plugins.ts`.
+ */
+export function packageSteps(
+  runtime: FlowsRuntime,
+  methods: readonly AnySettlementMethod[],
+): readonly AnyCheckoutStep[] {
+  return Object.freeze([
+    buildResumeStep(runtime),
+    dadosStep,
+    buildMethodStep(methods),
+    pixStep,
+    cardStep,
+    handoffStep,
+    statusStep,
+  ]);
+}

package/src/flows/pipeline/steps/pay-steps.tsx

@@ -0,0 +1,182 @@
+/**
+ * THE PAY PHASE (FUT-1240): the Pix code, the card form, the hand-off, and the
+ * return from one.
+ *
+ * Every step here is `phase: "pay"` except the resume, and that matters: the
+ * engine drops the whole phase for a settlement method whose `raisesCharge` is
+ * `false`. So a shopper paying the courier never reaches any of these, and no
+ * lane has to remember not to render them.
+ *
+ * The resume is `before-pay` rather than `pay` deliberately. A shopper coming
+ * back from a provider's own page has to be resolved BEFORE they are offered a
+ * way to pay again — and the same screen has to work for an in-person method,
+ * which has no pay phase at all.
+ */
+import { Box } from "@mui/material";
+import { useEffect, type JSX } from "react";
+
+import { useCheckoutComponents } from "../../../components/checkout/ui";
+import { useHostedResume, type HostedResume } from "../../../components/checkout/use-hosted-resume";
+import type { FlowsRuntime } from "../../runtime";
+import { usePipelineActions } from "../actions";
+import { CARD_PANE_STEP, PIX_PANE_STEP } from "../methods";
+import type { CheckoutStep, CheckoutStepRender } from "../types";
+
+export const HANDOFF_STEP_ID = "handoff";
+export const RESUME_STEP_ID = "resume";
+
+/** A raised order whose provider takes the money on its own page. */
+function handedOver(url: string | undefined): url is string {
+  return typeof url === "string" && url.length > 0;
+}
+
+function PixView({ ctx }: CheckoutStepRender<void>): JSX.Element | null {
+  const actions = usePipelineActions();
+  const PixPayment = actions.screens.PixPayment;
+  if (!ctx.order) return null;
+  return <PixPayment payable={ctx.order} onResolved={actions.resolve} />;
+}
+
+function CardView({ ctx }: CheckoutStepRender<void>): JSX.Element | null {
+  const actions = usePipelineActions();
+  const CardEntry = actions.screens.CardEntry;
+  if (!ctx.order) return null;
+  return <CardEntry payable={ctx.order} onResolved={actions.resolve} />;
+}
+
+/**
+ * The Pix code, once one exists.
+ *
+ * WHICH method this pane belongs to is not asked here: the engine reads it off
+ * the descriptor that named this step as its `pane`, so a method the package
+ * has never heard of can reuse the pane by naming it, and no pane states its
+ * own method twice.
+ */
+export const pixStep: CheckoutStep = {
+  id: PIX_PANE_STEP,
+  phase: "pay",
+  order: 0,
+  applies(ctx) {
+    return ctx.order !== null && !handedOver(ctx.order.hostedCheckoutUrl);
+  },
+  complete(ctx) {
+    return ctx.outcome !== null;
+  },
+  render(props) {
+    return <PixView {...props} />;
+  },
+};
+
+/** The card form, once an order exists to charge. Its method is its `pane` owner. */
+export const cardStep: CheckoutStep = {
+  id: CARD_PANE_STEP,
+  phase: "pay",
+  order: 1,
+  applies(ctx) {
+    return ctx.order !== null && !handedOver(ctx.order.hostedCheckoutUrl);
+  },
+  complete(ctx) {
+    return ctx.outcome !== null;
+  },
+  render(props) {
+    return <CardView {...props} />;
+  },
+};
+
+/**
+ * The hand-off interstitial: the order is parked and the tab is leaving.
+ *
+ * `complete` is `false` forever on purpose — there is no next step on THIS
+ * page. What comes back is a fresh mount that meets the resume step.
+ */
+function HandoffView({ ctx, back }: CheckoutStepRender<void>): JSX.Element | null {
+  const { Text } = useCheckoutComponents();
+  const actions = usePipelineActions();
+  const HostedHandoff = actions.screens.HostedHandoff;
+  const url = ctx.order?.hostedCheckoutUrl;
+  if (!ctx.order || !handedOver(url)) return null;
+  const pipeline = actions.copy.pipeline;
+  const waiting =
+    (ctx.method === null ? undefined : pipeline.awaitingHandover[ctx.method]) ?? pipeline.loading;
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 1 }}>
+      <Text variant="body" size="sm" color="secondary" as="p" data-testid="checkout-awaiting-handover">
+        {waiting}
+      </Text>
+      <HostedHandoff url={url} payable={ctx.order} onCancel={back} />
+    </Box>
+  );
+}
+
+export const handoffStep: CheckoutStep = {
+  id: HANDOFF_STEP_ID,
+  phase: "pay",
+  order: 2,
+  applies(ctx) {
+    return ctx.order !== null && handedOver(ctx.order.hostedCheckoutUrl);
+  },
+  complete() {
+    return false;
+  },
+  render(props) {
+    return <HandoffView {...props} />;
+  },
+};
+
+/**
+ * A shopper coming back from a provider's own page.
+ *
+ * It runs the package's OWN resume machinery — `useHostedResume`, with this
+ * checkout's slug and basket — rather than a second reading of the parked
+ * entry. That matters more than the extra hook: `useHostedResume` carries the
+ * whole FUT-1213 rule, including the deferral until the cart has answered, the
+ * bounded wait when it never does, and the one server ASK for a basket that
+ * has changed. A step that re-implemented "is something parked?" would be a
+ * second answer to a question with one correct one, on the money path.
+ *
+ * WHERE a resume lands is `hosted-return.ts`'s decision, honoured here:
+ *
+ *  - a HAND-OFF has nothing left on our page, so it waits on the confirmation
+ *    until the poll reaches a terminal state;
+ *  - anything else — a Pix code, a card charge raised on our own page — is
+ *    ADOPTED as this visit's order, and the walk puts the shopper back in
+ *    front of the pane that still has what they need.
+ */
+export function buildResumeStep(runtime: FlowsRuntime): CheckoutStep<void, HostedResume> {
+  return {
+    id: RESUME_STEP_ID,
+    phase: "before-pay",
+    order: -10,
+    useFacts() {
+      const tenantSlug = runtime.useTenantSlug();
+      const cart = runtime.config.useCart();
+      return useHostedResume(tenantSlug, cart.identity);
+    },
+    applies(ctx, resume) {
+      return ctx.outcome === null && ctx.order === null && resume.order !== null;
+    },
+    complete(ctx) {
+      return ctx.outcome !== null || ctx.order !== null;
+    },
+    render({ facts }) {
+      return <ResumeView resume={facts} />;
+    },
+  };
+}
+
+/** The resumed order, taken up by whichever half of the walk owns it. */
+function ResumeView({ resume }: { resume: HostedResume }): JSX.Element | null {
+  const actions = usePipelineActions();
+  const { adoptOrder, resolve } = actions;
+  const { order, step, status } = resume;
+  useEffect(() => {
+    if (!order) return;
+    // An on-page charge belongs to the WALK, not to this screen: adopting it
+    // makes the pane apply on the very next render.
+    if (step === "payment") adoptOrder(order);
+    else if (status !== null && status !== "AWAITING_PAYMENT") resolve(status);
+  }, [order, step, status, adoptOrder, resolve]);
+  if (!order || step === "payment") return null;
+  const PaymentStatus = actions.screens.PaymentStatus;
+  return <PaymentStatus status={status} payable={order} />;
+}

package/src/flows/pipeline/steps/status-step.tsx

@@ -0,0 +1,41 @@
+/**
+ * THE CONFIRMATION (FUT-1240) — the one step every settlement reaches.
+ *
+ * `complete` is `false` forever: a walk whose last step is finished has
+ * nowhere to put the shopper, and this is where a checkout ends. The
+ * registered method may replace the screen entirely (`Confirmation` on its
+ * descriptor), which is how a settlement that raises no charge says
+ * "recebemos seu pedido" instead of "pagamento aprovado" without the engine
+ * knowing either sentence.
+ */
+import type { JSX } from "react";
+
+import { descriptorFor, usePipelineActions } from "../actions";
+import type { CheckoutStep, CheckoutStepRender } from "../types";
+
+export const STATUS_STEP_ID = "status";
+
+function StatusView({ ctx }: CheckoutStepRender<void>): JSX.Element {
+  const actions = usePipelineActions();
+  const descriptor = descriptorFor(actions.methods, ctx);
+  const Confirmation = descriptor?.Confirmation;
+  if (Confirmation && ctx.order) return <Confirmation ctx={ctx} order={ctx.order} />;
+  const PaymentStatus = actions.screens.PaymentStatus;
+  return <PaymentStatus status={ctx.outcome} payable={ctx.order} />;
+}
+
+export const statusStep: CheckoutStep = {
+  id: STATUS_STEP_ID,
+  phase: "after-pay",
+  order: 0,
+  label: "status",
+  applies(ctx) {
+    return ctx.outcome !== null;
+  },
+  complete() {
+    return false;
+  },
+  render(props) {
+    return <StatusView {...props} />;
+  },
+};