@base44/app-plugin-commerce 0.1.8 → 0.1.11

package/README.md

@@ -8,7 +8,7 @@ It provides a full-featured **commerce data model and behavior** (variant-driven
 
 - **20 entities** — Products (a product sells variants when it carries attributes; no type field), variations, categories, ribbons, attributes + values, reviews, orders (embedded line/shipping/tax/fee/coupon lines), order notes, refunds, coupons, customers, Shipping & Tax Locations (shipping rates + tax groups per location), payment gateways, store settings, webhooks + deliveries, carts, download permissions, email log.
 - **16 backend functions** — 9 admin (`commerce/admin-products`, `commerce/admin-orders`, `commerce/admin-refunds`, `commerce/admin-coupons`, `commerce/admin-customers`, `commerce/admin-reviews`, `commerce/admin-webhooks`, `commerce/admin-reports`, `commerce/admin-tools`), 4 storefront (`commerce/storefront-catalog`, `commerce/storefront-cart`, `commerce/storefront-checkout`, `commerce/storefront-account`), 2 payment (`commerce/payments`, `commerce/payment-webhook`), and an idempotent `commerce/seed-store` — one call seeds the business defaults **and the whole catalog** (products with attributes in, variants/categories/taxonomy created internally).
-- **Online card payments, order side premade** — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook) and refund records are all built. Wiring a provider (Stripe, PayPal, a local PSP…) means implementing **exactly two files** — `base44/shared/commerce/card-payment.ts` and the payment webhook — and nothing else. Every other payment option is manual (on-hold + instructions) and needs no code; the admin can add more in Settings → Payments. See [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md).
+- **Online card payments, order side premade** — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook, both premade) and refund records are all built. Wiring a provider (Stripe, PayPal, a local PSP…) means implementing **four functions in one file** — `base44/shared/commerce/card-payment.ts` — and nothing else; a complete Stripe implementation to paste in ships in [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §2.2. Every other payment option is manual (on-hold + instructions) and needs no code; the admin can add more in Settings → Payments. See [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md).
 - **Shared commerce engine** (`base44/shared/commerce/`) — totals, tax, shipping, coupons, stock, order lifecycle, webhook dispatch (HMAC-signed), emails, card-payment plumbing, plus static country/currency/continent data.
 - **Admin UI** (`src/commerce/admin/`) — a React/Tailwind/shadcn admin with a familiar store back-office information architecture: dashboard, orders, products, coupons, customers, reports, and full settings including webhooks. Admin-role gated.
 - **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free functions for the shopfront you build: `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and variant price ranges; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" copy states a configured rule rather than an invented number. See [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md).
@@ -99,7 +99,7 @@ If you build on Base44's hosted platform, use the Base44 agent/MCP to write the
 ## What's NOT included
 
 - **No visitor/storefront UI.** The storefront **API** is complete (`commerce/storefront-*` functions); building the shopfront is up to you — see [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md). What *does* ship for the storefront is **helper logic**: [`src/commerce/utils/`](./src/commerce/utils/) — framework-free variant-selection functions (map a Size/Color selection to a `ProductVariation` and back, per-option availability, variant price ranges) — plus [`skills/commerce/references/product-render.md`](./skills/commerce/references/product-render.md) (what to render in a grid vs. a product page, and which fields each call returns) and [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md), the variant rules that go with the helpers.
-- **No payment provider** — the order side of card payments is premade (see above), but charging a card needs a provider: implement the two payment files to wire one. Until then the card option answers "card payments are not available yet" at checkout (or switch it off in Settings → Payments), and the manual gateways (bank transfer, cash on delivery, anything the admin adds) carry checkout.
+- **No payment provider** — the order side of card payments is premade (see above), but charging a card needs a provider: implement the four functions in `base44/shared/commerce/card-payment.ts` to wire one (Stripe: paste-in in `skills/commerce/post-installation.md` §2.2). Until then the card option answers "card payments are not available yet" at checkout (or switch it off in Settings → Payments), and the manual gateways (bank transfer, cash on delivery, anything the admin adds) carry checkout.
 - **No scheduled workflows shipped.** Base44 *does* have a scheduler, but this template ships no workflow files — time-based jobs (stock-hold release, cart expiry, webhook-log pruning) run **opportunistically** where possible, and for the rest you (or the Base44 agent) create scheduled workflows that call `commerce/admin-tools`/`commerce/admin-orders` actions — see *Scheduled work* in [`skills/commerce/SKILL.md`](./skills/commerce/SKILL.md).
 
 ## Next steps

package/base44/entities/commerce.Order.jsonc

@@ -84,7 +84,7 @@
     },
     "payment_method": {
       "type": "string",
-      "description": "PaymentGateway slug (e.g. offline|stripe)"
+      "description": "PaymentGateway slug (e.g. offline|card)"
     },
     "payment_method_title": {
       "type": "string",

package/base44/entities/commerce.OrderRefund.jsonc

@@ -21,7 +21,7 @@
     "refunded_payment": {
       "type": "boolean",
       "default": false,
-      "description": "True when a real gateway refund was made (Stripe wiring placeholder — see .agents/skills/commerce/references/online-payments.md)"
+      "description": "True when a real refund was made at the payment provider (via shared/commerce/card-payment.ts refundCardPayment — see .agents/skills/commerce/references/online-payments.md)"
     },
     "restock_items": {
       "type": "boolean",

package/base44/entities/commerce.PaymentGateway.jsonc

@@ -1,12 +1,12 @@
 {
   "name": "commerce.PaymentGateway",
   "type": "object",
-  "description": "Payment gateway configuration. Seeded: offline (settled outside the store) and stripe (processed by commerce/payments + commerce/payment-webhook). Secrets are never stored here; use Base44 secrets.",
+  "description": "Payment gateway configuration. Seeded: offline (settled outside the store) and card (processed by commerce/payments + commerce/payment-webhook via shared/commerce/card-payment.ts). Secrets are never stored here; use Base44 secrets.",
   "properties": {
     "slug": {
       "type": "string",
       "minLength": 1,
-      "description": "Unique gateway id, e.g. offline | stripe"
+      "description": "Unique gateway id, e.g. offline | card"
     },
     "title": {
       "type": "string",
@@ -35,7 +35,7 @@
     },
     "settings": {
       "type": "object",
-      "description": "Per-gateway settings. offline: {account_details: [{account_name, account_number, bank_name, sort_code, iban, bic}]}; stripe: {connector: \"stripe\"} — see .agents/skills/commerce/references/online-payments.md"
+      "description": "Per-gateway settings. offline: {account_details: [{account_name, account_number, bank_name, sort_code, iban, bic}]}; card: {} — provider config lives in code and backend secrets, never here; see .agents/skills/commerce/references/online-payments.md"
     }
   },
   "required": ["slug"],

package/base44/functions/commerce/payment-webhook/entry.ts

@@ -1,66 +1,52 @@
 /**
- * commerce/payment-webhook — file 2 of 2 to implement when wiring a payment
- * provider. File 1 is `base44/shared/commerce/card-payment.ts`.
+ * commerce/payment-webhook — the provider's server-to-server payment callback.
+ * PREMADE: wiring a payment provider does NOT mean editing this file. All
+ * provider-specific logic — including validating the incoming event — lives
+ * in `base44/shared/commerce/card-payment.ts` (`parseWebhook`), the one file
+ * to implement.
  *
- * This is the provider's server-to-server callback — the confirmation path
- * that covers the buyer who pays and closes the tab (the other path is the
- * customer returning to the storefront, which calls `commerce/payments`
- * `complete-return`; both are idempotent, whichever arrives second does
- * nothing).
+ * Trust model: an event body is never believed on its own. `parseWebhook`
+ * names the order (from the metadata `createCardPayment` attached) and only
+ * vouches `paid: true` after real signature verification; otherwise the event
+ * is a nudge and whether money arrived is asked of the provider itself
+ * through `checkCardPaymentPaid`. Either way a forged call can never mark an
+ * order paid, and the `order_key` match below stops an event being pointed
+ * at another order.
  *
- * Implement ONLY `parseWebhook` below. Everything after it is premade: the
- * order lookup, the order_key check, the idempotent confirmation and the
- * order progression (stock, emails, download permissions, store webhooks).
+ * This is one of the two idempotent confirmation paths — it covers the buyer
+ * who pays and closes the tab; the other is the customer returning to the
+ * storefront, which calls `commerce/payments` `complete-return`. Whichever
+ * runs second is a no-op. Register this function's URL with the provider
+ * (e.g. a Stripe webhook endpoint for `checkout.session.completed`).
  *
  * Unlike every other function here this takes the provider's **raw body**
  * rather than an `{action, ...}` envelope, because webhook signatures are
  * computed over those exact bytes.
  *
- * Until implemented, every request answers 400 `webhook_not_implemented`.
+ * Until `parseWebhook` is implemented, every request answers
+ * 400 `webhook_not_implemented`.
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
+import { HttpError } from "../../../shared/commerce/auth.ts";
 import { getSettings } from "../../../shared/commerce/settings.ts";
 import { confirmCardPayment } from "../../../shared/commerce/payments.ts";
+import { parseWebhook } from "../../../shared/commerce/card-payment.ts";
 
 /** Providers retry on non-2xx; answer 200 for anything we deliberately ignore. */
 const ok = (data: unknown, status = 200) => Response.json({ success: true, data }, { status });
 const fail = (status: number, error: string, code: string) =>
   Response.json({ success: false, error, code }, { status });
 
-interface CardWebhookEvent {
-  /** The order the event is about — read it from the event's metadata. */
-  order_id: string;
-  /** Must match the order's key; attach both to the payment when creating it. */
-  order_key: string;
-  /**
-   * Set true ONLY when you verified the request signature AND the event says
-   * the payment succeeded. When false, the event is treated as a nudge naming
-   * an order, and whether money arrived is asked of the provider through
-   * `checkCardPaymentPaid` — useful when no signing secret is available.
-   */
-  paid: boolean;
-  /** The provider's payment id, if the event carries one. */
-  reference?: string;
-}
-
-/**
- * ← IMPLEMENT THIS for your provider: verify the signature (over the raw
- * `payload` bytes) and pull out the order reference. Return null for events
- * that aren't about a payment for one of this store's orders.
- */
-async function parseWebhook(_req: Request, _payload: string): Promise<CardWebhookEvent | null> {
-  return null;
-}
-
 Deno.serve(async (req: Request) => {
   try {
     const payload = await req.text();
 
     const event = await parseWebhook(req, payload);
-    if (!event) {
-      return fail(400, "This store's payment webhook is not implemented.", "webhook_not_implemented");
+    // Not about one of this store's orders — acknowledge so the provider
+    // doesn't retry.
+    if (!event || !event.order_id) {
+      return ok({ ignored: true, reason: "no_order_reference" });
     }
-    if (!event.order_id) return ok({ ignored: true, reason: "no_order_reference" });
 
     const base44 = createClientFromRequest(req);
     const sr = base44.asServiceRole;
@@ -89,6 +75,9 @@ Deno.serve(async (req: Request) => {
       status: result.order.status,
     });
   } catch (e) {
+    if (e instanceof HttpError) {
+      return fail(e.status, e.message, e.code ?? "error");
+    }
     // 500 makes the provider retry, which is what we want for a transient failure.
     console.error("commerce/payment-webhook error:", e);
     return fail(500, (e as Error)?.message ?? "Internal error", "internal_error");

package/base44/shared/commerce/card-payment.ts

@@ -1,14 +1,25 @@
 /**
- * Card payments — file 1 of 2 to implement when wiring a payment provider
- * (Stripe, PayPal, Adyen, a local PSP…). File 2 is the webhook:
- * `base44/functions/commerce/payment-webhook/entry.ts`.
+ * Card payments — the ONE file to implement when wiring a payment provider
+ * (Stripe, PayPal, Adyen, a local PSP…). Implement the four functions below;
+ * no other file changes:
  *
- * Everything around these three functions is already built: checkout creates
- * the order, prices it, holds stock and routes the customer to the URL you
- * return; the webhook and the return page confirm payment idempotently and
- * move the order to processing (stock, emails, download permissions, webhooks
- * all fire from there); admin refunds write the refund record and restock.
- * Implement ONLY the provider calls below — no other file needs to change.
+ *   createCardPayment    → checkout + payment links (hosted payment page)
+ *   checkCardPaymentPaid → confirmation (return page, webhook, admin "Check payment")
+ *   refundCardPayment    → admin refunds through the provider
+ *   parseWebhook         → validate the provider's server-to-server event
+ *
+ * Any provider works; a ready-made reference implementation (Stripe) is in
+ * `.agents/skills/commerce/post-installation.md` §2.2 to paste over this
+ * file — another provider implements the same functions against its own API.
+ *
+ * Everything around these functions is already built: checkout creates the
+ * order, prices it, holds stock and routes the customer to the URL you
+ * return; the return page and the payment webhook confirm payment
+ * idempotently and move the order to processing (stock, emails, download
+ * permissions, webhooks all fire from there); admin refunds write the refund
+ * record and restock. `commerce/payment-webhook` (the function) is PREMADE —
+ * it calls `parseWebhook` from here and never trusts an event that this file
+ * hasn't vouched for.
  *
  * Until implemented, the Credit Card checkout option answers
  * 503 `no_card_payment_provider`.
@@ -34,9 +45,9 @@ export interface CardPaymentPage {
  * Create a payment page for `order.total` in `order.currency`.
  *
  * Send the customer back to `successUrl` / `cancelUrl` after they pay or give
- * up (both already carry order_id/order_key for the return page). If your
- * provider supports metadata, attach `order.id` and `order.order_key` so the
- * webhook can name the order.
+ * up (both already carry order_id/order_key for the return page). Attach
+ * `order.id` and `order.order_key` to the payment's metadata — that is how
+ * the premade webhook names the order when the provider's event comes in.
  */
 export async function createCardPayment(
   _sr: any,
@@ -78,3 +89,46 @@ export async function refundCardPayment(_sr: any, _order: any, _opts: {
     "card_refund_not_implemented",
   );
 }
+
+/** What `parseWebhook` distills a provider's webhook event into. */
+export interface CardWebhookEvent {
+  /** The order the event is about — read it from the event's metadata
+   * (`createCardPayment` attached it). */
+  order_id: string;
+  /** Must match the order's key; the premade webhook rejects the event
+   * otherwise, so a forged event can't be pointed at another order. */
+  order_key: string;
+  /**
+   * Set true ONLY when you verified the request signature over the raw
+   * payload bytes AND the event says the payment succeeded. When false, the
+   * event is treated as an unverified *nudge* naming an order: whether money
+   * actually arrived is then asked of the provider itself through
+   * `checkCardPaymentPaid`. `paid: false` therefore needs no signing secret
+   * and is already forgery-proof — never return true from an unverified body.
+   */
+  paid: boolean;
+  /**
+   * The provider's payment id, ONLY if the event is signature-verified.
+   * Leave unset otherwise — the premade flow then verifies the reference
+   * stored on the order at checkout, so a forged event can't smuggle in a
+   * reference to some other (paid) payment.
+   */
+  reference?: string;
+}
+
+/**
+ * Validate an incoming provider webhook event (raw request + raw body — the
+ * exact bytes, for signature schemes) and name the order it is about. Called
+ * by the premade `commerce/payment-webhook` function on every delivery; the
+ * verification that money actually arrived happens after this, against the
+ * provider, per the `paid` contract above. Return null for events that
+ * aren't about a payment for one of this store's orders (answered 200 so the
+ * provider doesn't retry).
+ */
+export async function parseWebhook(_req: Request, _payload: string): Promise<CardWebhookEvent | null> {
+  throw new HttpError(
+    400,
+    "This store's payment webhook is not implemented.",
+    "webhook_not_implemented",
+  );
+}

package/base44/shared/commerce/payments.ts

@@ -1,18 +1,20 @@
 /**
  * Card payment plumbing — the premade order-side half of online payments.
  *
- * The provider-specific half lives in exactly two files an agent implements
- * when wiring a provider (see `.agents/skills/commerce/references/online-payments.md`):
- *
- *   1. `shared/commerce/card-payment.ts` — create a payment page, check it was
- *      paid, refund it.
- *   2. `functions/commerce/payment-webhook/entry.ts` — parse the provider's
- *      server-to-server event.
+ * The provider-specific half lives in exactly ONE file an agent implements
+ * when wiring a provider: `shared/commerce/card-payment.ts` — four functions
+ * (create a payment page, check it was paid, refund it, validate a webhook
+ * event). Any provider works;
+ * a reference implementation (Stripe) is in
+ * `.agents/skills/commerce/post-installation.md` §2.2, and the
+ * provider-agnostic rules are in
+ * `.agents/skills/commerce/references/online-payments.md`.
  *
  * Everything here — return URLs, storing the payment reference on the order,
  * idempotent confirmation that moves the order to processing, refund routing —
  * is already wired into checkout, the payments function, the webhook and admin
- * refunds. None of it needs touching to add a provider.
+ * refunds. The payment webhook (`functions/commerce/payment-webhook`) is
+ * premade too. None of it needs touching to add a provider.
  */
 import { HttpError } from "./auth.ts";
 import { round2 } from "./money.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.1.8",
+  "version": "0.1.11",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

package/scripts/install.js

@@ -96,8 +96,9 @@
     // remove the old copy so agents don't keep reading the stale one.
     ["skills", "commerce"],
     [".agents", "skills", "commerce", "references", "stripe-payments.md"], // → references/online-payments.md
-    // Payments moved to the two-file model (card-payment.ts + the webhook);
-    // the Stripe adapter and the provider-status hook are gone.
+    // Payments moved to the card-payment.ts model (one file to implement;
+    // the webhook is premade). The old Stripe adapter and the provider-status
+    // hook are gone.
     ["base44", "shared", "commerce", "stripe.ts"],
     ["src", "commerce", "admin", "hooks", "usePaymentProvider.js"],
     // Attributes and their values are edited in the Attributes section of the

package/skills/commerce/SKILL.md

@@ -13,7 +13,7 @@ Operational guidance for extending, operating and building on the Base44 Commerc
 
 ## IMPORTANT — first-time installation
 
-If the template was just installed (or you are installing it right now), read [`.agents/skills/commerce/post-installation.md`](./post-installation.md) **before anything else**: embedding the admin pages, the three-layer admin-role enforcement (do not weaken), seeding the store's data — **one `commerce/seed-store` call takes the whole catalog** (products with attributes; variants, categories, ribbons and Shipping & Tax Locations created internally — §2) — and the **storefront quick start** (§3): logic-only chunks for product list → product page → cart → checkout that make reading the full API docs unnecessary for the happy path. The full install-from-scratch steps are in [`.agents/skills/commerce/installation-guidelines.md`](./installation-guidelines.md).
+If the template was just installed (or you are installing it right now), read [`.agents/skills/commerce/post-installation.md`](./post-installation.md) **before anything else — and, unless the user has a special requirement, read nothing else**: it alone covers embedding the admin pages, the three-layer admin-role enforcement (do not weaken), seeding the store's data — **one `commerce/seed-store` call takes the whole catalog** (products with attributes; variants, categories, ribbons and Shipping & Tax Locations created internally — §2) — **card payments in one file** (§2.2: a complete Stripe implementation to paste over `shared/commerce/card-payment.ts`; the payment webhook is premade), and the **storefront quick start** (§3): logic-only chunks for product list → product page → cart → checkout. The references below and the API docs are for requests that go beyond that happy path, not for the install. The full install-from-scratch steps are in [`.agents/skills/commerce/installation-guidelines.md`](./installation-guidelines.md).
 
 ## Working on the UI
 
@@ -34,7 +34,7 @@ Agents keep shipping storefronts that miss these, and each one breaks buying out
 
 2. **Checkout must present shipping options and send a choice.** Call `set-shipping-address` **as soon as the customer provides an address** — it recalculates the options and cost, and fails with `400 shipping_not_available` when the store doesn't ship there. Then read `shipping_status` on the returned cart: `auto_selected` (one option, already applied) · `chosen` · `choice_required` → **you must show `available_shipping_methods` and call `choose-shipping-method`** · `missing_address` → collect the address first (a single-location store shows its options even before one). `place-order` refuses with `400 shipping_method_required` until then — that is not a bug to work around. (`chosen_shipping_method` on the cart is the rate **id**, a string — display the choice by looking it up in `available_shipping_methods` for its `title`/`cost`, never by rendering the id or dotting into it.)
 
-3. **Handle card payments, and build `/order-received`.** Choosing the card gateway returns `payment.checkout_url` — redirect there (until a payment provider is implemented it answers `503 no_card_payment_provider`; offer the other methods). Every payment link comes back to `/order-received`, which **you must implement**: call `commerce/payments` `complete-return` with the query params and render its `state`. Without that page a customer pays into a 404 and the order is never marked paid. Also persist the `cart_token` from **every** cart response — `add-item` silently starts a fresh cart when the stored token is stale.
+3. **Handle card payments, and build `/order-received`.** Choosing the card gateway returns `payment.checkout_url` — redirect there (until a payment provider is implemented — one file, Stripe paste-in in [`post-installation.md` §2.2](./post-installation.md#22-payments--one-file-any-provider-stripe-as-the-reference) — it answers `503 no_card_payment_provider`; offer the other methods). Every payment link comes back to `/order-received`, which **you must implement**: call `commerce/payments` `complete-return` with the query params and render its `state`. Without that page a customer pays into a 404 and the order is never marked paid. Also persist the `cart_token` from **every** cart response — `add-item` silently starts a fresh cart when the stored token is stale.
 
 4. **Never advertise what isn't configured.** "Free shipping over €150" must come from a real shipping rate that is free or carries a `free_over` threshold on a Shipping & Tax Location. Locations are admin-only data, so a storefront cannot read them: the live answer is the cart's `available_shipping_methods` after `set-shipping-address`, and `shipping-promos.js` normalizes the rules wherever the records *are* in hand. No rule means no banner.
 
@@ -55,7 +55,7 @@ Open the matching file under `.agents/skills/commerce/references/` only when a t
 | Variant selection | attribute-level selectors, resolving a selection to a variation, availability states, incomplete-selection pricing, add-to-cart contract | [`references/storefront-product-page.md`](./references/storefront-product-page.md) |
 | Reviews | stars on cards and the product page, the review list + submit form (public by email, backend ships complete), the auto-approve toggle, UI-enforced policies (login-gated, verified-only, required rating) | [`references/reviews.md`](./references/reviews.md) |
 | Admin product form | changing the product editor — its stacked sections are **Price & Inventory** (tax group, then the attributes, then a row per variant, or a single *Base price* row when there are none), **Modifiers** (`meta_data`), **Downloads**, **Linked products**; one **Visible** toggle drives `status`. Variants reconcile from the attribute values automatically: no generate step, no per-variant delete. Weight and dimensions are per variant. | [`references/admin-product-form.md`](./references/admin-product-form.md) |
-| Online payments | **any storefront or checkout work** — the order side (checkout, confirmation, payment links, refund records) is premade; wiring a provider means implementing exactly two files (`shared/commerce/card-payment.ts` + the payment webhook) | [`references/online-payments.md`](./references/online-payments.md) |
+| Online payments | **any storefront or checkout work** — the order side (checkout, confirmation, payment links, refund records) *and* the payment webhook are premade; wiring a provider means implementing the four functions in one file (`shared/commerce/card-payment.ts`; Stripe = paste [`post-installation.md` §2.2](./post-installation.md#22-payments--one-file-any-provider-stripe-as-the-reference)) | [`references/online-payments.md`](./references/online-payments.md) |
 | Scheduled work | recurring maintenance — stock-hold release, abandoned-cart cleanup, webhook-log pruning, counter-drift repair | [`references/scheduled-work.md`](./references/scheduled-work.md) |
 | Emails | transactional order emails, per-type overrides, deliverability, the email log | [`references/emails.md`](./references/emails.md) |
 | Webhooks | outbound webhooks, HMAC signing, delivery log, auto-disable behavior | [`references/webhooks.md`](./references/webhooks.md) |

package/skills/commerce/docs/api-admin.md

@@ -178,7 +178,7 @@ Actions: `create-link` · `complete-return` · `verify` — the admin side of on
 - **`verify`** — `{ order_id }` → `{ paid, already_confirmed, status, order }`: re-asks the provider and moves the order to `processing` when the money is there. Idempotent.
 - **`complete-return`** — `{ order_id, order_key, payment?, return_url? }` → `{ state, paid, already_confirmed, status, order, payment_link, payment_instructions }`: what the storefront's **mandatory** `/order-received` page calls — confirm, progress the order, and hand back a render-ready result plus a fresh payment link while unpaid (card) or the gateway's payment instructions (manual).
 
-`commerce/payment-webhook` is the provider's server-to-server callback (raw body, no `action` envelope). Its `parseWebhook` is one of the two files to implement when wiring a provider; until then it answers `400 webhook_not_implemented`. See [`../references/online-payments.md`](../references/online-payments.md).
+`commerce/payment-webhook` is the provider's server-to-server callback (raw body, no `action` envelope). The function is **premade** — it validates every event through `card-payment.ts`'s `parseWebhook` and never trusts an event body on its own: an unverified event only names an order, and payment is verified through `checkCardPaymentPaid` against the provider's API, so no signing secret is needed. Until `card-payment.ts` is implemented it answers `400 webhook_not_implemented`; events it can't tie to an order are acknowledged with `200 { ignored: true }` so providers don't retry. See [`../references/online-payments.md`](../references/online-payments.md).
 
 ## commerce/seed-store
 

package/skills/commerce/docs/api-storefront.md

@@ -36,7 +36,7 @@ The backend is considerably richer than a minimal "grid → cart → pay" shop.
 | **Digital products** | entitlement-checked downloads with remaining-count, expiry, and signed URLs for private files | [`get-download`](#commercestorefront-account) |
 | **Store config** | currency (format it with `Intl.NumberFormat`), units, catalog/cart price display — read it and honour it instead of hardcoding | [`get-store-info`](#get-store-info) |
 
-Two things that are **not** in the backend and are yours to build: the visitor UI itself, and the payment provider integration — two files to implement (see [`references/online-payments.md`](../references/online-payments.md)). Payment methods and the currency are admin-owned data — always render them from `get-store-info` rather than a hardcoded list, and format prices with `Intl.NumberFormat(undefined, { style: "currency", currency })`.
+Two things that are **not** in the backend and are yours to build: the visitor UI itself, and the payment provider integration — four functions in one file (Stripe = paste [`post-installation.md` §2.2](../post-installation.md#22-payments--one-file-any-provider-stripe-as-the-reference); other providers: [`references/online-payments.md`](../references/online-payments.md)). Payment methods and the currency are admin-owned data — always render them from `get-store-info` rather than a hardcoded list, and format prices with `Intl.NumberFormat(undefined, { style: "currency", currency })`.
 
 ## Conventions
 
@@ -312,7 +312,7 @@ Separate function, same guest-bearer rule (`order_id` + `order_key`; an admin ma
 
 > **You must build the `/order-received` page** — it is mandatory for payment links to work. No storefront UI ships with the template, and without that route a paying customer lands on a 404 *and* the order never gets marked paid. It only needs to call `complete-return` and render its three states: see [`../references/online-payments.md`](../references/online-payments.md).
 
-Provider callbacks land on `commerce/payment-webhook` (server-to-server) — the second confirmation path, for buyers who pay and close the tab. Whichever path runs second is a no-op. Wiring a payment provider means implementing two files; see [`../references/online-payments.md`](../references/online-payments.md).
+Provider callbacks land on `commerce/payment-webhook` (server-to-server) — the second confirmation path, for buyers who pay and close the tab. Whichever path runs second is a no-op. The webhook function is premade (it verifies through the provider's API, so no signing secret); wiring a payment provider means implementing four functions in one file — see [`../references/online-payments.md`](../references/online-payments.md).
 
 ### `confirm-payment`
 Post-payment hook for an order on the card gateway. **Payload:** `{ order_id, order_key }`.

package/skills/commerce/installation-guidelines.md

@@ -85,7 +85,7 @@ The template ships an AI copilot for store operators:
 
 ## 4. Building on it — the four storefront requirements
 
-If your work includes a customer-facing shopfront, read **[`SKILL.md` → *If you build a storefront, these four are not optional*](./SKILL.md)** before writing it, and [`docs/api-storefront.md`](./docs/api-storefront.md)'s *Required behaviors* table. In short: attribute-level variant selectors resolved to a `variation_id`; shipping options presented and chosen; card payment redirect plus an `/order-received` page; and no offers the store isn't configured for. The API enforces the first three — a storefront that skips them cannot complete a purchase.
+If your work includes a customer-facing shopfront, the quick start in [`post-installation.md` §3](./post-installation.md#3-storefront-quick-start--logic-only) already walks all four requirements — you don't need any other reading. In short: attribute-level variant selectors resolved to a `variation_id`; shipping options presented and chosen; card payment redirect plus an `/order-received` page; and no offers the store isn't configured for. The API enforces the first three — a storefront that skips them cannot complete a purchase. (Day-2 deep dives: [`SKILL.md` → *these four are not optional*](./SKILL.md) and [`docs/api-storefront.md`](./docs/api-storefront.md)'s *Required behaviors* table.)
 
 ## 5. Next steps
 

package/skills/commerce/post-installation.md

@@ -1,6 +1,8 @@
 # Post-installation
 
-What to do right after the static installation ([`installation-guidelines.md`](./installation-guidelines.md)): embed the admin pages into the app, seed the store's data, and build the storefront from the quick start below. Installed into the app at `.agents/skills/commerce/post-installation.md`.
+What to do right after the static installation ([`installation-guidelines.md`](./installation-guidelines.md)): embed the admin pages into the app, seed the store's data, wire payments, and build the storefront from the quick start below. Installed into the app at `.agents/skills/commerce/post-installation.md`.
+
+> **This file is intentionally the whole job.** Unless the user has a special requirement (a non-Stripe payment provider, signature-verified webhooks, filters/reviews/accounts beyond the happy path), do **not** open the `references/` guides or the `docs/` API references — everything needed to ship a working store (admin mount, seeding, product list, product page, cart, checkout, order-received, card payments) is on this page, ending with the [Done when](#4-done-when) checklist. Reading more first just burns time.
 
 ---
 
@@ -131,13 +133,136 @@ The response reports everything:
   "currency": { "value": "EUR", "action": "created" } }   // "updated" | "unchanged" on re-runs; null when not passed
 ```
 
-**Images**: every product needs at least one, and the URL you seed is the URL the store serves — there are no placeholders to swap later. So resolve each image to its **final URL before seeding**: use whatever image generation the app has available and store the returned URL, upload real assets with `base44.integrations.Core.UploadFile({ file })` → public URL, or fall back to stable public stock URLs (`base44/functions/commerce/seed-store/sample-data.ts` shows a working Unsplash pattern). Match the image to the product. If an image isn't ready at seed time, seed without it and set it afterwards through the admin API — don't seed a dead path and compensate in the frontend.
+**Images**: every product needs at least one, and the URL you seed is the URL the store serves — there are no placeholders to swap later. So resolve each image to its **final URL before seeding**: use whatever image generation the app has available and store the returned URL, upload real assets with `base44.integrations.Core.UploadFile({ file })` → public URL, or fall back to stable public stock URLs (`base44/functions/commerce/seed-store/sample-data.ts` shows a working Unsplash pattern). Match the image to the product. Image generation is usually the **slowest step of the whole install** — kick all product images off first, do the rest (router mount, payment file, storefront pages) while they render, and seed once the URLs are back. If an image isn't ready at seed time, seed without it and set it afterwards through the admin API — don't seed a dead path and compensate in the frontend.
 
 A successful response means the data is in — the catalog and settings are live exactly as reported. Write any remaining store-specific settings into `commerce.StoreSettings` (direct CRUD, one record per `group_id` — weight/dimension units are the usual ones; patch `values`, don't replace groups you weren't asked about).
 
-### 2.2 Payments
+### 2.2 Payments — one file, any provider (Stripe as the reference)
+
+The order side of payments is **already implemented** (checkout routing, confirmation, payment links, refund records). The `offline` gateway — and any option the admin adds in Settings → Payments — works with nothing to configure: the order goes on-hold with the option's description as instructions.
+
+The **Credit card** option needs a payment provider — **any** provider works (Stripe, PayPal, Adyen, a local PSP…), and whichever one it is, wiring it touches exactly **one file**: `base44/shared/commerce/card-payment.ts` — four functions, each backing a premade flow. `commerce/payment-webhook` (the function) is **premade — do not edit it**: it calls this file's `parseWebhook` to validate each event and **never trusts an event body on its own** — an unverified event only *names* an order, and whether money arrived is asked of the provider itself through `checkCardPaymentPaid`, so a forged webhook call can never mark an order paid and **no signing secret is needed**. Until the file is implemented the card option answers `503 no_card_payment_provider` at checkout (or switch it off in Settings → Payments).
+
+| Function | Backs |
+|---|---|
+| `createCardPayment` | checkout + payment links (creates the hosted payment page) |
+| `checkCardPaymentPaid` | confirmation — the return page, the webhook and the admin's "Check payment" all verify through it, against the provider's API |
+| `refundCardPayment` | admin refunds with `refund_payment: true` |
+| `parseWebhook` | webhook validation — names the order the event is about; `paid: true` only after signature verification, never from a raw body |
+
+**Stripe is the reference implementation** and ships ready to use — don't write the file yourself; overwrite `base44/shared/commerce/card-payment.ts` with this as-is. For another provider, implement the same four functions against its API instead (same shape: hosted page in, paid-check and refund by `reference`, event naming an order — rules in [`references/online-payments.md`](./references/online-payments.md)):
+
+```ts
+// base44/shared/commerce/card-payment.ts — Stripe implementation
+import Stripe from "npm:stripe@18";
+import { HttpError } from "./auth.ts";
+
+export interface CardPaymentPage {
+  url: string;        // where the customer goes to pay
+  reference: string;  // the provider's id for this payment, stored on the order
+}
+
+const stripe = () => {
+  const key = Deno.env.get("STRIPE_SECRET_KEY");
+  if (!key) {
+    throw new HttpError(503, "Card payments are not configured — the STRIPE_SECRET_KEY secret is missing.", "no_card_payment_provider");
+  }
+  return new Stripe(key);
+};
+
+// Stripe amounts are in minor units; these currencies have none.
+const ZERO_DECIMAL = new Set(["BIF","CLP","DJF","GNF","JPY","KMF","KRW","MGA","PYG","RWF","UGX","VND","VUV","XAF","XOF","XPF"]);
+const minorUnits = (amount: number, currency: string) =>
+  Math.round(Number(amount) * (ZERO_DECIMAL.has(String(currency).toUpperCase()) ? 1 : 100));
+
+export async function createCardPayment(
+  _sr: any,
+  order: any,
+  opts: { successUrl: string; cancelUrl: string; customerEmail?: string },
+): Promise<CardPaymentPage> {
+  // order_id + order_key in the metadata is how the premade payment-webhook
+  // names the order when Stripe's event arrives — keep it on both objects.
+  const metadata = { order_id: String(order.id), order_key: String(order.order_key) };
+  const session = await stripe().checkout.sessions.create({
+    mode: "payment",
+    line_items: [{
+      quantity: 1,
+      price_data: {
+        currency: String(order.currency || "USD").toLowerCase(),
+        product_data: { name: `Order #${order.order_number}` },
+        unit_amount: minorUnits(order.total, order.currency),
+      },
+    }],
+    customer_email: opts.customerEmail || undefined,
+    metadata,
+    payment_intent_data: { metadata },
+    success_url: opts.successUrl,
+    cancel_url: opts.cancelUrl,
+  });
+  if (!session.url) throw new HttpError(502, "Stripe did not return a payment page URL.", "payment_session_failed");
+  return { url: session.url, reference: session.id };
+}
 
-The order side of payments is **already implemented** (checkout routing, confirmation, payment links, refund records). The `offline` gateway — and any option the admin adds in Settings → Payments — works with nothing to configure: the order goes on-hold with the option's description as instructions. The **Credit card** option needs a payment provider, which means implementing exactly two files (`shared/commerce/card-payment.ts` + the payment webhook); until then it answers `503 no_card_payment_provider` at checkout, or can simply be switched off. Details: [`references/online-payments.md`](./references/online-payments.md).
+export async function checkCardPaymentPaid(_sr: any, order: any, reference: string): Promise<boolean> {
+  const session = await stripe().checkout.sessions.retrieve(reference);
+  // The payment must be for THIS order — stops a reference to some other
+  // (paid) session being replayed against a different order.
+  return session.payment_status === "paid" && session.metadata?.order_id === String(order.id);
+}
+
+export async function refundCardPayment(_sr: any, _order: any, opts: {
+  reference: string; amount: number; currency: string; reason?: string;
+}): Promise<{ refund_id: string }> {
+  const session = await stripe().checkout.sessions.retrieve(opts.reference);
+  if (!session.payment_intent) {
+    throw new HttpError(409, "This payment has no charge to refund at Stripe.", "no_charge_to_refund");
+  }
+  const refund = await stripe().refunds.create({
+    payment_intent: String(session.payment_intent),
+    amount: minorUnits(opts.amount, opts.currency),
+  });
+  return { refund_id: refund.id };
+}
+
+/** What parseWebhook distills an event into — the premade webhook's contract. */
+export interface CardWebhookEvent {
+  order_id: string;
+  order_key: string;
+  paid: boolean;       // true only after signature verification — never from a raw body
+  reference?: string;  // only if signature-verified; otherwise the order's stored reference is used
+}
+
+/**
+ * Stripe webhook events. The event body is never trusted: this only names
+ * the order (from the metadata createCardPayment attached) and returns
+ * paid: false, so the premade webhook verifies against Stripe's API through
+ * checkCardPaymentPaid — a forged call can never mark an order paid, and no
+ * signing secret is needed. (Optional fast path that skips the API
+ * round-trip: verify the signature instead — references/online-payments.md.)
+ */
+export async function parseWebhook(_req: Request, payload: string): Promise<CardWebhookEvent | null> {
+  let event: any;
+  try { event = JSON.parse(payload); } catch { return null; }
+  const metadata = event?.data?.object?.metadata;
+  if (!metadata?.order_id || !metadata?.order_key) return null;
+  return { order_id: String(metadata.order_id), order_key: String(metadata.order_key), paid: false };
+}
+```
+
+Then two steps and payments are done (every provider follows this same shape — an API-credential secret, plus registering the premade webhook URL; only the Stripe specifics below vary):
+
+1. **Secret**: ask the user for their Stripe **secret key** and store it as the `STRIPE_SECRET_KEY` app secret (backend env — never in code, never in an entity). Test keys (`sk_test_…`) work end to end.
+2. **Webhook endpoint** — so orders are confirmed even when the buyer pays and closes the tab: register `https://<app-domain>/functions/commerce/payment-webhook` with Stripe for the `checkout.session.completed` event. There is **no signing secret to store** — events are treated as nudges and verified against Stripe's API. Registration is one call with the same secret key (or the user can do it in the Stripe dashboard):
+
+   ```js
+   await fetch("https://api.stripe.com/v1/webhook_endpoints", {
+     method: "POST",
+     headers: { Authorization: `Bearer ${Deno.env.get("STRIPE_SECRET_KEY")}`, "Content-Type": "application/x-www-form-urlencoded" },
+     body: new URLSearchParams({ url: "https://<app-domain>/functions/commerce/payment-webhook", "enabled_events[]": "checkout.session.completed" }),
+   });
+   ```
+
+That's it — checkout redirect, `/order-received` confirmation, the webhook, the admin's "Check payment" button, payment links and provider refunds all run through this one file. **Nothing else to read or edit**: [`references/online-payments.md`](./references/online-payments.md) is only for *other* providers or signature-verified webhooks.
 
 ---
 
@@ -169,7 +294,7 @@ const { products, page, per_page, has_next } = await inv("commerce/storefront-ca
 });                                // sort: -created_date | name | price | -price | popularity | rating
 ```
 
-Each row is a full product record — for a card use `name`, `images[0]?.src`, `price`, `regular_price`, `on_sale`, `short_description`, `stock_status`, `average_rating`/`rating_count` (stars cost no extra call) and `ribbons` (`[{ id, name }]`, may be absent — labels like "Best Seller" for the card corner). **There is no product type flag**: `product.attributes?.length > 0` means the product sells variants and its `price` is a *from*-price rolled up from the cheapest variant — render it as "From …". Categories for the nav come from `{ action: "list-categories" }` (a tree via `parent_id`).
+Each row is a full product record — for a card use `name`, `images[0]?.src` (**may be empty — render a placeholder, never a broken `<img>`**), `price`, `regular_price`, `on_sale` (sale badge), `short_description`, `stock_status`, `average_rating`/`rating_count` (stars cost no extra call) and `ribbons` (`[{ id, name }]`, may be absent — labels like "Best Seller" for the card corner). **There is no product type flag**: `product.attributes?.length > 0` means the product sells variants and its `price` is a *from*-price rolled up from the cheapest variant — render it as "From …". Categories for the nav come from `{ action: "list-categories" }` (a tree via `parent_id`). That is the whole card — no other call or reference needed for the list view.
 
 **Carry forward:** each card links to the product page by **`slug`**.
 
@@ -205,7 +330,9 @@ const cart = await inv("commerce/storefront-cart", {
 localStorage.setItem("cart_token", cart.cart_token);   // ALWAYS — the token may be a new cart's
 ```
 
-A product with attributes is **rejected without a `variation_id`** (`400 variation_required`) — that is why `view.addToCart` and not a bare `product_id` goes into the call. Show `reviews` (`{ items, has_next, average_rating, rating_count }`) and the `upsells`/`cross_sells` summaries the same response carries. On the other cart actions a `404 cart_not_found|cart_expired` means the cached token went stale — clear it and treat the cart as empty.
+A product with attributes is **rejected without a `variation_id`** (`400 variation_required`) — that is why `view.addToCart` and not a bare `product_id` goes into the call. On the other cart actions a `404 cart_not_found|cart_expired` means the cached token went stale — clear it and treat the cart as empty.
+
+**What the page renders — all from this one `get-product` call, no extra reads:** a gallery from `product.images` (`view.display.image` is the variant-selected one; placeholder when empty), name, price from `view.display` (`price`/`regular_price`/`on_sale` → sale badge), one selector per axis, stock state, `short_description` then `description` (**both HTML — render as rich text, don't escape or truncate away the markup**), SKU, `categories` as a breadcrumb, `ribbons` as light labels near the metadata, the `reviews` block (`{ items, has_next, average_rating, rating_count }`), and the `upsells`/`cross_sells` summaries. Descriptive properties (Material, Care…) live in `product.meta_data` — render them as a spec table; they are not attributes and not ribbons. That is the complete product page — [`references/storefront-product-page.md`](./references/storefront-product-page.md) and [`references/product-render.md`](./references/product-render.md) are only for edge cases and for adding fields to the *listing* call.
 
 **Carry forward:** the **`cart_token`** — from the response, every time.
 
@@ -257,8 +384,8 @@ A store with exactly **one shipping zone** shows its options (and, auto-selected
 The checkout page renders **two sets of options that are store data, never hardcoded**: the shipping methods (already resolved on the cart in step 3 — `place-order` refuses with `400 shipping_method_required` until `shipping_status` is `chosen`/`auto_selected`/`not_needed`) and the payment methods, which come from `info.payment_gateways` (step 1) — every gateway the admin has **enabled**:
 
 ```js
-// wiring a card provider = implementing two files — details:
-// .agents/skills/commerce/references/online-payments.md
+// card payments = ONE file to implement — §2.2 above has the complete
+// Stripe implementation to paste; no other reading needed
 const gateways = info.payment_gateways;   // [{ slug, title, description, online }] — admin-owned data
 // several → render a picker using the admin's title/description as the labels
 // exactly ONE → no picker: use it directly, but still show its title so the customer knows how they'll pay
@@ -308,6 +435,18 @@ Two shapes to get right when rendering: **`order` carries flat totals** — `ord
 
 ---
 
-## 4. Next
+## 4. Done when
+
+Post-installation is complete when every line below holds — verify against this list instead of re-reading docs:
+
+- [ ] `/store-admin/*` mounted behind the shipped `AuthGuard`; `/` routes somewhere real (storefront or a redirect).
+- [ ] `commerce/seed-store` ran once and reported the catalog — real products, final image URLs.
+- [ ] Product list renders from `list-products` (cards: image/placeholder, name, price or "From …", sale badge, stars, ribbons) and links by `slug`.
+- [ ] Product page renders from `get-product` with one selector per attribute, resolving to `view.addToCart`.
+- [ ] Cart → address (`set-shipping-address`) → shipping choice → `place-order` completes, and the `cart_token` is re-persisted from every response.
+- [ ] `/order-received` calls `complete-return` and renders `paid` / `unpaid` / `cancelled`.
+- [ ] Card payments: `card-payment.ts` implemented (Stripe: paste §2.2), `STRIPE_SECRET_KEY` secret set, webhook endpoint registered — **or** the card gateway switched off in Settings → Payments.
+
+## 5. Next
 
 Continue with the commerce skill — [`.agents/skills/commerce/SKILL.md`](./SKILL.md) — for day-2 work: UI changes, deeper storefront features ([`references/product-render.md`](./references/product-render.md) for what to render per view, [`references/storefront-product-page.md`](./references/storefront-product-page.md) for variant edge cases, [`references/reviews.md`](./references/reviews.md) for the ready-made reviews backend), payment provider wiring, scheduled maintenance, emails, webhooks, and operational limits.

package/skills/commerce/references/guest-access-security.md

@@ -13,6 +13,6 @@ The storefront functions run as the service role, so RLS is not protecting the c
 
 - **Identity comes from the session, never from the body.** An email in the payload is a claim, not a credential. Use `getCallerUser(base44)` and `requireUser(user)` from `shared/commerce/auth.ts`, and `ownsEmail(user, email)` before writing to anything keyed on someone's address. This is why `submit-review` requires a signed-in customer (a `reviewer_email` field is ignored) and why a guest checkout attaches to an existing `commerce.Customer` without rewriting its saved name and addresses — otherwise knowing a customer's email would be enough to redirect where their next order ships, or to post a review in their name.
 - **Anything a person owns needs authentication, not just an email.** If you add wishlists, loyalty, saved payment details, subscriptions or support tickets, gate the write on `requireUser` and derive the owner from `user.email` / `user.id`. Guest access is only ever by bearer token (`cart_token`, `order_key`) for the *one* record that token names. (Reviews are the deliberate exception — public by email, moderated instead of authenticated; a session email still always beats the payload.)
-- **Only the payment provider can say an order is paid.** Never transition an order to `processing` because a request said so — no `paid: true` flag, no `transaction_id` from a client, no `?payment=success` in a return URL. Go through `confirmCardPayment()`, which asks the provider about the payment reference stored on the order. Wiring a provider means implementing the two payment files (see [`online-payments.md`](./online-payments.md)), never a new "confirm" endpoint.
+- **Only the payment provider can say an order is paid.** Never transition an order to `processing` because a request said so — no `paid: true` flag, no `transaction_id` from a client, no `?payment=success` in a return URL. Go through `confirmCardPayment()`, which asks the provider about the payment reference stored on the order. Wiring a provider means implementing the four functions in `shared/commerce/card-payment.ts` (see [`online-payments.md`](./online-payments.md)), never a new "confirm" endpoint.
 - **A bearer token authorizes one record.** `order_key` gets you *that* order; it is not a licence to name someone else's ids in the same request. Match every id in the payload back to the record the token opened.
 - **Don't return more than the caller asked about.** Serialize customer-facing orders through `serializeOrderForCustomer()`, and don't let a response reveal whether another person's email exists, bought something, or has an account — a boolean in an error body is an enumeration oracle.

package/skills/commerce/references/online-payments.md

@@ -2,31 +2,47 @@
 
 The store ships with a **Credit card** checkout option (`commerce.PaymentGateway` slug `card`) and everything around it already built — order creation, totals, stock holds, the two idempotent confirmation paths (customer return + provider webhook), payment links for unpaid orders, refund records, emails, and the admin's payment panel.
 
-What it does **not** ship with is a payment provider. Wiring one (Stripe, PayPal, Adyen, a local PSP…) means implementing **exactly two files** — nothing else changes, no entity is touched, no caller or UI needs editing:
+What it does **not** ship with is a payment provider. Wiring one (Stripe, PayPal, Adyen, a local PSP…) means implementing **one file** — `base44/shared/commerce/card-payment.ts`, four functions — and nothing else: no entity is touched, no caller or UI needs editing, and the payment webhook *function* is premade (it calls this file's `parseWebhook`).
 
-| # | File | Implement |
-|---|------|-----------|
-| 1 | `base44/shared/commerce/card-payment.ts` | `createCardPayment` (make a hosted payment page for `order.total`, return `{url, reference}`), `checkCardPaymentPaid` (ask the provider whether `reference` was paid), and optionally `refundCardPayment` |
-| 2 | `base44/functions/commerce/payment-webhook/entry.ts` | `parseWebhook` (verify the provider's signature over the raw body, return `{order_id, order_key, paid, reference?}`) |
+| Function | Backs |
+|---|---|
+| `createCardPayment` | checkout + payment links: make a hosted payment page for `order.total`, return `{ url, reference }`, and attach `order.id`/`order.order_key` to the payment's metadata |
+| `checkCardPaymentPaid` | confirmation: ask the provider whether `reference` was paid **and is the payment for this order** — used by the return page, the webhook and the admin's "Check payment" |
+| `refundCardPayment` | admin refunds through the provider (optional — leave the stub to keep refunds manual) |
+| `parseWebhook` | webhook validation: name the order a provider event is about (from the echoed metadata), and vouch `paid: true` **only** after verifying the request signature over the raw body bytes |
 
-Until file 1 is implemented, picking Credit card at checkout answers `503 no_card_payment_provider` (the storefront should offer the other methods); the admin can also just switch the card option off in Settings → Payments to hide it. Every other payment option is **manual**: the order goes on-hold with the option's description as payment instructions, and the operator moves it on once the money arrives — those need no code at all, and the admin can add more of them in Settings → Payments.
+**Wiring Stripe? Don't start here** — [`post-installation.md` §2.2](../post-installation.md#22-payments--one-file-any-provider-stripe-as-the-reference) has the complete implementation of all four functions to paste in, plus the secret and webhook-endpoint steps. This reference is for other providers and for webhook customization.
+
+Until the file is implemented, picking Credit card at checkout answers `503 no_card_payment_provider` (the storefront should offer the other methods); the admin can also switch the card option off in Settings → Payments to hide it. Every other payment option is **manual**: the order goes on-hold with the option's description as payment instructions, and the operator moves it on once the money arrives — those need no code at all, and the admin can add more of them in Settings → Payments.
 
 ## How the premade flow works
 
 1. **Checkout** (`commerce/storefront-checkout` `place-order` with the `card` gateway): the order is created `pending`, `createCardPayment(sr, order, {successUrl, cancelUrl, customerEmail})` is called, the returned `reference` is stored on the order (`_payment_reference` meta), and the customer is redirected to `url`. The return URLs already carry `order_id`, `order_key` and `payment=success|cancel`.
 2. **Confirmation — two idempotent paths**, whichever runs second is a no-op:
    - **Customer return**: the `/order-received` page calls `commerce/payments` `complete-return`, which runs `checkCardPaymentPaid(sr, order, reference)` and, when true, moves the order to `processing` (stock/email/webhook side-effects fire from the transition).
-   - **Webhook**: register `commerce/payment-webhook`'s URL with the provider. Your `parseWebhook` verifies the signature and names the order; `paid: true` from a **verified** event is trusted directly, `paid: false` makes the premade code re-check via `checkCardPaymentPaid`. The event's `order_key` must match the order — attach `order.id` and `order.order_key` to the payment's metadata in `createCardPayment` so the event can carry them back.
+   - **Webhook**: register `commerce/payment-webhook`'s URL with the provider — it covers the buyer who pays and closes the tab. The function is **premade** and never trusts an event body on its own: it hands the raw request to your `parseWebhook`, which names the order from the `order_id`/`order_key` metadata `createCardPayment` attached. A `paid: false` event is an unverified *nudge* — payment is then verified through `checkCardPaymentPaid` against the provider's API, which is why **no signing secret is needed**: a forged event can at worst trigger a re-check, never mark an order paid, and the `order_key` match stops an event being pointed at another order. `paid: true` is trusted directly and is therefore only allowed after real signature verification.
 3. **Payment links**: `commerce/payments` `create-link` mints a fresh page for any unpaid order via the same `createCardPayment` — used by the admin's payment-link button and the order-received page's "Pay now".
 4. **Refunds**: `commerce/admin-refunds` with `refund_payment: true` calls `refundCardPayment` **before** writing the local record (a failed provider refund writes nothing). While unimplemented it answers `501 card_refund_not_implemented` — record the refund without `refund_payment` and return the money from the provider's own dashboard.
 
 ## Implementation rules
 
 - **Credentials** come from backend secrets/env (`Deno.env.get(...)`) — never from an entity, never from the client. On Base44, env vars are injected at deploy time; after adding a secret, redeploy the backend functions so they can see it.
-- **Only the provider can say an order is paid.** `checkCardPaymentPaid` must ask the provider's API about the stored `reference`; never return true because a request claimed it. In `parseWebhook`, set `paid: true` only after verifying the request signature over the raw body bytes.
+- **Only the provider can say an order is paid.** `checkCardPaymentPaid` must ask the provider's API about the stored `reference`; never return true because a request claimed it. It should also check the payment **names this order** (compare the payment's metadata `order_id` to `order.id`) — that stops a reference to some other, genuinely paid payment being replayed against a different order.
+- **Attach the metadata.** `createCardPayment` must put `order.id` and `order.order_key` on the payment's metadata (Stripe: `metadata` + `payment_intent_data.metadata`) — that echo is how `parseWebhook` names the order, and what the check above compares against.
+- **`parseWebhook` never trusts a raw body.** Return `paid: false` (the verify-via-API nudge) unless you verified the provider's signature over the raw payload bytes; set `reference` only from a verified event, otherwise leave it unset so the premade flow uses the reference stored on the order at checkout.
 - **Amounts**: `order.total` is in display units (e.g. `12.34`) with `order.currency`; convert to the provider's minor units yourself if it needs them.
 - The shared helpers in `base44/shared/commerce/payments.ts` (return-URL building, `confirmCardPayment`, reference bookkeeping) are premade — don't duplicate or bypass them.
 
+## `parseWebhook` in depth
+
+`parseWebhook(req, payload)` lives in `card-payment.ts` with the other three; `commerce/payment-webhook` (the function file) is premade and calls it with the raw request and the raw body — the exact bytes, so signature schemes work. It returns `CardWebhookEvent | null`:
+
+- **The simple, secure default — the nudge**: parse the event, read the `order_id`/`order_key` metadata `createCardPayment` attached, return `{ order_id, order_key, paid: false }`. No signing secret; the premade flow verifies via `checkCardPaymentPaid` against the provider's API, so forgery is impossible by construction. This is what the Stripe reference implementation does.
+- **The signature-verified fast path** (optional): verify the provider's signature over the raw `payload` bytes (Stripe: `constructEventAsync` with a webhook signing secret) and return `paid: true` with the event's `reference` for a verified successful payment; the premade code then trusts it without the API round-trip. `paid: true` from an unverified body is the one way to break this design — never do it.
+- Return **`null`** for events that aren't about a payment for one of this store's orders; the function answers 200 so the provider doesn't retry.
+
+Everything after `parseWebhook` — order lookup, the `order_key` match, idempotent confirmation, order progression — is premade either way.
+
 ## Storefront requirements (unchanged by any of this)
 
 - Redirect to `payment.checkout_url` when `place-order` returns `payment.status === "requires_payment"`.

package/src/commerce/admin/pages/settings/PaymentsSettings.jsx

@@ -205,12 +205,13 @@ export default function PaymentsSettings() {
               </div>
 
               {/* The "card" option redirects to a provider-hosted payment page.
-                  Wiring a provider means implementing the two payment files —
-                  shared/commerce/card-payment.ts + functions/commerce/payment-webhook,
-                  see .agents/skills/commerce/references/online-payments.md. Until
-                  then, picking it at checkout answers 503 no_card_payment_provider.
-                  Deliberately not shown to the store operator — it's developer
-                  guidance, not store configuration. */}
+                  Wiring a provider means implementing the four functions in
+                  shared/commerce/card-payment.ts (Stripe: paste-in in
+                  .agents/skills/commerce/post-installation.md §2.2; the payment
+                  webhook is premade). Until then, picking it at checkout answers
+                  503 no_card_payment_provider. Deliberately not shown to the
+                  store operator — it's developer guidance, not store
+                  configuration. */}
             </div>
           ))}
         </CardContent>