@vtex/faststore 0.0.8 → 0.0.11

package/dist/sdk/payment/resumed-purchase.js

@@ -0,0 +1,119 @@
+"use client";
+import { loggableErrorName } from "../../utils/loggable-error-name.js";
+import { SETTLED_ORDER_FACTS } from "./operations.js";
+import { getApolloContext } from "@apollo/client/react";
+import { useCallback, useContext } from "react";
+//#region src/sdk/payment/resumed-purchase.ts
+/**
+* The `purchase` analytics event for an order that was finished on a second call: the in-page resume
+* that `usePlaceOrder` runs, and the return page the bank sends the shopper to (T208, RFC D23).
+*
+* The attempt record may carry no value or currency (T29 FR-7), and a resume holds no transaction, so
+* both are read from the settled order. Every `purchase` in this package goes through `claimPurchase`,
+* so an order is reported once whichever path finished it.
+*/
+const PURCHASE_MARKER_PREFIX = "fs:purchase-sent:";
+/** Only used when storage cannot be read or written: one page lifetime still reports an order once. */
+const claimedInMemory = /* @__PURE__ */ new Set();
+/**
+* A synchronous check-and-set on `localStorage`, keyed on the order group and holding `1`, never a value, a
+* currency or anything about the shopper. The key is written before the caller emits, so an emission that
+* throws is still never repeated. Two browsers may each report one order once (ruled 2026-10-14); the marker
+* never expires and no server holds it.
+*/
+function claimPurchase(orderGroup) {
+	const key = `${PURCHASE_MARKER_PREFIX}${orderGroup}`;
+	try {
+		if (localStorage.getItem(key) !== null) return false;
+		localStorage.setItem(key, "1");
+		return true;
+	} catch {
+		if (claimedInMemory.has(key)) return false;
+		claimedInMemory.add(key);
+		return true;
+	}
+}
+/**
+* The budget for the settled-order read: a hung read must not hold the shopper on a blank return page. A
+* local race with a cleared timer, mirroring the API's own ten-second default. On expiry nothing is
+* reported and the flow goes on.
+*/
+const SETTLED_ORDER_READ_TIMEOUT_MS = 1e4;
+const ABANDONED = Symbol("abandoned");
+async function readWithinBudget(readOrder, orderNodeId) {
+	let timer;
+	const deadline = new Promise((resolve) => {
+		timer = setTimeout(() => resolve(ABANDONED), SETTLED_ORDER_READ_TIMEOUT_MS);
+	});
+	try {
+		return await Promise.race([readOrder(orderNodeId), deadline]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* Reads a settled order for the resume paths. `null` without an Apollo client, so a story or a test rendered
+* with no provider has no read and reports no purchase; the client is taken from Apollo's context rather than
+* `useApolloClient()`, which throws without one.
+*/
+function useSettledOrderRead() {
+	const { client } = useContext(getApolloContext());
+	const read = useCallback(async (orderNodeId) => {
+		if (!client) return null;
+		const { data } = await client.query({
+			query: SETTLED_ORDER_FACTS,
+			variables: { id: orderNodeId },
+			fetchPolicy: "network-only"
+		});
+		const order = data?.order;
+		if (!order) return null;
+		const { reference, status, total } = order;
+		return {
+			reference,
+			status,
+			total: total ? {
+				amount: total.amount,
+				currencyCode: total.currencyCode
+			} : null
+		};
+	}, [client]);
+	return client ? read : null;
+}
+/**
+* Reports the purchase of an order a resume just finished. Reads the order (under the budget), then emits
+* unless it is `DENIED` or carries no total: an order that failed is not a sale, and one without a total has
+* no value to report. `PENDING` (anti-fraud review) and `UNKNOWN` report, as the direct path reports a
+* placed order without reading its status. The marker is claimed only after those checks, so an order that
+* was not reported is not burned.
+*
+* Never rejects and never throws: the order is finished whether or not the event could be sent, so a read
+* that fails, a tracker that throws or storage that refuses must not change what the shopper sees.
+*/
+async function emitPurchaseForOrder({ track, readOrder, orderNodeId }) {
+	if (!track || !readOrder) return;
+	let facts;
+	try {
+		facts = await readWithinBudget(readOrder, orderNodeId);
+	} catch (error) {
+		console.error("[payment.purchase] the settled order could not be read", loggableErrorName(error));
+		return;
+	}
+	if (facts === ABANDONED || facts === null || facts.status === "DENIED" || facts.total === null) return;
+	if (!claimPurchase(facts.reference)) return;
+	try {
+		track({
+			name: "purchase",
+			transactionId: facts.reference,
+			value: {
+				amount: Number(facts.total.amount),
+				currencyCode: facts.total.currencyCode
+			}
+		});
+	} catch (error) {
+		console.error("[payment.purchase] the purchase event could not be sent", loggableErrorName(error));
+	}
+}
+//#endregion
+export { SETTLED_ORDER_READ_TIMEOUT_MS, claimPurchase, emitPurchaseForOrder, useSettledOrderRead };
+
+//# sourceMappingURL=resumed-purchase.js.map

package/dist/sdk/payment/resumed-purchase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumed-purchase.js","names":[],"sources":["../../../src/sdk/payment/resumed-purchase.ts"],"sourcesContent":["'use client';\n\nimport { getApolloContext } from '@apollo/client/react';\nimport { useCallback, useContext } from 'react';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport type { AnalyticsActions } from '../analytics/use-analytics-actions.js';\nimport { SETTLED_ORDER_FACTS } from './operations.js';\n\n/**\n * The `purchase` analytics event for an order that was finished on a second call: the in-page resume\n * that `usePlaceOrder` runs, and the return page the bank sends the shopper to (T208, RFC D23).\n *\n * The attempt record may carry no value or currency (T29 FR-7), and a resume holds no transaction, so\n * both are read from the settled order. Every `purchase` in this package goes through `claimPurchase`,\n * so an order is reported once whichever path finished it.\n */\n\nconst PURCHASE_MARKER_PREFIX = 'fs:purchase-sent:';\n\n/** Only used when storage cannot be read or written: one page lifetime still reports an order once. */\nconst claimedInMemory = new Set<string>();\n\n/**\n * A synchronous check-and-set on `localStorage`, keyed on the order group and holding `1`, never a value, a\n * currency or anything about the shopper. The key is written before the caller emits, so an emission that\n * throws is still never repeated. Two browsers may each report one order once (ruled 2026-10-14); the marker\n * never expires and no server holds it.\n */\nexport function claimPurchase(orderGroup: string): boolean {\n  const key = `${PURCHASE_MARKER_PREFIX}${orderGroup}`;\n  try {\n    if (localStorage.getItem(key) !== null) return false;\n    localStorage.setItem(key, '1');\n    return true;\n  } catch {\n    if (claimedInMemory.has(key)) return false;\n    claimedInMemory.add(key);\n    return true;\n  }\n}\n\nexport type SettledOrderFacts = Readonly<{\n  reference: string;\n  status: 'APPROVED' | 'PENDING' | 'DENIED' | 'UNKNOWN';\n  total: Readonly<{ amount: string; currencyCode: string }> | null;\n}>;\n\nexport type SettledOrderRead = (orderNodeId: string) => Promise<SettledOrderFacts | null>;\n\n/**\n * The budget for the settled-order read: a hung read must not hold the shopper on a blank return page. A\n * local race with a cleared timer, mirroring the API's own ten-second default. On expiry nothing is\n * reported and the flow goes on.\n */\nexport const SETTLED_ORDER_READ_TIMEOUT_MS = 10_000;\n\nconst ABANDONED = Symbol('abandoned');\n\nasync function readWithinBudget(\n  readOrder: SettledOrderRead,\n  orderNodeId: string,\n): Promise<SettledOrderFacts | null | typeof ABANDONED> {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const deadline = new Promise<typeof ABANDONED>((resolve) => {\n    timer = setTimeout(() => resolve(ABANDONED), SETTLED_ORDER_READ_TIMEOUT_MS);\n  });\n  try {\n    return await Promise.race([readOrder(orderNodeId), deadline]);\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\n/**\n * Reads a settled order for the resume paths. `null` without an Apollo client, so a story or a test rendered\n * with no provider has no read and reports no purchase; the client is taken from Apollo's context rather than\n * `useApolloClient()`, which throws without one.\n */\nexport function useSettledOrderRead(): SettledOrderRead | null {\n  const { client } = useContext(getApolloContext());\n\n  const read = useCallback<SettledOrderRead>(\n    async (orderNodeId) => {\n      if (!client) return null;\n      const { data } = await client.query({\n        query: SETTLED_ORDER_FACTS,\n        variables: { id: orderNodeId },\n        fetchPolicy: 'network-only',\n      });\n      const order = data?.order;\n      if (!order) return null;\n      const { reference, status, total } = order;\n      return {\n        reference,\n        status,\n        total: total ? { amount: total.amount, currencyCode: total.currencyCode } : null,\n      };\n    },\n    [client],\n  );\n\n  return client ? read : null;\n}\n\n/**\n * Reports the purchase of an order a resume just finished. Reads the order (under the budget), then emits\n * unless it is `DENIED` or carries no total: an order that failed is not a sale, and one without a total has\n * no value to report. `PENDING` (anti-fraud review) and `UNKNOWN` report, as the direct path reports a\n * placed order without reading its status. The marker is claimed only after those checks, so an order that\n * was not reported is not burned.\n *\n * Never rejects and never throws: the order is finished whether or not the event could be sent, so a read\n * that fails, a tracker that throws or storage that refuses must not change what the shopper sees.\n */\nexport async function emitPurchaseForOrder({\n  track,\n  readOrder,\n  orderNodeId,\n}: {\n  track: AnalyticsActions['track'] | null | undefined;\n  readOrder: SettledOrderRead | null | undefined;\n  orderNodeId: string;\n}): Promise<void> {\n  if (!track || !readOrder) return;\n\n  let facts: SettledOrderFacts | null | typeof ABANDONED;\n  try {\n    facts = await readWithinBudget(readOrder, orderNodeId);\n  } catch (error) {\n    console.error('[payment.purchase] the settled order could not be read', loggableErrorName(error));\n    return;\n  }\n  if (facts === ABANDONED || facts === null || facts.status === 'DENIED' || facts.total === null) return;\n\n  if (!claimPurchase(facts.reference)) return;\n  try {\n    track({\n      name: 'purchase',\n      transactionId: facts.reference,\n      value: { amount: Number(facts.total.amount), currencyCode: facts.total.currencyCode },\n    });\n  } catch (error) {\n    console.error('[payment.purchase] the purchase event could not be sent', loggableErrorName(error));\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AAiBA,MAAM,yBAAyB;;AAG/B,MAAM,kCAAkB,IAAI,IAAY;;;;;;;AAQxC,SAAgB,cAAc,YAA6B;CACzD,MAAM,MAAM,GAAG,yBAAyB;CACxC,IAAI;EACF,IAAI,aAAa,QAAQ,GAAG,MAAM,MAAM,OAAO;EAC/C,aAAa,QAAQ,KAAK,GAAG;EAC7B,OAAO;CACT,QAAQ;EACN,IAAI,gBAAgB,IAAI,GAAG,GAAG,OAAO;EACrC,gBAAgB,IAAI,GAAG;EACvB,OAAO;CACT;AACF;;;;;;AAeA,MAAa,gCAAgC;AAE7C,MAAM,YAAY,OAAO,WAAW;AAEpC,eAAe,iBACb,WACA,aACsD;CACtD,IAAI;CACJ,MAAM,WAAW,IAAI,SAA2B,YAAY;EAC1D,QAAQ,iBAAiB,QAAQ,SAAS,GAAG,6BAA6B;CAC5E,CAAC;CACD,IAAI;EACF,OAAO,MAAM,QAAQ,KAAK,CAAC,UAAU,WAAW,GAAG,QAAQ,CAAC;CAC9D,UAAU;EACR,aAAa,KAAK;CACpB;AACF;;;;;;AAOA,SAAgB,sBAA+C;CAC7D,MAAM,EAAE,WAAW,WAAW,iBAAiB,CAAC;CAEhD,MAAM,OAAO,YACX,OAAO,gBAAgB;EACrB,IAAI,CAAC,QAAQ,OAAO;EACpB,MAAM,EAAE,SAAS,MAAM,OAAO,MAAM;GAClC,OAAO;GACP,WAAW,EAAE,IAAI,YAAY;GAC7B,aAAa;EACf,CAAC;EACD,MAAM,QAAQ,MAAM;EACpB,IAAI,CAAC,OAAO,OAAO;EACnB,MAAM,EAAE,WAAW,QAAQ,UAAU;EACrC,OAAO;GACL;GACA;GACA,OAAO,QAAQ;IAAE,QAAQ,MAAM;IAAQ,cAAc,MAAM;GAAa,IAAI;EAC9E;CACF,GACA,CAAC,MAAM,CACT;CAEA,OAAO,SAAS,OAAO;AACzB;;;;;;;;;;;AAYA,eAAsB,qBAAqB,EACzC,OACA,WACA,eAKgB;CAChB,IAAI,CAAC,SAAS,CAAC,WAAW;CAE1B,IAAI;CACJ,IAAI;EACF,QAAQ,MAAM,iBAAiB,WAAW,WAAW;CACvD,SAAS,OAAO;EACd,QAAQ,MAAM,0DAA0D,kBAAkB,KAAK,CAAC;EAChG;CACF;CACA,IAAI,UAAU,aAAa,UAAU,QAAQ,MAAM,WAAW,YAAY,MAAM,UAAU,MAAM;CAEhG,IAAI,CAAC,cAAc,MAAM,SAAS,GAAG;CACrC,IAAI;EACF,MAAM;GACJ,MAAM;GACN,eAAe,MAAM;GACrB,OAAO;IAAE,QAAQ,OAAO,MAAM,MAAM,MAAM;IAAG,cAAc,MAAM,MAAM;GAAa;EACtF,CAAC;CACH,SAAS,OAAO;EACd,QAAQ,MAAM,2DAA2D,kBAAkB,KAAK,CAAC;CACnG;AACF"}

package/dist/sdk/payment/security-code-mask.js

@@ -39,33 +39,26 @@
 */
 const SECURITY_CODE_MASK_STYLE = Object.freeze({ WebkitTextSecurity: "disc" });
 /**
-* Whether the security code is fully typed — the moment `SECURITY_CODE_MASK_STYLE` above starts
-* applying (specs/mask-the-cvv-only-once-it.md, T173). Until then the field renders its digits in
-* the clear, so a shopper can read back what they just typed and catch a typo; from then on it
-* renders exactly as it did when the mask was unconditional. The mechanism is untouched; only its
-* timing moves. Never on blur, never after a delay: the mask engages on the keystroke that completes
-* the code.
+* Whether the security code is obscured: while it is non-empty and its input does not have focus
+* (specs/stop-sending-a-stale-non-displayable-cardholder.md, T34, reversing the T173 timing that
+* obscured a code the instant its last digit arrived). A shopper who is still in the field can read
+* back what they typed and catch a typo; the moment focus leaves, nothing is left legible. The
+* mechanism is untouched; only its timing moves.
 *
-* `expectedLength` is passed in because the two fields resolve it from different places and neither
-* belongs in this module: `CardEntry` takes the detected network's `cvvMask` (three digits for most
-* networks, four for Amex), while `SavedCardCvvField` has no per-network length at all and uses its
-* own three-or-four-digit floor. Resolving it here would mean knowing about payment-method validators
-* and saved-card rows, and would still leave the comparison itself free to drift between the two.
+* `focused` is passed in already folded with whatever else disables the input: a browser fires no
+* `blur` when a focused element becomes disabled, so each caller counts a disabled input as
+* unfocused. This function knows nothing about `disabled`.
 *
-* Both callers resolve a *floor*, and a ceiling would be a defect rather than a variation: whatever
-* length arrives here is the length at which digits stop being legible, so the widest of several
-* possible lengths leaves a code that is already complete for a shorter one readable for the rest of
-* the flow.
-*
-* Derived from the value on every render, with no state and no timer. That is what makes the render
-* which first holds a complete code already the masked one — so a paste delivering every digit in one
-* event opens no legible frame — lets a cleared field unmask with nothing to reset, and leaves a code
-* the shopper backspaces into legible again while they correct it.
+* Derived from the value and the focus flag on every render, never from an effect or a timer. That
+* is what makes the render which first holds an unfocused code already the masked one — so a paste or
+* a browser autofill delivering every digit in one event, and the blur itself, open no legible frame.
+* The length of the code plays no part: the mask no longer needs a per-network or per-field length,
+* and a partial code is hidden on blur like a complete one.
 */
-function isSecurityCodeComplete(value, expectedLength) {
-	return value.length > 0 && value.length >= expectedLength;
+function isSecurityCodeMasked(value, focused) {
+	return value.length > 0 && !focused;
 }
 //#endregion
-export { SECURITY_CODE_MASK_STYLE, isSecurityCodeComplete };
+export { SECURITY_CODE_MASK_STYLE, isSecurityCodeMasked };
 
 //# sourceMappingURL=security-code-mask.js.map

package/dist/sdk/payment/security-code-mask.js.map

@@ -1 +1 @@
-{"version":3,"file":"security-code-mask.js","names":[],"sources":["../../../src/sdk/payment/security-code-mask.ts"],"sourcesContent":["import type { CSSProperties } from 'react';\n\n/**\n * The security-code masking mechanism (specs/choose-a-security-code-masking-mechanism.md, T101 of\n * the Credit Card epic; docs/features/credit-card/rfc.md § D13). One shared constant for the two\n * inputs that hold a security code — `CardEntry`'s `cvv` field and `SavedCardCvvField`'s CVV\n * re-entry field — so the two call sites cannot drift on the mechanism.\n *\n * Why this and not `type=\"password\"`: T70 shipped `type=\"password\"` on both fields and it made real\n * Chrome offer a \"Save password?\" prompt on the new-card form — pairing the expiration date as a\n * fake *Username* and the security code as *Password*, and offering to store it in Google Password\n * Manager, synced to the signed-in account. PCI-DSS forbids retaining the security code past\n * authorization, and a cloud-synced credential vault is a strictly worse posture than the field's\n * pre-T70 baseline. `type=\"password\"` was reverted; both fields ship `type=\"text\"`.\n *\n * `-webkit-text-security: disc` obscures the digits on screen without touching `type`, so the\n * heuristic that triggered the prompt (keyed off `type=\"password\"` fields in the form) never fires —\n * settled by the 2026-08-24 unblock ruling through measurement in real Chrome, not documentation.\n * Applied as an **element inline style**, never a stylesheet the package ships (forbidden by\n * ADR-0007's Consequences, `:104`) and never a class a store authors (defeatable by any compound\n * swatch) — an inline declaration is the one CSS route that is both within the architecture rule and\n * outside the store's reach, and it outranks every class-based rule at normal importance.\n *\n * This closes the password-manager capture surface structurally — it does not mean the code never\n * leaves the browser by any path. `CardEntry`'s CVV keeps `autoComplete=\"cc-csc\"` (FR-5, unchanged by\n * this task): the exact token Chrome's own Autofill uses to classify the field as\n * `CREDIT_CARD_VERIFICATION_CODE`, and Chrome ships CVC storage (`AutofillEnableCvcStorageAndFilling`)\n * that retains the CVC beside a saved server card and syncs it to the signed-in Google account. This\n * mechanism does not close that path and is not trying to — it is the separate *card* vault the field\n * honestly declares itself to via `autoComplete`, not the credential vault this change removes (spec\n * § Verification, G1(d)).\n *\n * `WebkitTextSecurity` is asserted `as CSSProperties` because csstype 3.2.3 declares no such key —\n * mirrors the existing assertion in `variant-selector.tsx`. The property is standardized nowhere;\n * supported in Chromium and WebKit (and Firefox 114+, per T70's spec). An engine without it renders\n * exactly what ships today — not a regression.\n *\n * Defined once at module scope so the object is referentially stable and React's style diffing never\n * has work to do on re-render.\n */\nexport const SECURITY_CODE_MASK_STYLE: CSSProperties = Object.freeze({ WebkitTextSecurity: 'disc' }) as CSSProperties;\n\n/**\n * Whether the security code is fully typed — the moment `SECURITY_CODE_MASK_STYLE` above starts\n * applying (specs/mask-the-cvv-only-once-it.md, T173). Until then the field renders its digits in\n * the clear, so a shopper can read back what they just typed and catch a typo; from then on it\n * renders exactly as it did when the mask was unconditional. The mechanism is untouched; only its\n * timing moves. Never on blur, never after a delay: the mask engages on the keystroke that completes\n * the code.\n *\n * `expectedLength` is passed in because the two fields resolve it from different places and neither\n * belongs in this module: `CardEntry` takes the detected network's `cvvMask` (three digits for most\n * networks, four for Amex), while `SavedCardCvvField` has no per-network length at all and uses its\n * own three-or-four-digit floor. Resolving it here would mean knowing about payment-method validators\n * and saved-card rows, and would still leave the comparison itself free to drift between the two.\n *\n * Both callers resolve a *floor*, and a ceiling would be a defect rather than a variation: whatever\n * length arrives here is the length at which digits stop being legible, so the widest of several\n * possible lengths leaves a code that is already complete for a shorter one readable for the rest of\n * the flow.\n *\n * Derived from the value on every render, with no state and no timer. That is what makes the render\n * which first holds a complete code already the masked one — so a paste delivering every digit in one\n * event opens no legible frame — lets a cleared field unmask with nothing to reset, and leaves a code\n * the shopper backspaces into legible again while they correct it.\n */\nexport function isSecurityCodeComplete(value: string, expectedLength: number): boolean {\n  // The length guard is not redundant with `>=`: a store-configured empty `cvvMask` resolves to a\n  // zero expected length, which on its own would read an untouched field as fully typed.\n  return value.length > 0 && value.length >= expectedLength;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,MAAa,2BAA0C,OAAO,OAAO,EAAE,oBAAoB,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;AA0BnG,SAAgB,uBAAuB,OAAe,gBAAiC;CAGrF,OAAO,MAAM,SAAS,KAAK,MAAM,UAAU;AAC7C"}
+{"version":3,"file":"security-code-mask.js","names":[],"sources":["../../../src/sdk/payment/security-code-mask.ts"],"sourcesContent":["import type { CSSProperties } from 'react';\n\n/**\n * The security-code masking mechanism (specs/choose-a-security-code-masking-mechanism.md, T101 of\n * the Credit Card epic; docs/features/credit-card/rfc.md § D13). One shared constant for the two\n * inputs that hold a security code — `CardEntry`'s `cvv` field and `SavedCardCvvField`'s CVV\n * re-entry field — so the two call sites cannot drift on the mechanism.\n *\n * Why this and not `type=\"password\"`: T70 shipped `type=\"password\"` on both fields and it made real\n * Chrome offer a \"Save password?\" prompt on the new-card form — pairing the expiration date as a\n * fake *Username* and the security code as *Password*, and offering to store it in Google Password\n * Manager, synced to the signed-in account. PCI-DSS forbids retaining the security code past\n * authorization, and a cloud-synced credential vault is a strictly worse posture than the field's\n * pre-T70 baseline. `type=\"password\"` was reverted; both fields ship `type=\"text\"`.\n *\n * `-webkit-text-security: disc` obscures the digits on screen without touching `type`, so the\n * heuristic that triggered the prompt (keyed off `type=\"password\"` fields in the form) never fires —\n * settled by the 2026-08-24 unblock ruling through measurement in real Chrome, not documentation.\n * Applied as an **element inline style**, never a stylesheet the package ships (forbidden by\n * ADR-0007's Consequences, `:104`) and never a class a store authors (defeatable by any compound\n * swatch) — an inline declaration is the one CSS route that is both within the architecture rule and\n * outside the store's reach, and it outranks every class-based rule at normal importance.\n *\n * This closes the password-manager capture surface structurally — it does not mean the code never\n * leaves the browser by any path. `CardEntry`'s CVV keeps `autoComplete=\"cc-csc\"` (FR-5, unchanged by\n * this task): the exact token Chrome's own Autofill uses to classify the field as\n * `CREDIT_CARD_VERIFICATION_CODE`, and Chrome ships CVC storage (`AutofillEnableCvcStorageAndFilling`)\n * that retains the CVC beside a saved server card and syncs it to the signed-in Google account. This\n * mechanism does not close that path and is not trying to — it is the separate *card* vault the field\n * honestly declares itself to via `autoComplete`, not the credential vault this change removes (spec\n * § Verification, G1(d)).\n *\n * `WebkitTextSecurity` is asserted `as CSSProperties` because csstype 3.2.3 declares no such key —\n * mirrors the existing assertion in `variant-selector.tsx`. The property is standardized nowhere;\n * supported in Chromium and WebKit (and Firefox 114+, per T70's spec). An engine without it renders\n * exactly what ships today — not a regression.\n *\n * Defined once at module scope so the object is referentially stable and React's style diffing never\n * has work to do on re-render.\n */\nexport const SECURITY_CODE_MASK_STYLE: CSSProperties = Object.freeze({ WebkitTextSecurity: 'disc' }) as CSSProperties;\n\n/**\n * Whether the security code is obscured: while it is non-empty and its input does not have focus\n * (specs/stop-sending-a-stale-non-displayable-cardholder.md, T34, reversing the T173 timing that\n * obscured a code the instant its last digit arrived). A shopper who is still in the field can read\n * back what they typed and catch a typo; the moment focus leaves, nothing is left legible. The\n * mechanism is untouched; only its timing moves.\n *\n * `focused` is passed in already folded with whatever else disables the input: a browser fires no\n * `blur` when a focused element becomes disabled, so each caller counts a disabled input as\n * unfocused. This function knows nothing about `disabled`.\n *\n * Derived from the value and the focus flag on every render, never from an effect or a timer. That\n * is what makes the render which first holds an unfocused code already the masked one — so a paste or\n * a browser autofill delivering every digit in one event, and the blur itself, open no legible frame.\n * The length of the code plays no part: the mask no longer needs a per-network or per-field length,\n * and a partial code is hidden on blur like a complete one.\n */\nexport function isSecurityCodeMasked(value: string, focused: boolean): boolean {\n  return value.length > 0 && !focused;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,MAAa,2BAA0C,OAAO,OAAO,EAAE,oBAAoB,OAAO,CAAC;;;;;;;;;;;;;;;;;;AAmBnG,SAAgB,qBAAqB,OAAe,SAA2B;CAC7E,OAAO,MAAM,SAAS,KAAK,CAAC;AAC9B"}

package/dist/sdk/payment/submission-registry.js

@@ -1,5 +1,5 @@
 "use client";
-import { createContext, useContext, useEffect, useMemo, useRef } from "react";
+import { createContext, useContext, useLayoutEffect, useMemo, useRef } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/sdk/payment/submission-registry.tsx
 const SUBMISSION_CONTEXT_UNSET = Symbol("PaymentSubmissionContextUnset");
@@ -45,10 +45,14 @@ function usePaymentSubmission() {
 * `path`, and unregisters on unmount or on any argument
 * changing, so the map always holds the latest closures over the holder's card fields — a stale one
 * would pay with the previous keystroke's CVV.
+*
+* Registration runs in the layout phase: before paint and before any passive effect of the commit.
+* A render that no discrete event caused (an async mutation response, a timer) can be clicked on
+* before its passive effects flush, and the click would then resolve the previous commit's closure.
 */
 function useRegisterPaymentSubmission(path, submit, preflight, explainMissingMethod) {
 	const { register } = usePaymentSubmission();
-	useEffect(() => register(path, submit, preflight, explainMissingMethod), [
+	useLayoutEffect(() => register(path, submit, preflight, explainMissingMethod), [
 		register,
 		path,
 		submit,

package/dist/sdk/payment/submission-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"submission-registry.js","names":[],"sources":["../../../src/sdk/payment/submission-registry.tsx"],"sourcesContent":["'use client';\n\nimport { createContext, type ReactNode, useContext, useEffect, useMemo, useRef } from 'react';\nimport type { PaymentGatewayResult, PaymentGatewayTransaction } from './gateway.js';\nimport type { PaymentUserError } from './operations.js';\n\n/**\n * The card-data submission channel (specs/use-place-order.md, Decision 1; specs/epics/credit-card.md\n * § \"The card-data submission channel\"). **The holder submits; the orchestrator never holds.**\n *\n * T7 (new card) and T12 (saved card) each register a submit-time continuation here. Each closes over\n * its own card fields, builds the gateway card object inside that closure, calls\n * `$actions.payment.sendPayments` itself, and returns only the gateway leg's result: its `userErrors` and\n * whether a request reached the gateway (T112). T13's\n * `usePlaceOrder` resolves one by `path` and invokes it between start-transaction and\n * gateway-callback, so no card-shaped field appears anywhere in this channel's type signature.\n *\n * It is a *second*, narrow context beside T5's `payment` context rather than a field on it, because\n * the two have different shapes and different readers: `draft` is render state every leaf reads, this\n * is an imperative registry exactly two components write and one hook reads. Registration is a\n * ref-held `Map`, not state — T7 re-registers a fresh closure on every keystroke, and making that a\n * render would re-render the whole payment section per character.\n *\n * Values that are **not** sensitive travel on T5's `draft`, never here: the save-card flag and label\n * (T10), the cardholder document (T8), and the billing-address-differs flag (T11). The holder folds\n * them into the card object inside its own closure.\n *\n * This module lives in the SDK rather than beside T5's roots so the layering stays `matter → sdk`:\n * `usePlaceOrder` is an SDK hook and cannot import from `matter/`. \"Provided by T5's root\" means the\n * root renders `PaymentSubmissionProvider`, which it does — both of them, for the same ADR-0009\n * reason the `payment` context has two providers.\n */\n\n/** Which entry path a submission serves. The canonical key type; T5's `PaymentPath` aliases it. */\nexport type PaymentSubmissionPath = 'new-card' | 'saved-card';\n\n/**\n * What a continuation resolves (T112): the gateway leg's `userErrors` (empty on success) and\n * `reachedGateway`, which is `false` only when the holder can show it refused before issuing any\n * request. `usePlaceOrder` frees the attempt for exactly that case and locks it for every other one,\n * including a missing or non-boolean flag. Defined by the producer, `gateway.ts`; re-exported here so the\n * hook imports it from this module and keeps `./gateway.js` to the transaction type alone.\n */\nexport type PaymentSubmissionResult = PaymentGatewayResult;\n\n/**\n * A holder's submit-time continuation — the whole channel. It takes the non-sensitive transaction\n * descriptor and resolves a `PaymentSubmissionResult`. It must not log, serialize, or return the card.\n */\nexport type PaymentSubmission = (transaction: PaymentGatewayTransaction) => Promise<PaymentSubmissionResult>;\n\n/**\n * A holder's pre-flight verdict on its own draft, resolved before any transaction opens (T27,\n * specs/place-order-preflight-card-validation.md). Returns the refusals that would make this\n * submission pointless, or an empty array to proceed. Synchronous by contract (Decision 6): a holder\n * validates what it already holds and performs no I/O.\n *\n * Card-free by the same rule the submission itself follows — it returns `PaymentUserError`s and never\n * the fields it inspected. It may have side effects inside its own component (rendering field errors,\n * moving focus); that is the half a value-shaped gate cannot carry.\n */\nexport type PaymentPreflightCheck = () => readonly PaymentUserError[];\n\n/**\n * A holder's explanation of why no payment method is selected (T47, specs/distinguish-a-pan-that-\n * matches-no-configured.md, Decision 2/4/5). Consulted only by `usePlaceOrder`'s method step, and only\n * when nothing is selected, so it can never reorder the checks. Returns the refusal to show in place of\n * the generic missing-method one, or `null` when the holder has nothing more specific to say.\n *\n * Synchronous and side-effect-free, unlike the pre-flight: it returns a value and touches nothing in its\n * own component. Fixed copy and a fixed code only — it must never echo anything the shopper typed.\n */\nexport type PaymentMissingMethodExplainer = () => PaymentUserError | null;\n\n/** One path's registration. `preflight` and `explainMissingMethod` are `null` when its holder registered none (FR-6). */\ntype PaymentSubmissionEntry = Readonly<{\n  submit: PaymentSubmission;\n  preflight: PaymentPreflightCheck | null;\n  explainMissingMethod: PaymentMissingMethodExplainer | null;\n}>;\n\nexport type PaymentSubmissionChannel = Readonly<{\n  /**\n   * The entry path the shopper is on — T5's `draft.path`, mirrored here so the place-order sequence\n   * resolves it without reading the matter context. One-way and derived: the root passes it through\n   * on every render.\n   */\n  path: PaymentSubmissionPath | null;\n  /**\n   * Registers (or replaces) the continuation, and optionally its pre-flight check and its missing-method\n   * explainer, for a path. Returns its unregister function.\n   */\n  register: (\n    path: PaymentSubmissionPath,\n    submit: PaymentSubmission,\n    preflight?: PaymentPreflightCheck,\n    explainMissingMethod?: PaymentMissingMethodExplainer,\n  ) => () => void;\n  /** Unchanged: the continuation registered for a path, or `null` when its holder is not composed or unmounted. */\n  resolve: (path: PaymentSubmissionPath) => PaymentSubmission | null;\n  /** The pre-flight check registered for a path, or `null` when its holder registered none. */\n  resolvePreflight: (path: PaymentSubmissionPath) => PaymentPreflightCheck | null;\n  /** The missing-method explainer registered for a path, or `null` when its holder registered none (T47). */\n  resolveMissingMethodExplainer: (path: PaymentSubmissionPath) => PaymentMissingMethodExplainer | null;\n}>;\n\nconst SUBMISSION_CONTEXT_UNSET = Symbol('PaymentSubmissionContextUnset');\n\nconst PaymentSubmissionContext = createContext<PaymentSubmissionChannel | typeof SUBMISSION_CONTEXT_UNSET>(\n  SUBMISSION_CONTEXT_UNSET,\n);\n\nexport type PaymentSubmissionProviderProps = Readonly<{\n  /** T5's `draft.path`. */\n  path: PaymentSubmissionPath | null;\n  children: ReactNode;\n}>;\n\n/** Rendered by `PaymentSectionRoot` and `PaymentSectionController` around the section composition. */\nexport function PaymentSubmissionProvider({ path, children }: PaymentSubmissionProviderProps) {\n  const submissions = useRef(new Map<PaymentSubmissionPath, PaymentSubmissionEntry>());\n\n  const channel = useMemo<PaymentSubmissionChannel>(\n    () => ({\n      path,\n      register: (registeredPath, submit, preflight, explainMissingMethod) => {\n        submissions.current.set(registeredPath, {\n          submit,\n          preflight: preflight ?? null,\n          explainMissingMethod: explainMissingMethod ?? null,\n        });\n        return () => {\n          // Delete only if this registration is still the one on file: a Map holds one entry per\n          // path, so an unmounting holder whose registration was already superseded by a still-mounted\n          // sibling under the same path must not wipe that sibling's live continuation (or its check).\n          if (submissions.current.get(registeredPath)?.submit === submit) {\n            submissions.current.delete(registeredPath);\n          }\n        };\n      },\n      resolve: (registeredPath) => submissions.current.get(registeredPath)?.submit ?? null,\n      resolvePreflight: (registeredPath) => submissions.current.get(registeredPath)?.preflight ?? null,\n      resolveMissingMethodExplainer: (registeredPath) =>\n        submissions.current.get(registeredPath)?.explainMissingMethod ?? null,\n    }),\n    [path],\n  );\n\n  return <PaymentSubmissionContext value={channel}>{children}</PaymentSubmissionContext>;\n}\n\n/**\n * Read the submission channel from the nearest `PaymentSectionRoot` or `PaymentSectionController`.\n * Throws outside either subtree, mirroring `usePayment()`: a misplaced holder or CTA is a composition\n * bug the author should see immediately. Distinct from the two *runtime* states — no path chosen, no\n * continuation registered — which `usePlaceOrder` resolves as a userError.\n */\nexport function usePaymentSubmission(): PaymentSubmissionChannel {\n  const channel = useContext(PaymentSubmissionContext);\n  if (channel === SUBMISSION_CONTEXT_UNSET) {\n    throw new Error(\n      'usePaymentSubmission() must be used inside a <PaymentSectionRoot> or <PaymentSectionController> subtree.',\n    );\n  }\n  return channel;\n}\n\n/**\n * The holder-facing signature (T7, T12; `preflight` added by T27, `explainMissingMethod` by T47).\n * Registers `submit` — and, optionally, its pre-flight check and its missing-method explainer — for\n * `path`, and unregisters on unmount or on any argument\n * changing, so the map always holds the latest closures over the holder's card fields — a stale one\n * would pay with the previous keystroke's CVV.\n */\nexport function useRegisterPaymentSubmission(\n  path: PaymentSubmissionPath,\n  submit: PaymentSubmission,\n  preflight?: PaymentPreflightCheck,\n  explainMissingMethod?: PaymentMissingMethodExplainer,\n): void {\n  const { register } = usePaymentSubmission();\n\n  useEffect(\n    () => register(path, submit, preflight, explainMissingMethod),\n    [register, path, submit, preflight, explainMissingMethod],\n  );\n}\n"],"mappings":";;;;AA0GA,MAAM,2BAA2B,OAAO,+BAA+B;AAEvE,MAAM,2BAA2B,cAC/B,wBACF;;AASA,SAAgB,0BAA0B,EAAE,MAAM,YAA4C;CAC5F,MAAM,cAAc,uBAAO,IAAI,IAAmD,CAAC;CAEnF,MAAM,UAAU,eACP;EACL;EACA,WAAW,gBAAgB,QAAQ,WAAW,yBAAyB;GACrE,YAAY,QAAQ,IAAI,gBAAgB;IACtC;IACA,WAAW,aAAa;IACxB,sBAAsB,wBAAwB;GAChD,CAAC;GACD,aAAa;IAIX,IAAI,YAAY,QAAQ,IAAI,cAAc,CAAC,EAAE,WAAW,QACtD,YAAY,QAAQ,OAAO,cAAc;GAE7C;EACF;EACA,UAAU,mBAAmB,YAAY,QAAQ,IAAI,cAAc,CAAC,EAAE,UAAU;EAChF,mBAAmB,mBAAmB,YAAY,QAAQ,IAAI,cAAc,CAAC,EAAE,aAAa;EAC5F,gCAAgC,mBAC9B,YAAY,QAAQ,IAAI,cAAc,CAAC,EAAE,wBAAwB;CACrE,IACA,CAAC,IAAI,CACP;CAEA,OAAO,oBAAC,0BAAD;EAA0B,OAAO;EAAU;CAAmC,CAAA;AACvF;;;;;;;AAQA,SAAgB,uBAAiD;CAC/D,MAAM,UAAU,WAAW,wBAAwB;CACnD,IAAI,YAAY,0BACd,MAAM,IAAI,MACR,0GACF;CAEF,OAAO;AACT;;;;;;;;AASA,SAAgB,6BACd,MACA,QACA,WACA,sBACM;CACN,MAAM,EAAE,aAAa,qBAAqB;CAE1C,gBACQ,SAAS,MAAM,QAAQ,WAAW,oBAAoB,GAC5D;EAAC;EAAU;EAAM;EAAQ;EAAW;CAAoB,CAC1D;AACF"}
+{"version":3,"file":"submission-registry.js","names":[],"sources":["../../../src/sdk/payment/submission-registry.tsx"],"sourcesContent":["'use client';\n\nimport { createContext, type ReactNode, useContext, useLayoutEffect, useMemo, useRef } from 'react';\nimport type { PaymentGatewayResult, PaymentGatewayTransaction } from './gateway.js';\nimport type { PaymentUserError } from './operations.js';\n\n/**\n * The card-data submission channel (specs/use-place-order.md, Decision 1; specs/epics/credit-card.md\n * § \"The card-data submission channel\"). **The holder submits; the orchestrator never holds.**\n *\n * T7 (new card) and T12 (saved card) each register a submit-time continuation here. Each closes over\n * its own card fields, builds the gateway card object inside that closure, calls\n * `$actions.payment.sendPayments` itself, and returns only the gateway leg's result: its `userErrors` and\n * whether a request reached the gateway (T112). T13's\n * `usePlaceOrder` resolves one by `path` and invokes it between start-transaction and\n * gateway-callback, so no card-shaped field appears anywhere in this channel's type signature.\n *\n * It is a *second*, narrow context beside T5's `payment` context rather than a field on it, because\n * the two have different shapes and different readers: `draft` is render state every leaf reads, this\n * is an imperative registry exactly two components write and one hook reads. Registration is a\n * ref-held `Map`, not state — T7 re-registers a fresh closure on every keystroke, and making that a\n * render would re-render the whole payment section per character.\n *\n * Values that are **not** sensitive travel on T5's `draft`, never here: the save-card flag and label\n * (T10), the cardholder document (T8), and the billing-address-differs flag (T11). The holder folds\n * them into the card object inside its own closure.\n *\n * This module lives in the SDK rather than beside T5's roots so the layering stays `matter → sdk`:\n * `usePlaceOrder` is an SDK hook and cannot import from `matter/`. \"Provided by T5's root\" means the\n * root renders `PaymentSubmissionProvider`, which it does — both of them, for the same ADR-0009\n * reason the `payment` context has two providers.\n */\n\n/** Which entry path a submission serves. The canonical key type; T5's `PaymentPath` aliases it. */\nexport type PaymentSubmissionPath = 'new-card' | 'saved-card';\n\n/**\n * What a continuation resolves (T112): the gateway leg's `userErrors` (empty on success) and\n * `reachedGateway`, which is `false` only when the holder can show it refused before issuing any\n * request. `usePlaceOrder` frees the attempt for exactly that case and locks it for every other one,\n * including a missing or non-boolean flag. Defined by the producer, `gateway.ts`; re-exported here so the\n * hook imports it from this module and keeps `./gateway.js` to the transaction type alone.\n */\nexport type PaymentSubmissionResult = PaymentGatewayResult &\n  Readonly<{\n    /**\n     * `true` only from a holder whose order is placed by Start Transaction alone, so the gateway leg and its\n     * callback never run (T39). Read as `=== true`, and only with an empty `userErrors`: anything else keeps\n     * the callback leg.\n     */\n    completesWithoutGateway?: boolean;\n  }>;\n\n/**\n * A holder's submit-time continuation — the whole channel. It takes the non-sensitive transaction\n * descriptor and resolves a `PaymentSubmissionResult`. It must not log, serialize, or return the card.\n */\nexport type PaymentSubmission = (transaction: PaymentGatewayTransaction) => Promise<PaymentSubmissionResult>;\n\n/**\n * A holder's pre-flight verdict on its own draft, resolved before any transaction opens (T27,\n * specs/place-order-preflight-card-validation.md). Returns the refusals that would make this\n * submission pointless, or an empty array to proceed. Synchronous by contract (Decision 6): a holder\n * validates what it already holds and performs no I/O.\n *\n * Card-free by the same rule the submission itself follows — it returns `PaymentUserError`s and never\n * the fields it inspected. It may have side effects inside its own component (rendering field errors,\n * moving focus); that is the half a value-shaped gate cannot carry.\n */\nexport type PaymentPreflightCheck = () => readonly PaymentUserError[];\n\n/**\n * A holder's explanation of why no payment method is selected (T47, specs/distinguish-a-pan-that-\n * matches-no-configured.md, Decision 2/4/5). Consulted only by `usePlaceOrder`'s method step, and only\n * when nothing is selected, so it can never reorder the checks. Returns the refusal to show in place of\n * the generic missing-method one, or `null` when the holder has nothing more specific to say.\n *\n * Synchronous and side-effect-free, unlike the pre-flight: it returns a value and touches nothing in its\n * own component. Fixed copy and a fixed code only — it must never echo anything the shopper typed.\n */\nexport type PaymentMissingMethodExplainer = () => PaymentUserError | null;\n\n/** One path's registration. `preflight` and `explainMissingMethod` are `null` when its holder registered none (FR-6). */\ntype PaymentSubmissionEntry = Readonly<{\n  submit: PaymentSubmission;\n  preflight: PaymentPreflightCheck | null;\n  explainMissingMethod: PaymentMissingMethodExplainer | null;\n}>;\n\nexport type PaymentSubmissionChannel = Readonly<{\n  /**\n   * The entry path the shopper is on — T5's `draft.path`, mirrored here so the place-order sequence\n   * resolves it without reading the matter context. One-way and derived: the root passes it through\n   * on every render.\n   */\n  path: PaymentSubmissionPath | null;\n  /**\n   * Registers (or replaces) the continuation, and optionally its pre-flight check and its missing-method\n   * explainer, for a path. Returns its unregister function.\n   */\n  register: (\n    path: PaymentSubmissionPath,\n    submit: PaymentSubmission,\n    preflight?: PaymentPreflightCheck,\n    explainMissingMethod?: PaymentMissingMethodExplainer,\n  ) => () => void;\n  /** Unchanged: the continuation registered for a path, or `null` when its holder is not composed or unmounted. */\n  resolve: (path: PaymentSubmissionPath) => PaymentSubmission | null;\n  /** The pre-flight check registered for a path, or `null` when its holder registered none. */\n  resolvePreflight: (path: PaymentSubmissionPath) => PaymentPreflightCheck | null;\n  /** The missing-method explainer registered for a path, or `null` when its holder registered none (T47). */\n  resolveMissingMethodExplainer: (path: PaymentSubmissionPath) => PaymentMissingMethodExplainer | null;\n}>;\n\nconst SUBMISSION_CONTEXT_UNSET = Symbol('PaymentSubmissionContextUnset');\n\nconst PaymentSubmissionContext = createContext<PaymentSubmissionChannel | typeof SUBMISSION_CONTEXT_UNSET>(\n  SUBMISSION_CONTEXT_UNSET,\n);\n\nexport type PaymentSubmissionProviderProps = Readonly<{\n  /** T5's `draft.path`. */\n  path: PaymentSubmissionPath | null;\n  children: ReactNode;\n}>;\n\n/** Rendered by `PaymentSectionRoot` and `PaymentSectionController` around the section composition. */\nexport function PaymentSubmissionProvider({ path, children }: PaymentSubmissionProviderProps) {\n  const submissions = useRef(new Map<PaymentSubmissionPath, PaymentSubmissionEntry>());\n\n  const channel = useMemo<PaymentSubmissionChannel>(\n    () => ({\n      path,\n      register: (registeredPath, submit, preflight, explainMissingMethod) => {\n        submissions.current.set(registeredPath, {\n          submit,\n          preflight: preflight ?? null,\n          explainMissingMethod: explainMissingMethod ?? null,\n        });\n        return () => {\n          // Delete only if this registration is still the one on file: a Map holds one entry per\n          // path, so an unmounting holder whose registration was already superseded by a still-mounted\n          // sibling under the same path must not wipe that sibling's live continuation (or its check).\n          if (submissions.current.get(registeredPath)?.submit === submit) {\n            submissions.current.delete(registeredPath);\n          }\n        };\n      },\n      resolve: (registeredPath) => submissions.current.get(registeredPath)?.submit ?? null,\n      resolvePreflight: (registeredPath) => submissions.current.get(registeredPath)?.preflight ?? null,\n      resolveMissingMethodExplainer: (registeredPath) =>\n        submissions.current.get(registeredPath)?.explainMissingMethod ?? null,\n    }),\n    [path],\n  );\n\n  return <PaymentSubmissionContext value={channel}>{children}</PaymentSubmissionContext>;\n}\n\n/**\n * Read the submission channel from the nearest `PaymentSectionRoot` or `PaymentSectionController`.\n * Throws outside either subtree, mirroring `usePayment()`: a misplaced holder or CTA is a composition\n * bug the author should see immediately. Distinct from the two *runtime* states — no path chosen, no\n * continuation registered — which `usePlaceOrder` resolves as a userError.\n */\nexport function usePaymentSubmission(): PaymentSubmissionChannel {\n  const channel = useContext(PaymentSubmissionContext);\n  if (channel === SUBMISSION_CONTEXT_UNSET) {\n    throw new Error(\n      'usePaymentSubmission() must be used inside a <PaymentSectionRoot> or <PaymentSectionController> subtree.',\n    );\n  }\n  return channel;\n}\n\n/**\n * The holder-facing signature (T7, T12; `preflight` added by T27, `explainMissingMethod` by T47).\n * Registers `submit` — and, optionally, its pre-flight check and its missing-method explainer — for\n * `path`, and unregisters on unmount or on any argument\n * changing, so the map always holds the latest closures over the holder's card fields — a stale one\n * would pay with the previous keystroke's CVV.\n *\n * Registration runs in the layout phase: before paint and before any passive effect of the commit.\n * A render that no discrete event caused (an async mutation response, a timer) can be clicked on\n * before its passive effects flush, and the click would then resolve the previous commit's closure.\n */\nexport function useRegisterPaymentSubmission(\n  path: PaymentSubmissionPath,\n  submit: PaymentSubmission,\n  preflight?: PaymentPreflightCheck,\n  explainMissingMethod?: PaymentMissingMethodExplainer,\n): void {\n  const { register } = usePaymentSubmission();\n\n  useLayoutEffect(\n    () => register(path, submit, preflight, explainMissingMethod),\n    [register, path, submit, preflight, explainMissingMethod],\n  );\n}\n"],"mappings":";;;;AAkHA,MAAM,2BAA2B,OAAO,+BAA+B;AAEvE,MAAM,2BAA2B,cAC/B,wBACF;;AASA,SAAgB,0BAA0B,EAAE,MAAM,YAA4C;CAC5F,MAAM,cAAc,uBAAO,IAAI,IAAmD,CAAC;CAEnF,MAAM,UAAU,eACP;EACL;EACA,WAAW,gBAAgB,QAAQ,WAAW,yBAAyB;GACrE,YAAY,QAAQ,IAAI,gBAAgB;IACtC;IACA,WAAW,aAAa;IACxB,sBAAsB,wBAAwB;GAChD,CAAC;GACD,aAAa;IAIX,IAAI,YAAY,QAAQ,IAAI,cAAc,CAAC,EAAE,WAAW,QACtD,YAAY,QAAQ,OAAO,cAAc;GAE7C;EACF;EACA,UAAU,mBAAmB,YAAY,QAAQ,IAAI,cAAc,CAAC,EAAE,UAAU;EAChF,mBAAmB,mBAAmB,YAAY,QAAQ,IAAI,cAAc,CAAC,EAAE,aAAa;EAC5F,gCAAgC,mBAC9B,YAAY,QAAQ,IAAI,cAAc,CAAC,EAAE,wBAAwB;CACrE,IACA,CAAC,IAAI,CACP;CAEA,OAAO,oBAAC,0BAAD;EAA0B,OAAO;EAAU;CAAmC,CAAA;AACvF;;;;;;;AAQA,SAAgB,uBAAiD;CAC/D,MAAM,UAAU,WAAW,wBAAwB;CACnD,IAAI,YAAY,0BACd,MAAM,IAAI,MACR,0GACF;CAEF,OAAO;AACT;;;;;;;;;;;;AAaA,SAAgB,6BACd,MACA,QACA,WACA,sBACM;CACN,MAAM,EAAE,aAAa,qBAAqB;CAE1C,sBACQ,SAAS,MAAM,QAAQ,WAAW,oBAAoB,GAC5D;EAAC;EAAU;EAAM;EAAQ;EAAW;CAAoB,CAC1D;AACF"}

package/dist/sdk/payment/use-payment-actions.d.ts

@@ -38,6 +38,11 @@ export type PaymentStartTransactionResult = Readonly<{
   /** Gateway origin. Nullable, and never interpolated into a URL before `isTrustedGatewayOrigin`. */
   gatewayUrl: string | null;
   orderGroup: string | null;
+  /**
+   * The Relay Node ID of the order, for `Query.order(id:)`. Null when the transaction carried no order
+   * group. Optional so a provider written before this field existed still satisfies the type.
+   */
+  orderNodeId?: string | null;
   userProfileId: string | null;
   /** Display decimal. The gateway body's unit is `valueInCents`. */
   value: PaymentMoney | null;
@@ -47,12 +52,16 @@ export type PaymentStartTransactionResult = Readonly<{
 }>;
 export type PaymentGatewayCallbackResult = Readonly<{
   orderId: string | null;
+  /** The Relay Node ID of the finalized order, for `Query.order(id:)`. Null unless the callback succeeded. */
+  orderNodeId?: string | null;
+  /** The bank's challenge page. Set only when the server answered a challenge with a usable URL. */
+  redirectUrl?: string | null;
   userErrors: readonly PaymentUserError[];
 }>;
 export type PaymentActions = Readonly<{
   /** Select a payment method, optionally identifying a new card's BIN or a saved card's account. */
   setMethod: (input: PaymentMethodSelectInput) => Promise<readonly PaymentUserError[]>;
-  /** Select an installment count for the current method. The response carries the recomputed cart total. */
+  /** Select an installment count for the current method. The response's `cart.total` is the greater of the order form's value and the selected payment's value. */
   setInstallments: (count: number) => Promise<readonly PaymentUserError[]>;
   /** Persist the billing address, or fall back to the delivery address (`sameAsDelivery: true`). */
   setBillingAddress: (input: PaymentBillingAddressUpdateInput) => Promise<readonly PaymentUserError[]>;
@@ -66,8 +75,14 @@ export type PaymentActions = Readonly<{
   saveCard: (enabled: boolean) => Promise<readonly PaymentUserError[]>;
   /** Open a VTEX transaction from the persisted selection. Resolves the payload the gateway call needs. */
   startTransaction: () => Promise<PaymentStartTransactionResult>;
-  /** Finalize the transaction after the gateway accepted the card. */
-  gatewayCallback: (orderGroup: string) => Promise<PaymentGatewayCallbackResult>;
+  /**
+   * Finalize the transaction after the gateway accepted the card. `acceptChallenges: true` is sent only by
+   * the page the bank returns the shopper to, and only then; omitted, the server asks for a challenge
+   * instead of finishing the order.
+   */
+  gatewayCallback: (orderGroup: string, options?: Readonly<{
+    acceptChallenges?: boolean;
+  }>) => Promise<PaymentGatewayCallbackResult>;
   /**
    * Façade: post the card straight to the payment gateway. Issues no GraphQL operation and writes
    * nothing to the cache. Never rejects: resolves `{ reachedGateway, userErrors }`, with one `GATEWAY_ERROR`

package/dist/sdk/payment/use-payment-actions.js

@@ -4,10 +4,16 @@ import "../../core/dist/index.js";
 import { loggableErrorName } from "../../utils/loggable-error-name.js";
 import { PAYMENT_BILLING_ADDRESS_UPDATE, PAYMENT_GATEWAY_CALLBACK, PAYMENT_INSTALLMENT_SELECT, PAYMENT_METHOD_SELECT, PAYMENT_NETWORK_ERROR_CODE, PAYMENT_START_TRANSACTION } from "./operations.js";
 import { CLIENT_PREFERENCES_UPDATE } from "../identity/operations.js";
+import { isAcceptedBin } from "./bin-format.js";
 import { PAYMENT_GATEWAY_USER_ERROR, postPaymentsToGateway } from "./gateway.js";
 import { useMutation } from "@apollo/client/react";
 import { useCallback, useMemo } from "react";
+import { INVALID_BIN_MESSAGE } from "@vtex/fs-domain-logic/checkout/rules";
 //#region src/sdk/payment/use-payment-actions.ts
+const INVALID_BIN_ERROR = {
+	code: "INVALID_BIN_FORMAT",
+	message: INVALID_BIN_MESSAGE
+};
 const NETWORK_ERROR = {
 	code: PAYMENT_NETWORK_ERROR_CODE,
 	message: "Unable to complete the request. Please try again."
@@ -18,6 +24,7 @@ const EMPTY_START_TRANSACTION = {
 	merchantName: null,
 	gatewayUrl: null,
 	orderGroup: null,
+	orderNodeId: null,
 	userProfileId: null,
 	value: null,
 	valueInCents: null,
@@ -37,6 +44,7 @@ function usePaymentActions() {
 	const [startTransactionMutation] = useMutation(PAYMENT_START_TRANSACTION);
 	const [gatewayCallbackMutation] = useMutation(PAYMENT_GATEWAY_CALLBACK);
 	const setMethod = useCallback(async (input) => {
+		if (!isAcceptedBin(input)) return [INVALID_BIN_ERROR];
 		try {
 			return (await methodSelectMutation({ variables: { input } })).data?.paymentMethodSelect.userErrors ?? [];
 		} catch (error) {
@@ -76,6 +84,7 @@ function usePaymentActions() {
 				merchantName: payload?.merchantName ?? null,
 				gatewayUrl: payload?.gatewayUrl ?? null,
 				orderGroup: payload?.orderGroup ?? null,
+				orderNodeId: payload?.orderNodeId ?? null,
 				userProfileId: payload?.userProfileId ?? null,
 				value: payload?.value ?? null,
 				valueInCents: payload?.valueInCents ?? null,
@@ -90,17 +99,24 @@ function usePaymentActions() {
 			};
 		}
 	}, [startTransactionMutation]);
-	const gatewayCallback = useCallback(async (orderGroup) => {
+	const gatewayCallback = useCallback(async (orderGroup, options) => {
 		try {
-			const payload = (await gatewayCallbackMutation({ variables: { input: { orderGroup } } })).data?.paymentGatewayCallback;
+			const input = options?.acceptChallenges === true ? {
+				orderGroup,
+				acceptChallenges: true
+			} : { orderGroup };
+			const payload = (await gatewayCallbackMutation({ variables: { input } })).data?.paymentGatewayCallback;
 			return {
 				orderId: payload?.orderId ?? null,
+				orderNodeId: payload?.orderNodeId ?? null,
+				...payload?.redirectUrl ? { redirectUrl: payload.redirectUrl } : {},
 				userErrors: payload?.userErrors ?? []
 			};
 		} catch (error) {
 			console.error("[payment.gatewayCallback] paymentGatewayCallback failed", loggableErrorName(error));
 			return {
 				orderId: null,
+				orderNodeId: null,
 				userErrors: [NETWORK_ERROR]
 			};
 		}
@@ -162,7 +178,7 @@ defineActions({
 			]
 		},
 		setInstallments: {
-			description: "Select an installment count for the current method (async/pessimistic). The response recomputes the cart total with interest. Resolves the payload userErrors.",
+			description: "Select an installment count for the current method (async/pessimistic). The response carries the cart, whose total is the greater of the order form value and the selected payment value, so it includes the interest of the picked tier. Resolves the payload userErrors.",
 			payload: [{
 				name: "count",
 				type: "number"
@@ -243,6 +259,10 @@ defineActions({
 			payload: [{
 				name: "orderGroup",
 				type: "string"
+			}, {
+				name: "acceptChallenges",
+				type: "boolean",
+				optional: true
 			}]
 		},
 		sendPayments: {

package/dist/sdk/payment/use-payment-actions.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-payment-actions.js","names":[],"sources":["../../../src/sdk/payment/use-payment-actions.ts"],"sourcesContent":["'use client';\n\nimport { useMutation } from '@apollo/client/react';\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo } from 'react';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport { CLIENT_PREFERENCES_UPDATE } from '../identity/operations.js';\nimport {\n  PAYMENT_GATEWAY_USER_ERROR,\n  type PaymentGatewayResult,\n  postPaymentsToGateway,\n  type SendPaymentsRequest,\n} from './gateway.js';\nimport {\n  PAYMENT_BILLING_ADDRESS_UPDATE,\n  PAYMENT_GATEWAY_CALLBACK,\n  PAYMENT_INSTALLMENT_SELECT,\n  PAYMENT_METHOD_SELECT,\n  PAYMENT_NETWORK_ERROR_CODE,\n  PAYMENT_START_TRANSACTION,\n  type PaymentBillingAddressUpdateInput,\n  type PaymentMethodSelectInput,\n  type PaymentMoney,\n  type PaymentUserError,\n} from './operations.js';\n\n/**\n * The `payment` action namespace — the sanctioned client write surface for credit-card payment\n * (specs/payment-action-namespace.md; docs/features/credit-card/rfc.md § D12;\n * docs/storefront-core/adr-0010-actions-own-the-write-side.md).\n *\n * Six mutation-backed methods run the write model T3 shipped (`checkout/schema.graphql` § 11), except\n * `saveCard`, which reuses the already-shipped `clientPreferencesUpdate` document this package owns —\n * there is no `paymentSaveCard` mutation and T3 decided there must not be one. All six are\n * async/pessimistic: the handler awaits the mutation and only the server-confirmed payload changes the\n * cache. Each is stateless (no reactive vars, no module state), resolves its payload `userErrors` (empty\n * on success), and never throws for an expected outcome; an infrastructure failure (transport or an\n * upstream GraphQLError) is caught and collapsed to one synthetic `NETWORK_ERROR` userError with no\n * per-code branching, mirroring `useShippingActions`.\n *\n * `sendPayments` is the seventh method and the odd one: a **façade** (ADR-0010's sanctioned flavor,\n * alongside `notifications`) that posts card data from the browser straight to the payment gateway,\n * touching neither our GraphQL layer nor the normalized cache. It is catalogued like any other method —\n * per D12, hiding a write route with no read-back would cost discoverability without protecting\n * anything, and the compiler wants to *see* which components reference it. What is deliberately absent\n * from the catalog is the card data itself: no `payload` entry below names a card number, CVV, expiry,\n * or holder name, so there is no schema-bindable name for the editor or the agent to map a value onto\n * (RFC D13). The card reaches the handler as a runtime argument from the card-entry component's local\n * state (T7), and `gateway.ts` — which has no Apollo import — is the only module that touches it.\n */\n\n/**\n * Everything `usePlaceOrder` (T13) needs to assemble `PaymentGatewayTransaction`, minus the five\n * fields that come from the `Payment` read model. Every field is nullable because a payload carrying\n * `userErrors` nulls all of them (T18 Decision 4), so a complete descriptor is only guaranteed once\n * `userErrors` is empty *and* the payload passes the caller's completeness check.\n */\nexport type PaymentStartTransactionResult = Readonly<{\n  transactionId: string | null;\n  merchantName: string | null;\n  /** Gateway origin. Nullable, and never interpolated into a URL before `isTrustedGatewayOrigin`. */\n  gatewayUrl: string | null;\n  orderGroup: string | null;\n  userProfileId: string | null;\n  /** Display decimal. The gateway body's unit is `valueInCents`. */\n  value: PaymentMoney | null;\n  valueInCents: number | null;\n  referenceValueInCents: number | null;\n  userErrors: readonly PaymentUserError[];\n}>;\n\nexport type PaymentGatewayCallbackResult = Readonly<{\n  orderId: string | null;\n  userErrors: readonly PaymentUserError[];\n}>;\n\nexport type PaymentActions = Readonly<{\n  /** Select a payment method, optionally identifying a new card's BIN or a saved card's account. */\n  setMethod: (input: PaymentMethodSelectInput) => Promise<readonly PaymentUserError[]>;\n  /** Select an installment count for the current method. The response carries the recomputed cart total. */\n  setInstallments: (count: number) => Promise<readonly PaymentUserError[]>;\n  /** Persist the billing address, or fall back to the delivery address (`sameAsDelivery: true`). */\n  setBillingAddress: (input: PaymentBillingAddressUpdateInput) => Promise<readonly PaymentUserError[]>;\n  /**\n   * Record the data-storage consent a saved card requires, over the existing `clientPreferencesUpdate`.\n   * This does not by itself save the card: the save flag and label travel on `sendPayments`'s card\n   * argument (RFC D5's two halves). The boolean passes through unchanged — whether unchecking should\n   * revoke a consent an unrelated opt-in component may have granted is T10's decision, and its spec must\n   * state one (Gap 4 in specs/payment-action-namespace.md).\n   */\n  saveCard: (enabled: boolean) => Promise<readonly PaymentUserError[]>;\n  /** Open a VTEX transaction from the persisted selection. Resolves the payload the gateway call needs. */\n  startTransaction: () => Promise<PaymentStartTransactionResult>;\n  /** Finalize the transaction after the gateway accepted the card. */\n  gatewayCallback: (orderGroup: string) => Promise<PaymentGatewayCallbackResult>;\n  /**\n   * Façade: post the card straight to the payment gateway. Issues no GraphQL operation and writes\n   * nothing to the cache. Never rejects: resolves `{ reachedGateway, userErrors }`, with one `GATEWAY_ERROR`\n   * userError when the gateway rejects the call or it could not be issued. `reachedGateway` is `false`\n   * only when no request was issued; every outcome it cannot classify is `true`.\n   */\n  sendPayments: (request: SendPaymentsRequest) => Promise<PaymentGatewayResult>;\n}>;\n\nconst NETWORK_ERROR: PaymentUserError = {\n  code: PAYMENT_NETWORK_ERROR_CODE,\n  message: 'Unable to complete the request. Please try again.',\n};\n\n/** Mirrors the resolver's own nulled-fields constant, so one added field is nulled in one place. */\nconst EMPTY_START_TRANSACTION = {\n  transactionId: null,\n  merchantName: null,\n  gatewayUrl: null,\n  orderGroup: null,\n  userProfileId: null,\n  value: null,\n  valueInCents: null,\n  referenceValueInCents: null,\n} as const;\n\n/**\n * The `payment` namespace hook. Registered with the first-party action registry via `paymentActions`\n * below; the compiler-emitted `PaymentActionProvider` calls it and threads the narrowed methods into\n * each consumer's `$actions.payment`. Writes persist purely through the normalized-cache merge of each\n * mutation response — no refetch, no imperative cache write.\n */\nexport function usePaymentActions(): PaymentActions {\n  const [methodSelectMutation] = useMutation(PAYMENT_METHOD_SELECT);\n  const [installmentSelectMutation] = useMutation(PAYMENT_INSTALLMENT_SELECT);\n  const [billingAddressMutation] = useMutation(PAYMENT_BILLING_ADDRESS_UPDATE);\n  const [preferencesMutation] = useMutation(CLIENT_PREFERENCES_UPDATE);\n  const [startTransactionMutation] = useMutation(PAYMENT_START_TRANSACTION);\n  const [gatewayCallbackMutation] = useMutation(PAYMENT_GATEWAY_CALLBACK);\n\n  const setMethod = useCallback<PaymentActions['setMethod']>(\n    async (input) => {\n      try {\n        const result = await methodSelectMutation({ variables: { input } });\n        return result.data?.paymentMethodSelect.userErrors ?? [];\n      } catch (error) {\n        // Log only the error name — the input carries the card's BIN, and a variable-coercion error's\n        // message echoes the offending value (`got invalid value … at \"input.bin\"`).\n        console.error('[payment.setMethod] paymentMethodSelect failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [methodSelectMutation],\n  );\n\n  const setInstallments = useCallback<PaymentActions['setInstallments']>(\n    async (count) => {\n      try {\n        const result = await installmentSelectMutation({ variables: { input: { count } } });\n        return result.data?.paymentInstallmentSelect.userErrors ?? [];\n      } catch (error) {\n        console.error('[payment.setInstallments] paymentInstallmentSelect failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [installmentSelectMutation],\n  );\n\n  const setBillingAddress = useCallback<PaymentActions['setBillingAddress']>(\n    async (input) => {\n      try {\n        const result = await billingAddressMutation({ variables: { input } });\n        return result.data?.paymentBillingAddressUpdate.userErrors ?? [];\n      } catch (error) {\n        // Log only the error name — the message can echo the submitted address (PII).\n        console.error('[payment.setBillingAddress] paymentBillingAddressUpdate failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [billingAddressMutation],\n  );\n\n  const saveCard = useCallback<PaymentActions['saveCard']>(\n    async (enabled) => {\n      try {\n        const result = await preferencesMutation({ variables: { input: { savePersonalData: enabled } } });\n        return result.data?.clientPreferencesUpdate?.userErrors ?? [];\n      } catch (error) {\n        console.error('[payment.saveCard] clientPreferencesUpdate failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [preferencesMutation],\n  );\n\n  const startTransaction = useCallback<PaymentActions['startTransaction']>(async () => {\n    try {\n      const result = await startTransactionMutation();\n      const payload = result.data?.paymentStartTransaction;\n      return {\n        transactionId: payload?.transactionId ?? null,\n        merchantName: payload?.merchantName ?? null,\n        gatewayUrl: payload?.gatewayUrl ?? null,\n        orderGroup: payload?.orderGroup ?? null,\n        userProfileId: payload?.userProfileId ?? null,\n        value: payload?.value ?? null,\n        valueInCents: payload?.valueInCents ?? null,\n        referenceValueInCents: payload?.referenceValueInCents ?? null,\n        userErrors: payload?.userErrors ?? [],\n      };\n    } catch (error) {\n      console.error('[payment.startTransaction] paymentStartTransaction failed', loggableErrorName(error));\n      return { ...EMPTY_START_TRANSACTION, userErrors: [NETWORK_ERROR] };\n    }\n  }, [startTransactionMutation]);\n\n  const gatewayCallback = useCallback<PaymentActions['gatewayCallback']>(\n    async (orderGroup) => {\n      try {\n        const result = await gatewayCallbackMutation({ variables: { input: { orderGroup } } });\n        const payload = result.data?.paymentGatewayCallback;\n        return { orderId: payload?.orderId ?? null, userErrors: payload?.userErrors ?? [] };\n      } catch (error) {\n        console.error('[payment.gatewayCallback] paymentGatewayCallback failed', loggableErrorName(error));\n        return { orderId: null, userErrors: [NETWORK_ERROR] };\n      }\n    },\n    [gatewayCallbackMutation],\n  );\n\n  const sendPayments = useCallback<PaymentActions['sendPayments']>(async (request) => {\n    try {\n      return await postPaymentsToGateway(request);\n    } catch (error) {\n      // Log the error NAME ONLY. The request carries a card number and CVV, and a thrown fetch error's\n      // message can echo the URL or the body — nothing on this path is ever serialized to a log.\n      console.error('[payment.sendPayments] gateway request failed', loggableErrorName(error));\n      // A rejected request is unclassified — it may have been processed — so it counts as reached.\n      return { reachedGateway: true, userErrors: [PAYMENT_GATEWAY_USER_ERROR] };\n    }\n  }, []);\n\n  return useMemo(\n    () => ({\n      setMethod,\n      setInstallments,\n      setBillingAddress,\n      saveCard,\n      startTransaction,\n      gatewayCallback,\n      sendPayments,\n    }),\n    [setMethod, setInstallments, setBillingAddress, saveCard, startTransaction, gatewayCallback, sendPayments],\n  );\n}\n\n/**\n * Declares the `payment` action namespace — the single source of truth for its method/payload metadata,\n * runtime provider, and `use` hook (mirrors `cartActions`, `shippingActions`). The native catalog\n * builder (`scripts/build-catalog.mjs`) statically reads this call to emit `actions.json`; at runtime\n * `PaymentActionProvider` calls `usePaymentActions` directly.\n *\n * `sendPayments`'s `payload` lists only the non-sensitive transaction descriptor's identifiers.\n * `ActionPayloadField` is the surface a schema-bindable name would come from, so the card fields'\n * absence here is the mechanical form of RFC D13: card number and CVV are never expressed as a declared\n * action payload. The `SendPaymentsRequest` type in `gateway.ts` is the source of truth for the real\n * call shape.\n */\nexport const paymentActions = defineActions({\n  namespace: 'payment',\n  description:\n    'Mutation-backed payment writes against the VTEX orderForm paymentData/invoiceData, plus a façade that posts card data directly to the payment gateway (never through our GraphQL layer or cache).',\n  provider: { name: 'PaymentActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    setMethod: {\n      description:\n        'Select a payment method, optionally identifying a new card by BIN or a saved card by account (async/pessimistic). Resolves the payload userErrors.',\n      payload: [\n        { name: 'methodId', type: 'string' },\n        { name: 'bin', type: 'string', optional: true },\n        { name: 'accountId', type: 'string', optional: true },\n      ],\n    },\n    setInstallments: {\n      description:\n        'Select an installment count for the current method (async/pessimistic). The response recomputes the cart total with interest. Resolves the payload userErrors.',\n      payload: [{ name: 'count', type: 'number' }],\n    },\n    setBillingAddress: {\n      description:\n        'Persist the billing address, or fall back to the delivery address with sameAsDelivery (async/pessimistic). Resolves the payload userErrors.',\n      payload: [\n        { name: 'sameAsDelivery', type: 'boolean' },\n        { name: 'addressType', type: 'string', optional: true },\n        { name: 'postalCode', type: 'string', optional: true },\n        { name: 'country', type: 'string', optional: true },\n        { name: 'street', type: 'string', optional: true },\n        { name: 'number', type: 'string', optional: true },\n        { name: 'complement', type: 'string', optional: true },\n        { name: 'neighborhood', type: 'string', optional: true },\n        { name: 'city', type: 'string', optional: true },\n        { name: 'state', type: 'string', optional: true },\n        { name: 'reference', type: 'string', optional: true },\n      ],\n    },\n    saveCard: {\n      description:\n        'Record the data-storage consent a saved card requires, reusing the existing clientPreferencesUpdate write. Does not itself save the card — the save flag and label travel on sendPayments.',\n      payload: [{ name: 'enabled', type: 'boolean' }],\n    },\n    startTransaction: {\n      description:\n        'Open a VTEX transaction from the persisted payment selection. Takes no arguments; resolves the transaction identifiers the gateway call needs.',\n      payload: [],\n    },\n    gatewayCallback: {\n      description: 'Finalize the transaction after the gateway accepted the card. Resolves the payload userErrors.',\n      payload: [{ name: 'orderGroup', type: 'string' }],\n    },\n    sendPayments: {\n      description:\n        'Façade: post the card directly from the browser to the payment gateway. Issues no GraphQL operation and writes nothing to the cache. Resolves { reachedGateway, userErrors }: reachedGateway is false only when no request was issued. The card number and CVV are runtime-only arguments and are deliberately absent from this payload — they are never a bindable field (RFC D13).',\n      payload: [\n        { name: 'gatewayUrl', type: 'string' },\n        { name: 'transactionId', type: 'string' },\n        { name: 'merchantName', type: 'string' },\n        { name: 'orderGroup', type: 'string' },\n        { name: 'userProfileId', type: 'string' },\n      ],\n    },\n  },\n  use: usePaymentActions,\n});\n"],"mappings":"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"}
+{"version":3,"file":"use-payment-actions.js","names":[],"sources":["../../../src/sdk/payment/use-payment-actions.ts"],"sourcesContent":["'use client';\n\nimport { useMutation } from '@apollo/client/react';\nimport { defineActions } from '@vtex/fs-core';\nimport { INVALID_BIN_MESSAGE } from '@vtex/fs-domain-logic/checkout/rules';\nimport { useCallback, useMemo } from 'react';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport { CLIENT_PREFERENCES_UPDATE } from '../identity/operations.js';\nimport { isAcceptedBin } from './bin-format.js';\nimport {\n  PAYMENT_GATEWAY_USER_ERROR,\n  type PaymentGatewayResult,\n  postPaymentsToGateway,\n  type SendPaymentsRequest,\n} from './gateway.js';\nimport {\n  PAYMENT_BILLING_ADDRESS_UPDATE,\n  PAYMENT_GATEWAY_CALLBACK,\n  PAYMENT_INSTALLMENT_SELECT,\n  PAYMENT_METHOD_SELECT,\n  PAYMENT_NETWORK_ERROR_CODE,\n  PAYMENT_START_TRANSACTION,\n  type PaymentBillingAddressUpdateInput,\n  type PaymentMethodSelectInput,\n  type PaymentMoney,\n  type PaymentUserError,\n} from './operations.js';\n\n/**\n * The `payment` action namespace — the sanctioned client write surface for credit-card payment\n * (specs/payment-action-namespace.md; docs/features/credit-card/rfc.md § D12;\n * docs/storefront-core/adr-0010-actions-own-the-write-side.md).\n *\n * Six mutation-backed methods run the write model T3 shipped (`checkout/schema.graphql` § 11), except\n * `saveCard`, which reuses the already-shipped `clientPreferencesUpdate` document this package owns —\n * there is no `paymentSaveCard` mutation and T3 decided there must not be one. All six are\n * async/pessimistic: the handler awaits the mutation and only the server-confirmed payload changes the\n * cache. Each is stateless (no reactive vars, no module state), resolves its payload `userErrors` (empty\n * on success), and never throws for an expected outcome; an infrastructure failure (transport or an\n * upstream GraphQLError) is caught and collapsed to one synthetic `NETWORK_ERROR` userError with no\n * per-code branching, mirroring `useShippingActions`.\n *\n * `sendPayments` is the seventh method and the odd one: a **façade** (ADR-0010's sanctioned flavor,\n * alongside `notifications`) that posts card data from the browser straight to the payment gateway,\n * touching neither our GraphQL layer nor the normalized cache. It is catalogued like any other method —\n * per D12, hiding a write route with no read-back would cost discoverability without protecting\n * anything, and the compiler wants to *see* which components reference it. What is deliberately absent\n * from the catalog is the card data itself: no `payload` entry below names a card number, CVV, expiry,\n * or holder name, so there is no schema-bindable name for the editor or the agent to map a value onto\n * (RFC D13). The card reaches the handler as a runtime argument from the card-entry component's local\n * state (T7), and `gateway.ts` — which has no Apollo import — is the only module that touches it.\n */\n\n/**\n * Everything `usePlaceOrder` (T13) needs to assemble `PaymentGatewayTransaction`, minus the five\n * fields that come from the `Payment` read model. Every field is nullable because a payload carrying\n * `userErrors` nulls all of them (T18 Decision 4), so a complete descriptor is only guaranteed once\n * `userErrors` is empty *and* the payload passes the caller's completeness check.\n */\nexport type PaymentStartTransactionResult = Readonly<{\n  transactionId: string | null;\n  merchantName: string | null;\n  /** Gateway origin. Nullable, and never interpolated into a URL before `isTrustedGatewayOrigin`. */\n  gatewayUrl: string | null;\n  orderGroup: string | null;\n  /**\n   * The Relay Node ID of the order, for `Query.order(id:)`. Null when the transaction carried no order\n   * group. Optional so a provider written before this field existed still satisfies the type.\n   */\n  orderNodeId?: string | null;\n  userProfileId: string | null;\n  /** Display decimal. The gateway body's unit is `valueInCents`. */\n  value: PaymentMoney | null;\n  valueInCents: number | null;\n  referenceValueInCents: number | null;\n  userErrors: readonly PaymentUserError[];\n}>;\n\nexport type PaymentGatewayCallbackResult = Readonly<{\n  orderId: string | null;\n  /** The Relay Node ID of the finalized order, for `Query.order(id:)`. Null unless the callback succeeded. */\n  orderNodeId?: string | null;\n  /** The bank's challenge page. Set only when the server answered a challenge with a usable URL. */\n  redirectUrl?: string | null;\n  userErrors: readonly PaymentUserError[];\n}>;\n\nexport type PaymentActions = Readonly<{\n  /** Select a payment method, optionally identifying a new card's BIN or a saved card's account. */\n  setMethod: (input: PaymentMethodSelectInput) => Promise<readonly PaymentUserError[]>;\n  /** Select an installment count for the current method. The response's `cart.total` is the greater of the order form's value and the selected payment's value. */\n  setInstallments: (count: number) => Promise<readonly PaymentUserError[]>;\n  /** Persist the billing address, or fall back to the delivery address (`sameAsDelivery: true`). */\n  setBillingAddress: (input: PaymentBillingAddressUpdateInput) => Promise<readonly PaymentUserError[]>;\n  /**\n   * Record the data-storage consent a saved card requires, over the existing `clientPreferencesUpdate`.\n   * This does not by itself save the card: the save flag and label travel on `sendPayments`'s card\n   * argument (RFC D5's two halves). The boolean passes through unchanged — whether unchecking should\n   * revoke a consent an unrelated opt-in component may have granted is T10's decision, and its spec must\n   * state one (Gap 4 in specs/payment-action-namespace.md).\n   */\n  saveCard: (enabled: boolean) => Promise<readonly PaymentUserError[]>;\n  /** Open a VTEX transaction from the persisted selection. Resolves the payload the gateway call needs. */\n  startTransaction: () => Promise<PaymentStartTransactionResult>;\n  /**\n   * Finalize the transaction after the gateway accepted the card. `acceptChallenges: true` is sent only by\n   * the page the bank returns the shopper to, and only then; omitted, the server asks for a challenge\n   * instead of finishing the order.\n   */\n  gatewayCallback: (\n    orderGroup: string,\n    options?: Readonly<{ acceptChallenges?: boolean }>,\n  ) => Promise<PaymentGatewayCallbackResult>;\n  /**\n   * Façade: post the card straight to the payment gateway. Issues no GraphQL operation and writes\n   * nothing to the cache. Never rejects: resolves `{ reachedGateway, userErrors }`, with one `GATEWAY_ERROR`\n   * userError when the gateway rejects the call or it could not be issued. `reachedGateway` is `false`\n   * only when no request was issued; every outcome it cannot classify is `true`.\n   */\n  sendPayments: (request: SendPaymentsRequest) => Promise<PaymentGatewayResult>;\n}>;\n\nconst INVALID_BIN_ERROR: PaymentUserError = { code: 'INVALID_BIN_FORMAT', message: INVALID_BIN_MESSAGE };\n\n// Diagnostic `message` (logs, `onResult`); each reader words `NETWORK_ERROR` from its own content.\nconst NETWORK_ERROR: PaymentUserError = {\n  code: PAYMENT_NETWORK_ERROR_CODE,\n  message: 'Unable to complete the request. Please try again.',\n};\n\n/** Mirrors the resolver's own nulled-fields constant, so one added field is nulled in one place. */\nconst EMPTY_START_TRANSACTION = {\n  transactionId: null,\n  merchantName: null,\n  gatewayUrl: null,\n  orderGroup: null,\n  orderNodeId: null,\n  userProfileId: null,\n  value: null,\n  valueInCents: null,\n  referenceValueInCents: null,\n} as const;\n\n/**\n * The `payment` namespace hook. Registered with the first-party action registry via `paymentActions`\n * below; the compiler-emitted `PaymentActionProvider` calls it and threads the narrowed methods into\n * each consumer's `$actions.payment`. Writes persist purely through the normalized-cache merge of each\n * mutation response — no refetch, no imperative cache write.\n */\nexport function usePaymentActions(): PaymentActions {\n  const [methodSelectMutation] = useMutation(PAYMENT_METHOD_SELECT);\n  const [installmentSelectMutation] = useMutation(PAYMENT_INSTALLMENT_SELECT);\n  const [billingAddressMutation] = useMutation(PAYMENT_BILLING_ADDRESS_UPDATE);\n  const [preferencesMutation] = useMutation(CLIENT_PREFERENCES_UPDATE);\n  const [startTransactionMutation] = useMutation(PAYMENT_START_TRANSACTION);\n  const [gatewayCallbackMutation] = useMutation(PAYMENT_GATEWAY_CALLBACK);\n\n  const setMethod = useCallback<PaymentActions['setMethod']>(\n    async (input) => {\n      // Refused here, before the value can reach the network, the GraphQL variables or the Apollo cache.\n      // Logs nothing: the input carries the value being refused.\n      if (!isAcceptedBin(input)) return [INVALID_BIN_ERROR];\n      try {\n        const result = await methodSelectMutation({ variables: { input } });\n        return result.data?.paymentMethodSelect.userErrors ?? [];\n      } catch (error) {\n        // Log only the error name — the input carries the card's BIN, and a variable-coercion error's\n        // message echoes the offending value (`got invalid value … at \"input.bin\"`).\n        console.error('[payment.setMethod] paymentMethodSelect failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [methodSelectMutation],\n  );\n\n  const setInstallments = useCallback<PaymentActions['setInstallments']>(\n    async (count) => {\n      try {\n        const result = await installmentSelectMutation({ variables: { input: { count } } });\n        return result.data?.paymentInstallmentSelect.userErrors ?? [];\n      } catch (error) {\n        console.error('[payment.setInstallments] paymentInstallmentSelect failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [installmentSelectMutation],\n  );\n\n  const setBillingAddress = useCallback<PaymentActions['setBillingAddress']>(\n    async (input) => {\n      try {\n        const result = await billingAddressMutation({ variables: { input } });\n        return result.data?.paymentBillingAddressUpdate.userErrors ?? [];\n      } catch (error) {\n        // Log only the error name — the message can echo the submitted address (PII).\n        console.error('[payment.setBillingAddress] paymentBillingAddressUpdate failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [billingAddressMutation],\n  );\n\n  const saveCard = useCallback<PaymentActions['saveCard']>(\n    async (enabled) => {\n      try {\n        const result = await preferencesMutation({ variables: { input: { savePersonalData: enabled } } });\n        return result.data?.clientPreferencesUpdate?.userErrors ?? [];\n      } catch (error) {\n        console.error('[payment.saveCard] clientPreferencesUpdate failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [preferencesMutation],\n  );\n\n  const startTransaction = useCallback<PaymentActions['startTransaction']>(async () => {\n    try {\n      const result = await startTransactionMutation();\n      const payload = result.data?.paymentStartTransaction;\n      return {\n        transactionId: payload?.transactionId ?? null,\n        merchantName: payload?.merchantName ?? null,\n        gatewayUrl: payload?.gatewayUrl ?? null,\n        orderGroup: payload?.orderGroup ?? null,\n        orderNodeId: payload?.orderNodeId ?? null,\n        userProfileId: payload?.userProfileId ?? null,\n        value: payload?.value ?? null,\n        valueInCents: payload?.valueInCents ?? null,\n        referenceValueInCents: payload?.referenceValueInCents ?? null,\n        userErrors: payload?.userErrors ?? [],\n      };\n    } catch (error) {\n      console.error('[payment.startTransaction] paymentStartTransaction failed', loggableErrorName(error));\n      return { ...EMPTY_START_TRANSACTION, userErrors: [NETWORK_ERROR] };\n    }\n  }, [startTransactionMutation]);\n\n  const gatewayCallback = useCallback<PaymentActions['gatewayCallback']>(\n    async (orderGroup, options) => {\n      try {\n        const input = options?.acceptChallenges === true ? { orderGroup, acceptChallenges: true } : { orderGroup };\n        const result = await gatewayCallbackMutation({ variables: { input } });\n        const payload = result.data?.paymentGatewayCallback;\n        return {\n          orderId: payload?.orderId ?? null,\n          orderNodeId: payload?.orderNodeId ?? null,\n          ...(payload?.redirectUrl ? { redirectUrl: payload.redirectUrl } : {}),\n          userErrors: payload?.userErrors ?? [],\n        };\n      } catch (error) {\n        console.error('[payment.gatewayCallback] paymentGatewayCallback failed', loggableErrorName(error));\n        return { orderId: null, orderNodeId: null, userErrors: [NETWORK_ERROR] };\n      }\n    },\n    [gatewayCallbackMutation],\n  );\n\n  const sendPayments = useCallback<PaymentActions['sendPayments']>(async (request) => {\n    try {\n      return await postPaymentsToGateway(request);\n    } catch (error) {\n      // Log the error NAME ONLY. The request carries a card number and CVV, and a thrown fetch error's\n      // message can echo the URL or the body — nothing on this path is ever serialized to a log.\n      console.error('[payment.sendPayments] gateway request failed', loggableErrorName(error));\n      // A rejected request is unclassified — it may have been processed — so it counts as reached.\n      return { reachedGateway: true, userErrors: [PAYMENT_GATEWAY_USER_ERROR] };\n    }\n  }, []);\n\n  return useMemo(\n    () => ({\n      setMethod,\n      setInstallments,\n      setBillingAddress,\n      saveCard,\n      startTransaction,\n      gatewayCallback,\n      sendPayments,\n    }),\n    [setMethod, setInstallments, setBillingAddress, saveCard, startTransaction, gatewayCallback, sendPayments],\n  );\n}\n\n/**\n * Declares the `payment` action namespace — the single source of truth for its method/payload metadata,\n * runtime provider, and `use` hook (mirrors `cartActions`, `shippingActions`). The native catalog\n * builder (`scripts/build-catalog.mjs`) statically reads this call to emit `actions.json`; at runtime\n * `PaymentActionProvider` calls `usePaymentActions` directly.\n *\n * `sendPayments`'s `payload` lists only the non-sensitive transaction descriptor's identifiers.\n * `ActionPayloadField` is the surface a schema-bindable name would come from, so the card fields'\n * absence here is the mechanical form of RFC D13: card number and CVV are never expressed as a declared\n * action payload. The `SendPaymentsRequest` type in `gateway.ts` is the source of truth for the real\n * call shape.\n */\nexport const paymentActions = defineActions({\n  namespace: 'payment',\n  description:\n    'Mutation-backed payment writes against the VTEX orderForm paymentData/invoiceData, plus a façade that posts card data directly to the payment gateway (never through our GraphQL layer or cache).',\n  provider: { name: 'PaymentActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    setMethod: {\n      description:\n        'Select a payment method, optionally identifying a new card by BIN or a saved card by account (async/pessimistic). Resolves the payload userErrors.',\n      payload: [\n        { name: 'methodId', type: 'string' },\n        { name: 'bin', type: 'string', optional: true },\n        { name: 'accountId', type: 'string', optional: true },\n      ],\n    },\n    setInstallments: {\n      description:\n        'Select an installment count for the current method (async/pessimistic). The response carries the cart, whose total is the greater of the order form value and the selected payment value, so it includes the interest of the picked tier. Resolves the payload userErrors.',\n      payload: [{ name: 'count', type: 'number' }],\n    },\n    setBillingAddress: {\n      description:\n        'Persist the billing address, or fall back to the delivery address with sameAsDelivery (async/pessimistic). Resolves the payload userErrors.',\n      payload: [\n        { name: 'sameAsDelivery', type: 'boolean' },\n        { name: 'addressType', type: 'string', optional: true },\n        { name: 'postalCode', type: 'string', optional: true },\n        { name: 'country', type: 'string', optional: true },\n        { name: 'street', type: 'string', optional: true },\n        { name: 'number', type: 'string', optional: true },\n        { name: 'complement', type: 'string', optional: true },\n        { name: 'neighborhood', type: 'string', optional: true },\n        { name: 'city', type: 'string', optional: true },\n        { name: 'state', type: 'string', optional: true },\n        { name: 'reference', type: 'string', optional: true },\n      ],\n    },\n    saveCard: {\n      description:\n        'Record the data-storage consent a saved card requires, reusing the existing clientPreferencesUpdate write. Does not itself save the card — the save flag and label travel on sendPayments.',\n      payload: [{ name: 'enabled', type: 'boolean' }],\n    },\n    startTransaction: {\n      description:\n        'Open a VTEX transaction from the persisted payment selection. Takes no arguments; resolves the transaction identifiers the gateway call needs.',\n      payload: [],\n    },\n    gatewayCallback: {\n      description: 'Finalize the transaction after the gateway accepted the card. Resolves the payload userErrors.',\n      payload: [\n        { name: 'orderGroup', type: 'string' },\n        { name: 'acceptChallenges', type: 'boolean', optional: true },\n      ],\n    },\n    sendPayments: {\n      description:\n        'Façade: post the card directly from the browser to the payment gateway. Issues no GraphQL operation and writes nothing to the cache. Resolves { reachedGateway, userErrors }: reachedGateway is false only when no request was issued. The card number and CVV are runtime-only arguments and are deliberately absent from this payload — they are never a bindable field (RFC D13).',\n      payload: [\n        { name: 'gatewayUrl', type: 'string' },\n        { name: 'transactionId', type: 'string' },\n        { name: 'merchantName', type: 'string' },\n        { name: 'orderGroup', type: 'string' },\n        { name: 'userProfileId', type: 'string' },\n      ],\n    },\n  },\n  use: usePaymentActions,\n});\n"],"mappings":"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"}

package/dist/sdk/payment/use-place-order.d.ts

@@ -1,11 +1,13 @@
 import { PaymentMoney } from "./operations.js";
 import "../actions/types.js";
+import "./resumed-purchase.js";
 //#region src/sdk/payment/use-place-order.d.ts
 export type PlaceOrderInstallment = Readonly<{
   count: number;
   /** Per-installment amount, as a display decimal. The gateway's unit is minor units. */
   value: PaymentMoney;
-  interestRate: number;
+  /** `null` when the order form did not say. The gateway body still gets a number: `?? 0` at the descriptor. */
+  interestRate: number | null;
 }>;
 export type PlaceOrderMethod = Readonly<{
   id: string;
@@ -36,7 +38,8 @@ export type PlaceOrderAttemptPhase =
 /** The continuation resolved with no userErrors — the card reached the gateway. */
 'sent' |
 /** The card's fate is unknown: the continuation threw, the POST was aborted, or a finalization got no
- *  answer or only a locked code (`REDIRECT_REQUIRED`, `MISSING_TRANSACTION_COOKIES`). Resume-only.
+ *  answer or only a locked code (`REDIRECT_REQUIRED`, `MISSING_TRANSACTION_COOKIES`,
+ *  `ORDER_GROUP_MISMATCH`). Resume-only.
  *  Treated exactly like `sent`. */
 'unresolved' |
 /** `gatewayCallback` is in flight for this attempt's order group. */
@@ -55,6 +58,11 @@ export type PlaceOrderAttempt = Readonly<{
    * upstream success response body is discarded. So `orderId === orderGroup` on every success today.
    */
   orderId: string | null;
+  /**
+   * The Relay Node ID of the placed order, from `gatewayCallback` (or from `startTransaction` when no
+   * callback runs). Absent until the attempt settles; opaque to this module.
+   */
+  orderNodeId?: string | null;
 }>;
 /**
  * Fix pass (High finding, race #2): widened past a plain value so a write can be made conditional on