@base44/app-plugin-commerce 0.1.5 → 0.1.7

package/base44/shared/commerce/coupons.ts

@@ -69,8 +69,8 @@ export function eligibleLines(coupon: any, lines: CouponLineInput[]): CouponLine
 }
 
 /**
- * The 9 ordered validation checks. Pass `coupon = null` for a lookup miss.
- * Error codes: not_found | expired | usage_limit_reached |
+ * The 10 ordered validation checks. Pass `coupon = null` for a lookup miss.
+ * Error codes: not_found | disabled | expired | usage_limit_reached |
  * usage_limit_per_user_reached | individual_use | min_amount_not_met |
  * max_amount_exceeded | not_applicable | sale_items_excluded | email_restricted
  */
@@ -78,17 +78,23 @@ export function validateCoupon(coupon: any | null, ctx: CouponValidationCtx): Co
   // 1. exists
   if (!coupon) return { valid: false, code: "not_found", error: "Coupon does not exist." };
 
-  // 2. expiry
+  // 2. enabled — a disabled coupon is unusable everywhere: apply-coupon rejects
+  // it, and carts already holding it drop it on the next re-price.
+  if (coupon.enabled === false) {
+    return { valid: false, code: "disabled", error: "This coupon is disabled." };
+  }
+
+  // 3. expiry
   if (coupon.date_expires && new Date(coupon.date_expires).getTime() < Date.now()) {
     return { valid: false, code: "expired", error: "This coupon has expired." };
   }
 
-  // 3. global usage limit
+  // 4. global usage limit
   if (coupon.usage_limit != null && (coupon.usage_count ?? 0) >= coupon.usage_limit) {
     return { valid: false, code: "usage_limit_reached", error: "Coupon usage limit has been reached." };
   }
 
-  // 4. per-user usage limit (usages recorded in used_by, one entry per use)
+  // 5. per-user usage limit (usages recorded in used_by, one entry per use)
   if (coupon.usage_limit_per_user != null && ctx.customerEmail) {
     const uses = (coupon.used_by || []).filter(
       (e: string) => (e || "").toLowerCase() === ctx.customerEmail!.toLowerCase(),
@@ -98,7 +104,7 @@ export function validateCoupon(coupon: any | null, ctx: CouponValidationCtx): Co
     }
   }
 
-  // 5. individual use — both directions
+  // 6. individual use — both directions
   const others = (ctx.appliedCoupons || []).filter((c) => c.code !== coupon.code);
   if (coupon.individual_use && others.length) {
     return { valid: false, code: "individual_use", error: "This coupon cannot be used in conjunction with other coupons." };
@@ -107,7 +113,7 @@ export function validateCoupon(coupon: any | null, ctx: CouponValidationCtx): Co
     return { valid: false, code: "individual_use", error: "An applied coupon does not allow other coupons." };
   }
 
-  // 6. min / max spend (vs items subtotal, ex tax)
+  // 7. min / max spend (vs items subtotal, ex tax)
   if (coupon.minimum_amount != null && coupon.minimum_amount > 0 && ctx.itemsSubtotal < coupon.minimum_amount) {
     return { valid: false, code: "min_amount_not_met", error: `The minimum spend for this coupon is ${coupon.minimum_amount}.` };
   }
@@ -115,7 +121,7 @@ export function validateCoupon(coupon: any | null, ctx: CouponValidationCtx): Co
     return { valid: false, code: "max_amount_exceeded", error: `The maximum spend for this coupon is ${coupon.maximum_amount}.` };
   }
 
-  // 7. product/category restrictions must leave something to discount
+  // 8. product/category restrictions must leave something to discount
   const restricted =
     (coupon.product_ids || []).length || (coupon.excluded_product_ids || []).length ||
     (coupon.product_category_ids || []).length || (coupon.excluded_product_category_ids || []).length;
@@ -124,12 +130,12 @@ export function validateCoupon(coupon: any | null, ctx: CouponValidationCtx): Co
     return { valid: false, code: "not_applicable", error: "Sorry, this coupon is not applicable to your cart contents." };
   }
 
-  // 8. exclude_sale_items must still leave eligible lines
+  // 9. exclude_sale_items must still leave eligible lines
   if (coupon.exclude_sale_items && withoutSaleFilter.length && !eligibleLines(coupon, ctx.lines).length) {
     return { valid: false, code: "sale_items_excluded", error: "Sorry, this coupon is not valid for sale items." };
   }
 
-  // 9. email restrictions
+  // 10. email restrictions
   if ((coupon.email_restrictions || []).length) {
     if (!ctx.customerEmail || !emailMatchesRestriction(ctx.customerEmail, coupon.email_restrictions)) {
       return { valid: false, code: "email_restricted", error: "This coupon is not valid for your email address." };

package/base44/shared/commerce/emails.ts

@@ -150,25 +150,35 @@ export async function sendOrderEmail(
 }
 
 /**
- * Low/out-of-stock notifications to the inventory recipient
+ * Low/out-of-stock notifications to the store operator
  * (kind: "low_stock" | "out_of_stock" | "backorder").
+ *
+ * Configured per type in the `emails` group like every other email in
+ * Settings → Emails (`emails.low_stock.enabled`, `emails.low_stock.recipient`).
  */
 export async function sendStockEmail(sr: any, kind: string, product: any, opts: { settings?: Record<string, any> } = {}): Promise<void> {
   try {
     const settings = opts.settings ?? (await getSettings(sr, "inventory", "emails", "general"));
-    const inv = settings.inventory ?? {};
-    if (kind === "low_stock" && inv.notify_low_stock === false) return;
-    if (kind === "out_of_stock" && inv.notify_out_of_stock === false) return;
-    const to = toAddresses(inv.notification_recipient)[0]
-      ?? toAddresses(settings.emails?.admin_recipients)[0]
-      ?? (await adminUserEmails(sr))[0];
-    if (!to) {
+    const em = settings.emails ?? {};
+    const kindCfg = em[kind] ?? {};
+    if (kindCfg.enabled === false) return;
+
+    // Same chain as admin order emails; comma-separated lists reach every
+    // address, not just the first.
+    const configured = [
+      toAddresses(kindCfg.recipient),
+      toAddresses(em.admin_recipients),
+    ].find((list) => list.length);
+    const recipients = dedupeByAddress(
+      (configured ?? (await adminUserEmails(sr))).map((to) => ({ to, target: "admin" as const })),
+    );
+    if (!recipients.length) {
       await logEmail(sr, {
         type: kind,
         recipient: "",
         target: "admin",
         success: false,
-        error: "no recipient — no inventory recipient, no admin recipients, and no app user has the admin role",
+        error: "no recipient — no stock notification recipient, no admin recipients, and no app user has the admin role",
       });
       return;
     }
@@ -182,15 +192,17 @@ export async function sendStockEmail(sr: any, kind: string, product: any, opts:
     const subject = `${storeName ? `[${storeName}] ` : ""}Product ${labels[kind] ?? kind}: ${product.name}`;
     const body = `<p><strong>${product.name}</strong> (${product.sku || "no SKU"}) ${labels[kind] ?? kind}.</p>
 <p>Remaining stock: ${product.stock_quantity ?? "n/a"}</p>`;
-    try {
-      await sr.integrations.Core.SendEmail({ to, subject, body, from_name: storeName || undefined });
-      await logEmail(sr, { type: kind, recipient: to, target: "admin", subject, success: true });
-    } catch (e) {
-      await logEmail(sr, {
-        type: kind, recipient: to, target: "admin", subject,
-        success: false, error: String((e as Error)?.message ?? e),
-      });
-      throw e;
+    for (const { to } of recipients) {
+      try {
+        await sr.integrations.Core.SendEmail({ to, subject, body, from_name: storeName || undefined });
+        await logEmail(sr, { type: kind, recipient: to, target: "admin", subject, success: true });
+      } catch (e) {
+        await logEmail(sr, {
+          type: kind, recipient: to, target: "admin", subject,
+          success: false, error: String((e as Error)?.message ?? e),
+        });
+        console.error(`sendStockEmail(${kind}) to ${to} failed:`, e);
+      }
     }
   } catch (e) {
     console.error(`sendStockEmail(${kind}) failed:`, e);

package/base44/shared/commerce/money.ts

@@ -35,32 +35,19 @@ export function distributeProportionally(total: number, weights: number[]): numb
 }
 
 /**
- * Format an amount per the store's `general` settings values:
- * {currency, currency_position, thousand_sep, decimal_sep, num_decimals}.
- * Positions: left | right | left_space | right_space.
+ * Format an amount in the store currency (`general.currency`). Formatting is
+ * localization's job, not configuration: `Intl.NumberFormat` renders the
+ * symbol, separators and decimal count for the currency — there are no
+ * position/separator settings to keep in sync.
  */
 export function formatMoney(amount: number, general: Record<string, unknown> = {}): string {
   const code = String(general.currency ?? "USD");
-  const currency = CURRENCIES.find((c) => c.code === code);
-  const symbol = currency?.symbol ?? code;
-  const decimals = Number(general.num_decimals ?? currency?.decimals ?? 2);
-  const thousandSep = String(general.thousand_sep ?? ",");
-  const decimalSep = String(general.decimal_sep ?? ".");
-  const position = String(general.currency_position ?? "left");
-
-  const negative = amount < 0;
-  const fixed = Math.abs(round2(amount)).toFixed(decimals);
-  const [intPart, fracPart] = fixed.split(".");
-  const grouped = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, thousandSep);
-  const num = fracPart ? `${grouped}${decimalSep}${fracPart}` : grouped;
-
-  let out: string;
-  switch (position) {
-    case "right":       out = `${num}${symbol}`; break;
-    case "left_space":  out = `${symbol} ${num}`; break;
-    case "right_space": out = `${num} ${symbol}`; break;
-    case "left":
-    default:            out = `${symbol}${num}`;
+  const value = round2(Number(amount) || 0);
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency: code }).format(value);
+  } catch {
+    // Unknown/custom currency code: fall back to a plain "CODE 12.34".
+    const currency = CURRENCIES.find((c) => c.code === code);
+    return `${currency?.symbol ?? code} ${value.toFixed(currency?.decimals ?? 2)}`;
   }
-  return negative ? `-${out}` : out;
 }

package/base44/shared/commerce/payments.ts

@@ -1,171 +1,34 @@
-// Deploy marker: 1
-// Bump after connecting a payment provider: env vars are injected at deploy time,
-// and editing this file redeploys every commerce/* function.
-// See skills/commerce/references/online-payments.md §2.
 /**
- * Online payments — the provider-neutral utility every caller uses.
+ * Card payment plumbing — the premade order-side half of online payments.
  *
- * Nothing outside this file (and the adapter it points at) knows which payment
- * provider the store uses. Checkout, the payment-link/verify function, the
- * webhook and refunds all call the operations below; the admin UI talks about
- * "an online payment provider", not a brand.
+ * The provider-specific half lives in exactly two files an agent implements
+ * when wiring a provider (see `.agents/skills/commerce/references/online-payments.md`):
  *
- * **The wiring** is one line — `ACTIVE_PROVIDER`. It is bound to the Stripe
- * adapter (`stripe.ts`), which is fully implemented: hosted payment page,
- * payment links, return-verification, webhook signature checking and refunds.
+ *   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.
  *
- * **To use a different provider** (PayPal, Adyen, a local PSP): write an adapter
- * that satisfies `PaymentAdapter` and point `ACTIVE_PROVIDER` at it. That is the
- * whole change on the backend — no caller, no UI and no entity needs touching.
- * See skills/commerce/references/online-payments.md.
- *
- * Credentials always come from the host — an injected secret (Base44 puts the
- * Stripe keys in `STRIPE_SECRET_KEY` / `STRIPE_PUBLISHABLE_KEY` once Stripe is
- * set up for the app) or a connector — never from the `commerce.PaymentGateway`
- * entity and never from the client.
+ * 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.
  */
 import { HttpError } from "./auth.ts";
 import { round2 } from "./money.ts";
 import { transitionOrder } from "./orders.ts";
-import * as stripe from "./stripe.ts";
-
-/** A hosted-payment session: the page a customer pays on. */
-export interface PaymentSession {
-  id: string;
-  url: string;
-  /** "paid" once the provider has the money. */
-  paid: boolean;
-  /** Provider's payment/charge id, stored on the order for refunds. */
-  payment_reference: string;
-  expires_at?: number;
-  /** The order this session was opened for, as the provider recorded it. */
-  order_id: string;
-  order_key: string;
-}
-
-export interface PaymentConnection {
-  connected: boolean;
-  error?: string;
-}
-
-/** What a provider implementation has to offer. Keep these signatures. */
-export interface PaymentAdapter {
-  /** Machine id (e.g. "stripe"); also the connector name on hosts that use one. */
-  id: string;
-  /** Human label — the only place a provider brand belongs in the backend. */
-  label: string;
-  /** The `commerce.PaymentGateway` slug this provider backs. */
-  gatewaySlug: string;
-  connection(sr: any): Promise<PaymentConnection>;
-  createSession(sr: any, order: any, opts: {
-    successUrl: string;
-    cancelUrl: string;
-    customerEmail?: string;
-  }): Promise<PaymentSession>;
-  retrieveSession(sr: any, sessionId: string): Promise<PaymentSession>;
-  /**
-   * Invalidate a previously issued payment page, if the provider supports it, so
-   * an old link can't be paid after the order changed. Best-effort.
-   */
-  expireSession?(sr: any, sessionId: string): Promise<boolean>;
-  refund(sr: any, opts: {
-    paymentReference: string;
-    amount: number;
-    currency: string;
-    reason?: string;
-    idempotencyKey?: string;
-  }): Promise<{ id: string; status: string; amount: number }>;
-  /** True when the raw webhook body really came from the provider. */
-  verifyWebhook(opts: { payload: string; header: string; secret: string }): Promise<boolean>;
-  /** Pull the fields the order lifecycle needs out of a webhook body. */
-  parseWebhookEvent(body: any): {
-    type: string;
-    paid: boolean;
-    order_id: string;
-    order_key: string;
-    session_id: string;
-    payment_reference: string;
-  };
-}
+import { checkCardPaymentPaid, createCardPayment, refundCardPayment } from "./card-payment.ts";
 
-// ── the Stripe adapter ───────────────────────────────────────────────────────
+/** The one `commerce.PaymentGateway` slug that pays online; all others are manual. */
+export const CARD_GATEWAY_SLUG = "card";
 
-function toPaymentSession(session: stripe.CheckoutSession): PaymentSession {
-  return {
-    id: session.id,
-    url: session.url,
-    paid: session.payment_status === "paid",
-    payment_reference: session.payment_intent,
-    expires_at: session.expires_at,
-    order_id: session.order_id,
-    order_key: session.order_key,
-  };
+/** Does this gateway slug mean "pay by card on the provider's hosted page"? */
+export function isCardGateway(slug: string): boolean {
+  return String(slug || "") === CARD_GATEWAY_SLUG;
 }
 
-const stripeAdapter: PaymentAdapter = {
-  id: "stripe",
-  label: "Stripe",
-  gatewaySlug: "stripe",
-
-  async connection(sr) {
-    // Verified, not just present: a disconnected or rotated key must stop
-    // reading as connected, or the store advertises card payment it can't take.
-    const check = await stripe.verifyStripeCredential(sr);
-    return { connected: check.ok, error: check.error };
-  },
-
-  async createSession(sr, order, opts) {
-    return toPaymentSession(await stripe.createCheckoutSession(sr, order, opts));
-  },
-
-  async retrieveSession(sr, sessionId) {
-    return toPaymentSession(await stripe.retrieveCheckoutSession(sr, sessionId));
-  },
-
-  expireSession(sr, sessionId) {
-    return stripe.expireCheckoutSession(sr, sessionId);
-  },
-
-  refund(sr, opts) {
-    return stripe.createStripeRefund(sr, {
-      paymentIntentId: opts.paymentReference,
-      amount: opts.amount,
-      currency: opts.currency,
-      reason: opts.reason,
-      idempotencyKey: opts.idempotencyKey,
-    });
-  },
-
-  verifyWebhook(opts) {
-    return stripe.verifyWebhookSignature(opts);
-  },
-
-  parseWebhookEvent(body) {
-    const type = String(body?.type ?? "");
-    const object = body?.data?.object ?? {};
-    const metadata = object.metadata ?? {};
-    const paid = type === "checkout.session.completed"
-      ? object.payment_status === "paid"
-      : type === "payment_intent.succeeded";
-    return {
-      type,
-      paid,
-      order_id: String(metadata.order_id ?? ""),
-      order_key: String(metadata.order_key ?? ""),
-      session_id: type.startsWith("checkout.session") ? String(object.id ?? "") : "",
-      payment_reference: type.startsWith("checkout.session")
-        ? String(typeof object.payment_intent === "string" ? object.payment_intent : object.payment_intent?.id ?? "")
-        : String(object.id ?? ""),
-    };
-  },
-};
-
-/** ← The one line to change when moving to another provider. */
-export const ACTIVE_PROVIDER: PaymentAdapter = stripeAdapter;
+// ── order bookkeeping ────────────────────────────────────────────────────────
 
-// ── order bookkeeping (provider-neutral meta keys) ───────────────────────────
-
-export const SESSION_META_KEY = "_payment_session_id";
 export const REFERENCE_META_KEY = "_payment_reference";
 
 export function orderMeta(order: any, key: string): string {
@@ -181,6 +44,11 @@ export function withOrderMeta(order: any, entries: Record<string, string>): any[
   return meta;
 }
 
+/** Paid enough to stop asking for money? */
+export function isOrderPaid(order: any): boolean {
+  return Boolean(order?.date_paid) || ["processing", "completed", "refunded"].includes(order?.status);
+}
+
 // ── return URLs ──────────────────────────────────────────────────────────────
 
 /** An absolute http(s) URL — what every provider requires for its return URLs. */
@@ -290,7 +158,7 @@ export function resolveReturnUrls(opts: {
  * confirmed payment state plus the outcome the provider claims in the URL.
  *
  * The URL is only ever a hint (`?payment=success` is editable by anyone), so
- * `paid` — the answer from the provider — always wins over it.
+ * `paid` — the confirmed answer — always wins over it.
  */
 export function paymentReturnState(input: { paid: boolean; outcome?: string }):
   "paid" | "cancelled" | "unpaid" {
@@ -298,141 +166,54 @@ export function paymentReturnState(input: { paid: boolean; outcome?: string }):
   return input.outcome === "cancel" ? "cancelled" : "unpaid";
 }
 
-// ── provider-neutral operations ──────────────────────────────────────────────
-
-/** Does this gateway slug mean "pay online with the configured provider"? */
-export function isOnlineGateway(slug: string): boolean {
-  return String(slug || "") === ACTIVE_PROVIDER.gatewaySlug;
-}
-
-/**
- * Whether the store can actually take an online payment right now.
- *
- * A *live fact about the host's payment setup*, never a constant: surface it from
- * here so a "no payment provider connected" state disappears by itself once the
- * provider is set up.
- */
-export async function onlinePaymentStatus(sr: any): Promise<{
-  provider: string;
-  provider_label: string;
-  gateway_slug: string;
-  connected: boolean;
-  error?: string;
-}> {
-  const conn = await ACTIVE_PROVIDER.connection(sr);
-  return {
-    provider: ACTIVE_PROVIDER.id,
-    provider_label: ACTIVE_PROVIDER.label,
-    gateway_slug: ACTIVE_PROVIDER.gatewaySlug,
-    connected: conn.connected,
-    ...(conn.error ? { error: conn.error } : {}),
-  };
-}
+// ── operations (premade; they call the card-payment.ts stubs) ────────────────
 
 /**
- * Start (or resume) payment for an order: returns the hosted page to send the
- * customer to. Used by checkout right after the order is created **and** by the
- * admin to produce a payment link for an unpaid order — same session either way,
- * so both routes behave identically.
+ * Start (or restart) card payment for an order: returns the hosted page to send
+ * the customer to. Used by checkout right after the order is created **and** by
+ * the admin's "payment link" — same flow either way.
  *
- * The session id and payment reference are stored on the order so the return
- * handler and the webhook can confirm without trusting anything in the URL.
+ * The payment reference is stored on the order so the return handler, the
+ * webhook and refunds can name the payment without trusting the client.
  */
-export async function startOnlinePayment(sr: any, order: any, opts: {
+export async function startCardPayment(sr: any, order: any, opts: {
   successUrl: string;
   cancelUrl: string;
   customerEmail?: string;
-}): Promise<{ provider: string; session_id: string; url: string; expires_at?: number }> {
+}): Promise<{ url: string; reference: string }> {
   if (isOrderPaid(order)) {
     throw new HttpError(409, "This order is already paid.", "already_paid");
   }
-
-  // Retire the previous payment page before minting a new one: after an order is
-  // edited, an older link would otherwise still be payable at the old total.
-  const previousSession = orderMeta(order, SESSION_META_KEY);
-  if (previousSession && ACTIVE_PROVIDER.expireSession) {
-    try {
-      await ACTIVE_PROVIDER.expireSession(sr, previousSession);
-    } catch {
-      // already completed or expired — nothing to do
-    }
-  }
-
-  const session = await ACTIVE_PROVIDER.createSession(sr, order, opts);
-  if (!session.url) {
+  const page = await createCardPayment(sr, order, opts);
+  if (!page?.url) {
     throw new HttpError(502, "The payment provider did not return a payment page.", "payment_session_failed");
   }
   await sr.entities["commerce.Order"].update(order.id, {
-    meta_data: withOrderMeta(order, {
-      [SESSION_META_KEY]: session.id,
-      [REFERENCE_META_KEY]: session.payment_reference,
-    }),
+    meta_data: withOrderMeta(order, { [REFERENCE_META_KEY]: page.reference ?? "" }),
   });
-  return {
-    provider: ACTIVE_PROVIDER.id,
-    session_id: session.id,
-    url: session.url,
-    expires_at: session.expires_at,
-  };
-}
-
-/** Paid enough to stop asking for money? */
-export function isOrderPaid(order: any): boolean {
-  return Boolean(order?.date_paid) || ["processing", "completed", "refunded"].includes(order?.status);
-}
-
-/**
- * Session ids reach us from places the customer controls (a return URL, a webhook
- * body), so without this anyone could pay a cheap order of their own and replay
- * that session against an expensive one — or someone else's.
- */
-function assertSessionBelongsToOrder(session: PaymentSession, order: any): void {
-  const sameOrder = session.order_id && session.order_id === String(order.id);
-  const sameKey = !session.order_key || session.order_key === String(order.order_key ?? "");
-  if (!sameOrder || !sameKey) {
-    throw new HttpError(
-      409,
-      "That payment belongs to a different order.",
-      "session_order_mismatch",
-    );
-  }
+  return { url: page.url, reference: page.reference ?? "" };
 }
 
 /**
- * Confirm a payment and move the order on — **idempotent**, so the webhook and
- * the customer's return can both run in any order and only the first one has an
- * effect (no double stock reduction, coupon counting or emails).
- *
- * Whether money arrived is always asked of the provider; `trustedPaid` (a
- * signature-verified event) only stands in when there is no session to fetch.
+ * Confirm a card payment and move the order on — **idempotent**, so the webhook
+ * and the customer's return can both run in any order and only the first one
+ * has an effect (no double stock reduction, coupon counting or emails).
  *
- * With no `sessionId`, the session stored on the order is used, which is what a
- * "check payment status" button in the admin wants.
+ * Whether money arrived is asked of the provider (`checkCardPaymentPaid`);
+ * `trustedPaid` — a signature-verified webhook event — stands in for that
+ * round trip when the webhook implementation vouches for it.
  */
-export async function confirmOnlinePayment(sr: any, order: any, opts: {
-  sessionId?: string;
-  paymentReference?: string;
+export async function confirmCardPayment(sr: any, order: any, opts: {
+  reference?: string;
   settings?: Record<string, any>;
   actor?: string;
   trustedPaid?: boolean;
 } = {}): Promise<{ paid: boolean; already_confirmed: boolean; order: any }> {
   if (isOrderPaid(order)) return { paid: true, already_confirmed: true, order };
 
-  let paid = false;
-  let reference = opts.paymentReference ?? "";
-
-  const storedSessionId = orderMeta(order, SESSION_META_KEY);
-  const sessionId = opts.sessionId || storedSessionId;
-  if (sessionId) {
-    const session = await ACTIVE_PROVIDER.retrieveSession(sr, sessionId);
-    // The order's own session was minted for it; one from the request must prove it.
-    if (sessionId !== storedSessionId) assertSessionBelongsToOrder(session, order);
-    // A payment intent can succeed a moment before its session reads paid.
-    paid = session.paid || !!opts.trustedPaid;
-    reference = reference || session.payment_reference;
-  } else {
-    paid = !!opts.trustedPaid;
-  }
+  const reference = opts.reference || orderMeta(order, REFERENCE_META_KEY) || String(order?.transaction_id ?? "");
+  const paid = opts.trustedPaid === true ||
+    (reference ? await checkCardPaymentPaid(sr, order, reference) : false);
   if (!paid) return { paid: false, already_confirmed: false, order };
 
   if (reference) {
@@ -445,7 +226,7 @@ export async function confirmOnlinePayment(sr: any, order: any, opts: {
   await transitionOrder(sr, order, "processing", {
     settings: opts.settings,
     actor: opts.actor ?? "payment-provider",
-    note: `Payment received via ${ACTIVE_PROVIDER.label}${reference ? ` (${reference})` : ""}.`,
+    note: `Card payment received${reference ? ` (${reference})` : ""}.`,
   });
   return { paid: true, already_confirmed: false, order };
 }
@@ -453,31 +234,19 @@ export async function confirmOnlinePayment(sr: any, order: any, opts: {
 /**
  * Refund money at the provider. Called *before* the local refund record is
  * written, so a failed provider refund never leaves a phantom refund behind.
- * Returns null when the order has no online payment to refund.
+ * Returns null when the order has no card payment to refund; throws
+ * 501 `card_refund_not_implemented` while `refundCardPayment` is a stub.
  */
-export async function refundOnlinePayment(sr: any, order: any, opts: {
+export async function refundCardOrder(sr: any, order: any, opts: {
   amount: number;
   reason?: string;
-  idempotencyKey?: string;
-}): Promise<{ provider: string; id: string; status: string; amount: number } | null> {
+}): Promise<{ refund_id: string } | null> {
   const reference = order?.transaction_id || orderMeta(order, REFERENCE_META_KEY);
-  if (!isOnlineGateway(order?.payment_method) || !reference) return null;
-
-  const refund = await ACTIVE_PROVIDER.refund(sr, {
-    paymentReference: reference,
+  if (!isCardGateway(order?.payment_method) || !reference) return null;
+  return await refundCardPayment(sr, order, {
+    reference,
     amount: round2(opts.amount),
     currency: String(order.currency || "USD"),
     reason: opts.reason,
-    idempotencyKey: opts.idempotencyKey,
   });
-  return { provider: ACTIVE_PROVIDER.id, ...refund };
-}
-
-/** Webhook plumbing, provider-neutral. */
-export function verifyPaymentWebhook(opts: { payload: string; header: string; secret: string }): Promise<boolean> {
-  return ACTIVE_PROVIDER.verifyWebhook(opts);
-}
-
-export function parsePaymentWebhook(body: any) {
-  return ACTIVE_PROVIDER.parseWebhookEvent(body);
 }

package/base44/shared/commerce/scan.ts

@@ -2,7 +2,7 @@
  * Full-collection scan helper. Base44's filter() is exact-match with a 5k page
  * cap and no total count, so server-side search/aggregation loops pages of 500.
  * Keep `cap` sane — reports over very large stores should move to a
- * materialized stats entity (see skills/commerce/references/limits-and-performance.md).
+ * materialized stats entity (see .agents/skills/commerce/references/limits-and-performance.md).
  */
 
 export interface ScanOpts {

package/base44/shared/commerce/sequence.ts

@@ -4,7 +4,7 @@
  * NOTE ON CONCURRENCY: Base44 has no transactions, so nextOrderNumber() is a
  * read-max-then-increment and two simultaneous checkouts could race. The window
  * is tiny and order ids (not numbers) are the primary key; see
- * skills/commerce/references/limits-and-performance.md for mitigations.
+ * .agents/skills/commerce/references/limits-and-performance.md for mitigations.
  */
 
 const ORDER_NUMBER_START = 1001;