[vctrchu]

Replaces #428 after renaming its branch to vctrchu/pos-payment-intercept-feature-preview. Prior review discussion remains on #428.

Background

Provide an independent, minimal cash-payment intercept example for the POS intercept feature preview. This draft is for review and testing and does not depend on or modify the cart-intercept draft #431.

Related SDK changes: Shopify/ui-extensions#4713 and Shopify/ui-extensions#4714.

Solution

• Add pos-payment-intercept/ and a payment-only templates.pos-payment-intercept.json opt-in catalog exposing pos_payment_intercept. Leave the public templates.json and existing POS templates unchanged.
• Configure paymentvalidations with blocking = true and applies_to = ["cash"] under pos.app.ready.data, paired with pos.payment.validations.resolution.render.
• Return one blocking ERROR at $.payment. The resolution target displays the intercepted method and amount and registers shopify.resolution.onSave; Shopify-owned Save/Next/Done waits for the handler before POS revalidates.
• Store the acknowledgment outside the read-only payment cart as a fingerprint of the cart line UUIDs, payment method, amount, and currency. Matching cash details pass revalidation; changing the cash amount or adding or removing a cart line requires another review. Other payment methods remain outside this cash-only example. A failed storage write does not grant completion.
• No cart mutation, identity verification, compliance claim, or custom completion API.
• Use API 2026-10, SDK 2026.10.0-rc.13, Preact, and offline support.

Prior verification (from the original PR)

• Rendered the Liquid template with the generator's Preact context; verified the original generated identity and source paths, cash-only blocking capability, matching target, locales, catalog, and exact SDK pin.
• Installed generated dependencies and passed shopify app build --skip-dependencies-installation plus tsc --noEmit -p extensions/pos-onsave-payment/tsconfig.json in a disposable app.
• Passed a focused Preact/API smoke check covering one onSave registration, no write before POS save, awaited fingerprint storage, matching payment revalidation, changed-payment invalidation, and failed writes that keep the finding active.
• Authenticated CLI generation reached App Management but was blocked by Cannot find a valid organization. Real POS behavior remains unverified and requires an approved app in a preview-enabled POS environment.

Verification of the latest template fixes

• Exercised Shopify CLI 4.8.0 Liquid copying and top-level source renaming; verified src/payment_intercept/background.js, cash_review.js, and payment_resolution.jsx match the configured modules.
• Passed shopify app build in an isolated generated app.
• Passed a generated Preact/API smoke check: no scroll-box padding override, unreviewed cash blocks, a saved review clears the finding, a changed cash amount blocks again, and the save handler unregisters.
• Native POS visual verification remains outstanding.

Generate for the feature preview

Run these commands from your Shopify app root—the directory containing shopify.app.toml. To create an app first, follow Build your first POS UI extension. Change --name if you want a different extension name.

curl --fail --location \
  "https://raw.githubusercontent.com/Shopify/extensions-templates/vctrchu/pos-payment-intercept-feature-preview/templates.pos-payment-intercept.json" \
  --output /tmp/templates.pos-payment-intercept.json

SHOPIFY_CLI_APP_TEMPLATES_JSON_PATH="/tmp/templates.pos-payment-intercept.json" \
  shopify app generate extension \
  --template pos_payment_intercept \
  --name pos-payment-intercept-feature-preview \
  --clone-url "https://github.com/Shopify/extensions-templates#vctrchu/pos-payment-intercept-feature-preview" \
  --path "$PWD"

What these commands do:

1. curl --fail --location … --output /tmp/… downloads this branch's temporary template catalog. --fail stops on an HTTP error, --location follows redirects, and /tmp keeps the temporary file outside the app.
2. SHOPIFY_CLI_APP_TEMPLATES_JSON_PATH=… shopify app generate extension … uses that catalog for this invocation. The catalog registers the temporary template identifier and maps it to its Preact directory. --clone-url supplies the branch containing the actual template files; it does not register the identifier. --name controls the generated extension name, and --path "$PWD" adds it to the current Shopify app.

The custom catalog replaces CLI's default template catalog only for this command.

Use Shopify CLI 4.8.0 or later; do not pass --flavor. These branch URLs are only for the feature preview. Deployment and runtime testing still require an approved app and preview-enabled POS environment.

Checklist

• I have tophat'd these changes in a real POS environment
• I have squashed my commits into chunks of work with meaningful commit messages