@blamejs/blamejs-shop 0.4.27 → 0.4.28

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.28 (2026-06-11) — **Console refunds reach PayPal, refund webhooks apply their stated amount instead of reversing everything, and gift cards and loyalty points now ride the PayPal button.** A payment-lifecycle release for stores taking PayPal. Refunding a PayPal-paid order from the console — full, partial, or through the returns flow — now dials PayPal; previously every console refund dialed the card processor with a PayPal id and failed, leaving the PayPal dashboard as the only way to refund. Refund webhooks from both processors now apply the amount they state: a partial refund issued from the processor's dashboard reverses gift-card and loyalty credit proportionally, where before it triggered the full terminal reversal and could hand a customer the entire credited value back for a five-dollar refund. PayPal webhook deliveries are now claimed in a replay store after signature verification, the verification call runs on its own circuit breaker behind a per-IP budget so a forged-delivery flood can't fast-fail live checkouts, and a buyer paying with the PayPal button can now apply a gift card or spend loyalty points like any other checkout. A deployment with PayPal credentials but no webhook id gets a boot warning naming the missing variable. Upgrade applies two D1 migrations. **Fixed:** *Console refunds route by the order's payment provider* — Orders persist which processor took the payment, and every refund surface — the order console's full and partial refund, the returns console's provider refund, and the refund-automation library — routes to that processor. PayPal refunds dial the capture (recovered from the order record, the payment transition's metadata, or the PayPal API, in that order), and the operator's idempotency key flows through as the PayPal request id so a retried partial refund deduplicates while distinct partial refunds execute distinctly. Orders that predate the provider column fall back to the payment-id shape. The refund button now reflects provider reality: it offers a refund only when the processor that took the payment is configured, and refuses with a specific reason — provider not configured, no capture on record — instead of a generic failure. · *Refund webhooks apply their stated amount* — A refund event arriving from the processor now reads the refunded amount instead of unconditionally driving the order to the terminal refunded state. A partial refund reverses gift-card and loyalty credit proportionally through the same accounting the console's partial refund uses; only a balance-clearing refund transitions the order to refunded. Both processors are covered: PayPal events carry a per-refund amount and deduplicate on the refund id, card-processor events carry a cumulative total and apply the delta against the local ledger. An event with a missing or unparseable amount is refused so the processor redelivers it — the handler never guesses a full refund. · *Gift cards and loyalty points apply to PayPal button payments* — The PayPal button now sends the gift-card code and loyalty-points fields from the pay form, matching card checkout. When a gift card covers the whole total, the page completes the order and redirects without opening the PayPal popup — the previous behavior surfaced a payment error to the buyer after the order had already been created, paid, and the card debited. **Security:** *PayPal webhook deliveries are claimed once and verified in isolation* — Each verified PayPal event id is claimed in a replay store before any state transition — matching the card-processor webhook discipline — so a replayed or re-delivered event is absorbed exactly once across the redelivery window. The signature-verification call to PayPal runs on its own circuit breaker, and the webhook path carries a per-IP request budget, so a flood of forged deliveries can neither trip the breaker that live checkout dials ride nor crowd out legitimate redeliveries. · *Boot warning when the PayPal webhook id is missing* — A deployment with PayPal client credentials but no PAYPAL_WEBHOOK_ID logs a warning at boot naming the variable. Verification itself remains mandatory and fails closed — without the id every webhook delivery is refused, which keeps forged events out but also means dashboard-issued refunds never mirror locally and PayPal will eventually disable the webhook endpoint; the warning makes that state visible instead of silent.
+
 - v0.4.27 (2026-06-11) — **Stale quotes expire on schedule, operators can reprice an open quote or convert a verbally-approved one to an order, and customers see the operator's per-line notes and the validity window.** A quote-lifecycle release. Quotes whose validity window has elapsed now transition to expired on a scheduled sweep instead of lingering as open work — the accept-time guard already refused stale prices; now the console's queue and the customer's account list reflect that reality, and the admin list gains an expired filter. Operators can reprice a quote that is awaiting the customer's answer (the customer's existing link immediately shows the new pricing) and can convert a quote the customer approved outside the site — by phone or email — directly to an order, with a required reason recorded in the audit log. The customer-facing quote view now renders the per-line notes the operator wrote alongside each price and shows the validity date in the account list. Upgrade applies one D1 migration. **Added:** *Quotes past their validity window expire on a scheduled sweep* — A scheduled tick transitions responded quotes whose valid-until date has elapsed to expired, in one bounded pass per fire. The transition is race-safe: each row re-checks its status and validity inside a conditional update, so a customer accepting at the same moment wins, a reprice that extends validity rescues the quote, and overlapping ticks never double-transition. The sweep rides the same shared-secret internal endpoint discipline as the other scheduled tasks — secret-checked at the edge and again in the container. The per-pass batch size is tunable with QUOTE_EXPIRY_BATCH (validated at boot). · *Operators can reprice a quote awaiting the customer's answer* — A responded quote that the customer has not yet accepted can be repriced from the console — new per-line pricing, shipping, tax, and validity window through the same validation as the original response, with a version counter recording each revision. The customer's existing quote link keeps working and renders the new pricing; no new email is sent, so the link the customer already holds stays valid. Repricing a quote in any other state is refused with a conflict. · *Operators can convert a verbally-approved quote to an order* — When a customer approves a quote outside the site — by phone or email — the operator can convert it to an order directly from the console. The action requires a written reason, records an audit row with the operator, the reason, and the minted order id, and runs through the same conversion path customer acceptance uses: inventory holds are placed first and released if order creation fails, and the accept-time expiry guard still refuses a quote past its validity window. The action requires order-write permission. **Changed:** *The customer quote view shows per-line notes and the validity window* — Notes the operator writes against individual quote lines now render on the customer's quote page under the line they describe, and the account quote list shows the validity date for open quotes — so the customer sees the full offer, not just the numbers, and knows how long it stands. · *The admin quote list gains an expired filter* — The console's quote list accepts a status filter and ships an Expired view, so quotes the sweep transitioned are reviewable rather than invisible. An unrecognized status value falls back to the default queue.
 
 - v0.4.26 (2026-06-06) — **Guest orders attach to an account on verified sign-in; privacy exports and erasures now cover suggestions, saved-for-later, and store credit; HSTS ships on container responses behind the CDN; and internal cron POSTs are secret-checked at the edge.** A guest-order-claim, privacy-completeness, and edge-hardening release. When a shopper who checked out as a guest later signs in or registers with a verified email that matches the order, those orders now attach to their account and appear in their order history. A subject-access export now includes the customer's suggestion-box submissions, their save-for-later list, and their store-credit ledger, and an erasure anonymizes the suggestions, deletes the saved list, and retains the store-credit ledger under its accounting basis — a domain whose reader isn't wired still shows in the export manifest rather than being silently dropped. Strict-Transport-Security now ships on responses served directly by the container behind the Cloudflare proxy, not only on edge-rendered pages. The worker now verifies the shared secret on internal cron and event POSTs before forwarding them to the container. Upgrade applies one D1 migration. **Added:** *Guest orders reconcile to an account on verified sign-in* — An order placed as a guest carries the buyer's email as a one-way hash. When that buyer later signs in or registers — including through Sign in with Google — and their verified email hashes to the same value, the matching guest orders attach to their account and show up under their order history. Attachment is driven only by verified-email ownership, never by unauthenticated email knowledge, and is idempotent: re-signing-in attaches nothing new, a non-matching email attaches nothing, and the placing-browser cookie and emailed-access-token routes to a guest order keep working unchanged. **Changed:** *Privacy export and erasure cover suggestions, saved-for-later, and store credit* — A full subject-access export now includes three more customer-keyed domains: the customer's suggestion-box submissions (product ideas and complaints, matched on the account id or the hashed email the submission carried), their save-for-later list, and their store-credit balance and ledger history. Erasure anonymizes each suggestion in place — severing both identity keys so the row can no longer be traced to the person while leaving the de-identified roadmap signal — deletes the save-for-later list outright, and retains the store-credit ledger under the same accounting / legal-obligation basis the loyalty ledger and gift cards already use. Each domain reports its effect in the request's completeness manifest, so a domain whose reader isn't wired is visible as absent rather than silently omitted. **Security:** *HSTS ships on container responses behind the proxy* — Strict-Transport-Security is emitted on responses served directly by the application container, not only on pages rendered at the edge. Behind the Cloudflare proxy the container connection is plain HTTP and the real scheme arrives in the forwarded-proto header; the security-headers middleware now trusts that header, so a direct-to-container or edge-render-off response carries the same two-year, includeSubDomains, preload HSTS value the edge sends. Plain-HTTP local and direct connections still omit the header, which user agents ignore over HTTP anyway. · *Internal cron and event POSTs are secret-checked at the edge* — The worker now verifies the shared secret on its internal cron and event POSTs (cart-recovery, stock-alert and wishlist sweeps, the stale-order reap, portal-session expiry, and campaign sends) before forwarding them to the container, refusing a forged public request at the edge instead of relying solely on the container's own check. The check is skipped when the secret isn't configured, so a deployment that hasn't set it still forwards rather than refusing every scheduled task.

package/README.md

@@ -68,7 +68,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/shipping.js`** | Operator-table adapter. Services with zones (flat or per-gram + base + min/max), free-over-threshold, `digital_only` flag. |
 | **`lib/delivery-estimate.js`** | "Get it by <date>" promises. Operators define carrier transit times, warehouse cutoffs, holidays, and postal-prefix zones at `/admin/delivery-estimates`; the product and cart pages then show a signed-in customer a delivery date computed against their saved shipping address and the configured origin (`SHOP_ESTIMATE_ORIGIN` or the `shop.estimate_origin` config row). Anonymous, edge-cached pages deliberately render no date — estimates are destination-specific and never bake into the shared cache. Unconfigured stores render nothing, never an error. |
 | **`lib/promo-banners.js`** | Placement-targeted marketing banners (top strip, homepage hero, PDP-side, cart-side, empty-search, footer) with schedule windows, audience targeting, themes, priorities, and click/impression counts. Authored at `/admin/promo-banners`; rendered on both substrates with edge-cache-safe resolution. |
-| **`lib/payment.js`** | Payment adapters — **Stripe** (verify webhook HMAC-SHA256 via upstream `b.webhook.verify`, create / retrieve / confirm / cancel PaymentIntent, refund, register / list payment-method domains for Apple/Google Pay) and **PayPal** (`adapter: "paypal"` — OAuth2 client-credentials token, create / capture / get / refund Orders v2, webhook verify via PayPal's verify-webhook-signature API). No `stripe` / `paypal` npm dep — outbound through `b.httpClient` (SSRF-gated, retried, circuit-broken). |
+| **`lib/payment.js`** | Payment adapters — **Stripe** (verify webhook HMAC-SHA256 via upstream `b.webhook.verify`, create / retrieve / confirm / cancel PaymentIntent, refund, register / list payment-method domains for Apple/Google Pay) and **PayPal** (`adapter: "paypal"` — OAuth2 client-credentials token, create / capture / get / refund Orders v2, webhook verify via PayPal's verify-webhook-signature API). Console refunds route by the order's payment provider — full, partial, and RMA refunds reach the processor that took the payment — and processor-side refund webhooks apply their stated amount, reversing gift-card / loyalty credit proportionally on a partial. Gift cards and loyalty points apply to PayPal button payments the same as card checkout. No `stripe` / `paypal` npm dep — outbound through `b.httpClient` (SSRF-gated, retried, circuit-broken). |
 | **`lib/order.js`** | FSM-driven post-checkout record via upstream `b.fsm`. States: pending → paid → fulfilling → shipped → delivered (+ refunded / cancelled). Every transition appends to `order_transitions`. Guest orders carry the buyer's email as a one-way hash and attach to a customer account when a verified sign-in (passkey / Google / Apple) proves ownership of the same address — never from email knowledge alone — after which they appear in the account's order history. |
 | **`lib/checkout.js`** | Orchestrator. `quote()` returns priced quote; `confirm()` validates the ship-to address (real ISO 3166-1 country; US/CA state + ZIP/postal formats; lenient elsewhere) and the customer email shape, then creates a Stripe PaymentIntent + persists order pending; `handleStripeEvent()` verifies webhook + fires the FSM transition. PayPal path: `createPaypalOrder()` opens a PayPal order + persists pending, `capturePaypalOrder()` captures → paid, `handlePaypalEvent()` is the webhook backstop. All idempotent on re-delivery. |
 | **`lib/email.js`** | Transactional templates — order receipt, ship notification, refund confirmation, wishlist price-drop, abandoned-cart, review request, back-in-stock, **wishlist digest** (the periodic saved-items rollup, rendered per-line from the structured digest so every title / price is independently escaped), and **email magic-link sign-in**. Strict `{{var}}` renderer with HTML escape + refusal of unknown / unused placeholders. Composed on `b.mail` (DKIM/SPF/DMARC/BIMI upstream). |

package/SECURITY.md

@@ -170,6 +170,19 @@ node -e "
   `hmac-sha256-stripe`) inside `lib/payment.js` before any FSM
   transition runs. An unsigned or out-of-window delivery never
   touches origin resources.
+- **PayPal webhook signature + replay refusal.** Inbound `POST` to
+  `/api/webhooks/paypal` is verified server-to-server against PayPal's
+  verify-webhook-signature API using `PAYPAL_WEBHOOK_ID` — set it
+  whenever the PayPal client credentials are set, or every delivery is
+  refused (verification fails closed; the boot log warns when the id is
+  missing). Each verified event id is claimed in a replay store before
+  any state transition, so a re-delivered or replayed event is absorbed
+  exactly once, and refund events apply their stated amount — a partial
+  refund issued from the PayPal dashboard reverses gift-card and
+  loyalty credit proportionally, never in full. The verify call runs on
+  its own circuit breaker and the path carries a per-IP budget, so a
+  forged-delivery flood can neither open the checkout breaker nor
+  drown legitimate redeliveries.
 - **Apple Pay domain-association file.** Apple verifies the domain
   before it will render the Apple Pay wallet button, and it verifies by
   fetching `/.well-known/apple-developer-merchantid-domain-association`.

package/lib/admin.js

@@ -31,6 +31,7 @@
  */
 
 var pricing = require("./pricing");
+var paymentModule = require("./payment");   // _decimalToMinor — normalize a PayPal refund response's decimal amount to minor units
 var collectionsModule = require("./collections");
 var quantityDiscountsModule = require("./quantity-discounts");
 var loyaltyEarnRulesModule = require("./loyalty-earn-rules");
@@ -843,7 +844,8 @@ function mount(router, deps) {
   var catalog       = deps.catalog;
   var order         = deps.order;
   var cart          = deps.cart          || null;   // abandoned-cart visibility console (/admin/carts) disabled when absent
-  var payment       = deps.payment       || null;   // refund endpoints disabled when absent
+  var payment       = deps.payment       || null;   // Stripe handle — Stripe-paid orders refund through this
+  var paypal        = deps.paypal        || null;   // PayPal handle — PayPal-paid orders refund through this; refund endpoints disabled when BOTH are absent
   var mailer        = deps.mailer        || null;   // transactional email factory (lib/email.js) — resend-confirmation disabled when absent
   var _checkout     = deps.checkout      || null;   // reserved — future webhook handler wiring
   var r2            = deps.r2_bridge     || null;   // media-upload endpoint disabled when absent
@@ -2244,7 +2246,7 @@ function mount(router, deps) {
       // a read failure leaves the panel to treat the order as un-refunded
       // (the route re-validates the cap server-side before moving money).
       var refundedMinor = 0;
-      if (payment && o.payment_intent_id) {
+      if (o.payment_intent_id && _refundHandleFor(o)) {
         try { refundedMinor = await order.refundedTotalMinor(o.id); }
         catch (_re) { refundedMinor = 0; }
       }
@@ -2253,9 +2255,12 @@ function mount(router, deps) {
         nav_available: navAvailable,
         order:       o,
         transitions: order.transitionsFrom(o.status),
-        // Refund moves money, so the console only offers it when a payment
-        // provider is wired AND the order has a captured intent to refund.
-        can_refund:  !!(payment && o.payment_intent_id),
+        // Refund moves money, so the console only offers it when the order
+        // has a captured intent AND the provider that captured it is wired —
+        // a Stripe handle can't refund a PayPal-paid order (and vice versa),
+        // so the gate routes by the order's provider, not by "some payment
+        // handle exists".
+        can_refund:  !!(o.payment_intent_id && _refundHandleFor(o)),
         // Partial-refund panel inputs. `refunded_minor` is the running
         // total already refunded; `refundable_minor` is what's left of the
         // order's grand total. The panel renders a decimal-amount form
@@ -4008,27 +4013,162 @@ function mount(router, deps) {
   }
 
   // ---- refunds --------------------------------------------------------
+  //
+  // PROVIDER ROUTING. An order's payment_intent_id is provider-opaque: the
+  // Stripe flow stores a `pi_...` PaymentIntent id, the PayPal flow stores
+  // the PayPal order id. A refund must dial the provider that captured the
+  // charge — sending a PayPal order id into Stripe's refund API (or vice
+  // versa) is a guaranteed upstream 4xx with the operator left reading a
+  // misleading provider error. Every refund surface below (full, partial,
+  // RMA) resolves the order's provider first and routes through
+  // `_issueProviderRefund`, which normalizes the two providers' shapes:
+  //
+  //   stripe → payment.refund({ payment_intent, amount_minor?, reason })
+  //   paypal → paypal.refund({ capture_id, amount_minor?, currency })
+  //
+  // The PayPal capture id (the refund target — NOT the order id) resolves
+  // from the persisted orders.paypal_capture_id column, falling back to the
+  // mark_paid transition metadata for orders captured before the column
+  // existed, then to a remote getOrder read — and heals the column so the
+  // recovery runs once per order.
+
+  // Which provider captured this order's charge. The persisted column is
+  // authoritative; legacy rows (placed before the column existed) fall back
+  // to the payment_intent_id shape — a Stripe PaymentIntent id always
+  // carries the `pi_` prefix, a PayPal order id never does. Returns
+  // "stripe" | "paypal" | null (no provider charge — gift-card / loyalty
+  // fully-covered orders).
+  function _orderPaymentProvider(o) {
+    if (!o) return null;
+    if (o.payment_provider === "paypal" || o.payment_provider === "stripe") return o.payment_provider;
+    if (!o.payment_intent_id) return null;
+    return /^pi_/.test(o.payment_intent_id) ? "stripe" : "paypal";
+  }
+
+  // The wired adapter that can refund this order, or null when the order's
+  // provider isn't configured. This is what the console's refund affordances
+  // gate on — provider REALITY, not merely "some payment handle exists"
+  // (offering a Stripe-backed Refund button on a PayPal order moves no
+  // money and 502s).
+  function _refundHandleFor(o) {
+    var provider = _orderPaymentProvider(o);
+    if (provider === "stripe") return payment;
+    if (provider === "paypal") return paypal;
+    return null;
+  }
+
+  // Resolve the PayPal CAPTURE id a refund runs against. Local resolution
+  // first (column, then transition-metadata recovery — order.paypalCaptureId
+  // heals the column), then a remote getOrder read for pre-existing orders
+  // whose capture id never reached the local ledger. Throws a coded
+  // TypeError (clean 422, nothing dialed for the refund) when no capture
+  // can be found — refunding the ORDER id instead would 404 at PayPal.
+  async function _paypalCaptureIdFor(o) {
+    var local = await order.paypalCaptureId(o.id);
+    if (local) return local;
+    try {
+      var remote = await paypal.getOrder(o.payment_intent_id);
+      var recovered = remote.purchase_units[0].payments.captures[0].id;
+      if (typeof recovered === "string" && recovered.length) {
+        try { await order.setPaypalCapture(o.id, recovered); }
+        catch (_e) { /* drop-silent — healing the column is best-effort; the refund proceeds on the recovered id */ }
+        return recovered;
+      }
+    } catch (_e2) { /* fall through to the coded refusal below */ }
+    var missing = new TypeError("This PayPal order has no recorded capture to refund against — the payment may not have been captured.");
+    missing._refundCode = "no-paypal-capture";
+    throw missing;
+  }
+
+  // Issue the provider refund for an order, routed by provider, normalized
+  // to `{ provider, id, amount_minor, raw }`. `opts2.amount_minor` absent →
+  // a FULL refund of the charge's remaining balance (both providers
+  // implement that natively). `opts2.idempotency_key` is REQUIRED by the
+  // callers' double-refund discipline: Stripe dedupes on Idempotency-Key;
+  // the PayPal adapter folds it into the PayPal-Request-Id, so two distinct
+  // partial slices on the SAME capture carry distinct request ids (PayPal
+  // silently REPLAYS the first refund when the id repeats — it never
+  // executes a second one) while a retry of the same slice stays
+  // deduplicated.
+  async function _issueProviderRefund(o, opts2) {
+    var provider = _orderPaymentProvider(o);
+    var handle   = _refundHandleFor(o);
+    if (!handle) {
+      var unwired = new TypeError(provider === "paypal"
+        ? "This order was paid through PayPal, but PayPal credentials are not configured — set PAYPAL_CLIENT_ID / PAYPAL_SECRET to refund it."
+        : "No payment provider is configured for this order's charge.");
+      unwired._refundCode = "provider-not-configured";
+      throw unwired;
+    }
+    var raw, refundedMinor = null;
+    if (provider === "paypal") {
+      var captureId = await _paypalCaptureIdFor(o);
+      var ppInput = { capture_id: captureId };
+      if (opts2.amount_minor != null) {
+        ppInput.amount_minor = opts2.amount_minor;
+        // A PayPal partial refund names its amount in the CAPTURE currency —
+        // the order's charge currency.
+        ppInput.currency = String(o.currency || "").toUpperCase();
+      }
+      raw = await handle.refund(ppInput, opts2.idempotency_key);
+      // The refund resource echoes its amount as a decimal string; parse it
+      // exactly, falling back to the requested amount when the response
+      // omits it. Stays null on an unparseable full-refund response — the
+      // ledger row then records no amount rather than a guessed one.
+      if (raw && raw.amount && typeof raw.amount.value === "string") {
+        try {
+          refundedMinor = paymentModule._decimalToMinor(
+            raw.amount.value, String(raw.amount.currency_code || o.currency || "").toUpperCase());
+        } catch (_e) { refundedMinor = null; }
+      }
+      if (refundedMinor == null && opts2.amount_minor != null) refundedMinor = opts2.amount_minor;
+    } else {
+      raw = await handle.refund({
+        payment_intent: o.payment_intent_id,
+        amount_minor:   opts2.amount_minor != null ? opts2.amount_minor : undefined,
+        reason:         opts2.reason || undefined,
+        metadata:       opts2.metadata || undefined,
+      }, opts2.idempotency_key);
+      refundedMinor = Number.isInteger(raw && raw.amount) ? raw.amount
+        : (opts2.amount_minor != null ? opts2.amount_minor : null);
+    }
+    return { provider: provider, id: raw && raw.id, amount_minor: refundedMinor, raw: raw };
+  }
 
-  if (payment) {
+  // Ledger metadata for a provider refund: the provider's refund id under
+  // its provider-named key plus the refunded amount. The PayPal key
+  // (`paypal_refund_id`) is ALSO the dedupe identity the webhook mirror
+  // checks — PayPal echoes every refund back as a PAYMENT.CAPTURE.REFUNDED
+  // event whose resource.id is this refund id, and the mirror skips a row
+  // it already finds in the ledger, so an admin-issued refund is never
+  // double-applied when its own webhook arrives.
+  function _refundLedgerMeta(result, extra) {
+    var meta = Object.assign({}, extra || {});
+    meta[result.provider === "paypal" ? "paypal_refund_id" : "stripe_refund_id"] = result.id;
+    if (Number.isInteger(result.amount_minor) && result.amount_minor > 0) meta.amount_minor = result.amount_minor;
+    return meta;
+  }
+
+  if (payment || paypal) {
     // Issue the actual payment-provider refund, then advance the order
     // FSM. Shared by the JSON API and the browser console so a console
     // "Refund" moves the money first (never a bare state change — that
     // would mark an order refunded with the customer never paid back).
     async function _refundOrder(o, body) {
       var refundIdempotencyKey = "refund:" + o.id + ":" + (body.idempotency_suffix || b.uuid.v7());
-      var refund = await payment.refund({
-        payment_intent: o.payment_intent_id,
-        amount_minor:   body.amount_minor || undefined,
-        reason:         body.reason || undefined,
-        metadata:       { order_id: o.id },
-      }, refundIdempotencyKey);
+      var result = await _issueProviderRefund(o, {
+        amount_minor:    body.amount_minor || undefined,
+        reason:          body.reason || undefined,
+        metadata:        { order_id: o.id },
+        idempotency_key: refundIdempotencyKey,
+      });
       try {
         await order.transition(o.id, "refund", {
           reason:   "admin:refund:" + (body.reason || "requested_by_customer"),
-          metadata: { stripe_refund_id: refund.id, amount_minor: refund.amount },
+          metadata: _refundLedgerMeta(result),
         });
       } catch (_e) { /* refund succeeded at the provider; transition refusal logged, surfaced via re-fetch */ }
-      return { refund: refund, order: await order.get(o.id) };
+      return { refund: result.raw, order: await order.get(o.id) };
     }
 
     // Browser confirmation interstitial for the full refund — it moves
@@ -4044,7 +4184,7 @@ function mount(router, deps) {
         var o;
         try { o = await order.get(id); }
         catch (e) { if (!(e instanceof TypeError)) throw e; o = null; }
-        if (!o || !o.payment_intent_id) {
+        if (!o || !o.payment_intent_id || !_refundHandleFor(o)) {
           return _redirect(res, "/admin/orders/" + encodeURIComponent(id) + "?err=1");
         }
         var amount = pricing.format(o.grand_total_minor, o.currency);
@@ -4069,8 +4209,14 @@ function mount(router, deps) {
         try {
           result = await _refundOrder(o, req.body || {});
         } catch (e) {
+          // A coded refusal (the order's provider isn't configured / the
+          // PayPal capture can't be resolved) is a clean 422 — nothing was
+          // dialed, the operator gets the actionable message.
+          if (e instanceof TypeError && e._refundCode) {
+            return _problem(res, 422, e._refundCode, e.message);
+          }
           // allow:admin-5xx-echoes-raw-error-message — 502 surfaces the PAYMENT PROVIDER's refund-failure reason (e.g. "charge already refunded"), an operator-actionable upstream message, not a server/storage internal.
-          return _problem(res, 502, "stripe-refund-failed", (e && e.message) || String(e));
+          return _problem(res, 502, _orderPaymentProvider(o) + "-refund-failed", (e && e.message) || String(e));
         }
         _json(res, 200, result);
         return { id: o.id };
@@ -4083,7 +4229,7 @@ function mount(router, deps) {
         var o;
         try { o = await order.get(id); }
         catch (e) { if (!(e instanceof TypeError)) throw e; o = null; }
-        if (!o || !o.payment_intent_id) {
+        if (!o || !o.payment_intent_id || !_refundHandleFor(o)) {
           return _redirect(res, "/admin/orders/" + encodeURIComponent(id) + "?err=1");
         }
         try {
@@ -4151,15 +4297,19 @@ function mount(router, deps) {
       }
       var clearsBalance = (minor === remainingMinor);
       // Idempotency key folds in the refunded-total seen, so two submits of
-      // the same slice (a double-click, a retry) reuse one provider refund.
+      // the same slice (a double-click, a retry) reuse one provider refund —
+      // and, equally load-bearing on the PayPal side, two DIFFERENT slices
+      // on the same capture carry DIFFERENT keys: the adapter folds this key
+      // into the PayPal-Request-Id, and PayPal silently replays the first
+      // refund (it never executes a second) when the request id repeats.
       var idemKey = "refund:" + o.id + ":partial:" + alreadyMinor + ":" + minor;
-      var refund = await payment.refund({
-        payment_intent: o.payment_intent_id,
-        amount_minor:   minor,
-        reason:         "requested_by_customer",
-        metadata:       { order_id: o.id, partial: !clearsBalance },
-      }, idemKey);
-      var refundedMinor = Number(refund.amount) || minor;
+      var result = await _issueProviderRefund(o, {
+        amount_minor:    minor,
+        reason:          "requested_by_customer",
+        metadata:        { order_id: o.id, partial: !clearsBalance },
+        idempotency_key: idemKey,
+      });
+      var refundedMinor = Number.isInteger(result.amount_minor) && result.amount_minor > 0 ? result.amount_minor : minor;
       if (clearsBalance) {
         // The slice clears the remaining balance — drive the terminal FSM
         // edge so the order moves to `refunded` (and the gift-card / loyalty
@@ -4169,7 +4319,7 @@ function mount(router, deps) {
         try {
           await order.transition(o.id, "refund", {
             reason:   "admin:refund:partial-final",
-            metadata: { stripe_refund_id: refund.id, amount_minor: refundedMinor, partial: true },
+            metadata: _refundLedgerMeta(result, { amount_minor: refundedMinor, partial: true }),
           });
         } catch (_te) { /* provider refund persisted; FSM refusal surfaced via re-fetch */ }
       } else {
@@ -4178,10 +4328,10 @@ function mount(router, deps) {
         await order.recordPartialRefund(o.id, {
           amount_minor: refundedMinor,
           reason:       "admin:refund:partial",
-          metadata:     { stripe_refund_id: refund.id },
+          metadata:     _refundLedgerMeta(result, { amount_minor: refundedMinor }),
         });
       }
-      return { refund: refund, amount_minor: refundedMinor, cleared: clearsBalance };
+      return { refund: result.raw, amount_minor: refundedMinor, cleared: clearsBalance };
     }
 
     router.post("/admin/orders/:id/refund/partial", _pageOrApi(false,
@@ -4195,11 +4345,12 @@ function mount(router, deps) {
           result = await _partialRefund(o, body.amount);
         } catch (e) {
           if (e instanceof TypeError) {
-            var status = e._refundCode === "over-refund" || e._refundCode === "nothing-remaining" ? 422 : 400;
+            var status = e._refundCode === "over-refund" || e._refundCode === "nothing-remaining" ||
+                         e._refundCode === "provider-not-configured" || e._refundCode === "no-paypal-capture" ? 422 : 400;
             return _problem(res, status, e._refundCode || "bad-request", e.message);
           }
           // allow:admin-5xx-echoes-raw-error-message — 502 surfaces the PAYMENT PROVIDER's refund-failure reason, an operator-actionable upstream message, not a server/storage internal.
-          return _problem(res, 502, "stripe-refund-failed", (e && e.message) || String(e));
+          return _problem(res, 502, _orderPaymentProvider(o) + "-refund-failed", (e && e.message) || String(e));
         }
         _json(res, 200, result);
         return { id: o.id };
@@ -4209,7 +4360,7 @@ function mount(router, deps) {
         var o;
         try { o = await order.get(id); }
         catch (e) { if (!(e instanceof TypeError)) throw e; o = null; }
-        if (!o || !o.payment_intent_id) {
+        if (!o || !o.payment_intent_id || !_refundHandleFor(o)) {
           return _redirect(res, "/admin/orders/" + encodeURIComponent(id) + "?err=1");
         }
         var enc = encodeURIComponent(id);
@@ -4710,10 +4861,13 @@ function mount(router, deps) {
     // degrades to "record-only" rather than throwing.
     async function _rmaProviderContext(rma) {
       var ctx = { order: null, canProviderRefund: false };
-      if (!payment || !rma || !rma.order_id) return ctx;
+      if ((!payment && !paypal) || !rma || !rma.order_id) return ctx;
       try { ctx.order = await order.get(rma.order_id); }
       catch (_e) { ctx.order = null; }
-      ctx.canProviderRefund = !!(ctx.order && ctx.order.payment_intent_id);
+      // Provider reality, not mere handle presence: the linked order must
+      // carry a captured intent AND the provider that captured it must be
+      // the one that's wired (see _refundHandleFor).
+      ctx.canProviderRefund = !!(ctx.order && ctx.order.payment_intent_id && _refundHandleFor(ctx.order));
       return ctx;
     }
 
@@ -5012,12 +5166,16 @@ function mount(router, deps) {
       var idem = "rma-refund:" + rma.id;
       var refund;
       try {
-        refund = await payment.refund({
-          payment_intent: order2.payment_intent_id,
-          amount_minor:   (rma.refund_amount_minor != null && rma.refund_amount_minor > 0) ? rma.refund_amount_minor : undefined,
-          reason:         "requested_by_customer",
-          metadata:       { order_id: order2.id, rma_id: rma.id, rma_code: rma.rma_code || "" },
-        }, idem);
+        // Routed by the linked order's provider (Stripe payment_intent vs
+        // PayPal capture) — see _issueProviderRefund. The deterministic key
+        // keeps a retry of the SAME RMA refund deduplicated at either
+        // provider (Stripe Idempotency-Key / PayPal-Request-Id).
+        refund = (await _issueProviderRefund(order2, {
+          amount_minor:    (rma.refund_amount_minor != null && rma.refund_amount_minor > 0) ? rma.refund_amount_minor : undefined,
+          reason:          "requested_by_customer",
+          metadata:        { order_id: order2.id, rma_id: rma.id, rma_code: rma.rma_code || "" },
+          idempotency_key: idem,
+        })).raw;
       } catch (e) {
         // Provider call failed — release the claim so the operator can retry
         // a transient failure. A release failure can't be recovered here, so

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.27",
+  "version": "0.4.28",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-imfe0otYErcB8rr2h6KLSGTtStirysptpXETSPY4zLv3bZoIT75Lo1dOvkOav+xL",
@@ -46,8 +46,8 @@
       "fingerprinted": "js/pay.683a905563e54a47.js"
     },
     "js/paypal-checkout.js": {
-      "integrity": "sha384-LI6y/1z0Y9F8Kx8RhW4EwY2WqJPXLwJozCXqnhDT+dTckLHyvhly0SsRpH0bsdui",
-      "fingerprinted": "js/paypal-checkout.b05ab5572cc3728f.js"
+      "integrity": "sha384-Fxi5GnmvGA/ZoOC7Vomdo2ng37kkp+G9OgjnRiMSQWtl+fmzdUd5p4Yc+fmPQBrt",
+      "fingerprinted": "js/paypal-checkout.7ee687882cc1b588.js"
     },
     "js/saved-card.js": {
       "integrity": "sha384-Kaj6n+Any4rwCH2lyREHoq30MrAZtEd/fTa+tDnIrMJ4zO01YWRhW5TTujcYyuVn",

package/lib/checkout.js

@@ -36,6 +36,10 @@
  */
 
 var b = require("./vendor/blamejs");
+// Shared decimal↔minor conversion (zero-decimal-currency aware) — the
+// PAYMENT.CAPTURE.REFUNDED mirror parses the webhook's decimal amount with
+// the same table the adapter encodes outbound amounts from.
+var paymentLib = require("./payment");
 
 function _uuid(s, label) {
   try { return b.guardUuid.sanitize(s, { profile: "strict" }); }
@@ -262,6 +266,14 @@ function create(deps) {
   var webhookReplayQuery = (typeof deps.webhookReplayQuery === "function")
     ? deps.webhookReplayQuery : null;
   var STRIPE_REPLAY_TTL_MS = b.constants.TIME.minutes(5); // matches the signature tolerance window
+  // PayPal claims live in the same store but keep a much longer window:
+  // PayPal's verify-webhook-signature API has no timestamp tolerance of ours
+  // to lean on, and PayPal redelivers an unacknowledged event for ~3 days
+  // (up to ~25 attempts) — a claim that expired before the last legitimate
+  // redelivery would let a captured payload re-apply. Claimed ids are
+  // namespaced ("paypal:<event-id>") so the two providers can never collide
+  // in the shared table.
+  var PAYPAL_REPLAY_TTL_MS = b.constants.TIME.days(3);
   var _stripeReplayStore = null;
   function _stripeReplay() {
     if (!webhookReplayQuery) return null;
@@ -300,6 +312,147 @@ function create(deps) {
     return _stripeReplayStore;
   }
 
+  // Has a provider refund with this id already been mirrored into the
+  // order's ledger? Scans the hydrated transition rows for a `refund` row
+  // whose metadata carries the same provider refund id. This is what makes
+  // the webhook refund mirror idempotent across BOTH paths a refund reaches
+  // us twice: the admin console issues the refund (stamping the provider
+  // refund id on its ledger row) and the provider then mirrors the same
+  // refund back as a webhook; or the provider redelivers the same event
+  // under a fresh delivery attempt after the replay claim's TTL.
+  function _refundAlreadyRecorded(o, metaKey, refundId) {
+    if (!refundId) return false;
+    var rows = (o && o.transitions) || [];
+    for (var i = 0; i < rows.length; i += 1) {
+      if (rows[i].on_event !== "refund") continue;
+      var meta;
+      try { meta = JSON.parse(rows[i].metadata_json || "{}"); }
+      catch (_e) { meta = {}; }
+      if (meta && meta[metaKey] === refundId) return true;
+    }
+    return false;
+  }
+
+  // Mirror a PayPal PAYMENT.CAPTURE.REFUNDED event into the order ledger,
+  // AMOUNT-AWARE. The resource is the refund object itself: its `amount` is
+  // that single refund's value (NOT a cumulative figure), so a $5 dashboard
+  // refund on a $50 order must append a $5 partial-refund row — never drive
+  // the terminal refund edge, which re-credits every gift-card/loyalty
+  // credit on the order. Only a slice that clears the remaining balance is
+  // terminal. A missing/garbled/currency-mismatched amount THROWS a coded
+  // error the webhook route maps to a 5xx so PayPal redelivers — guessing
+  // "full refund" here is customer-influenceable value creation.
+  async function _mirrorPaypalRefund(o, event, ppOrderId) {
+    var eventType = event.event_type;
+    var resource  = event.resource || {};
+    var refundId  = (typeof resource.id === "string" && resource.id.length) ? resource.id : null;
+    if (o.status === "refunded") {
+      return { handled: true, event_type: eventType, order: o, skipped: "already-advanced" };
+    }
+    if (_refundAlreadyRecorded(o, "paypal_refund_id", refundId)) {
+      return { handled: true, event_type: eventType, order: o, skipped: "already-recorded", paypal_refund_id: refundId };
+    }
+    var amount = resource.amount || {};
+    var amountMinor;
+    try {
+      var ccy = typeof amount.currency_code === "string" ? amount.currency_code.toUpperCase() : "";
+      if (ccy !== String(o.currency || "").toUpperCase()) {
+        throw new TypeError("refund currency " + JSON.stringify(amount.currency_code) +
+                            " does not match order currency " + JSON.stringify(o.currency));
+      }
+      amountMinor = paymentLib._decimalToMinor(amount.value, ccy);
+    } catch (e) {
+      var bad = new Error("checkout: PAYMENT.CAPTURE.REFUNDED resource.amount is missing or unparseable — " +
+                          ((e && e.message) || String(e)));
+      bad.code = "PAYPAL_REFUND_AMOUNT_INVALID";
+      throw bad;
+    }
+    if (amountMinor <= 0) {
+      var zero = new Error("checkout: PAYMENT.CAPTURE.REFUNDED resource.amount must be positive");
+      zero.code = "PAYPAL_REFUND_AMOUNT_INVALID";
+      throw zero;
+    }
+    var refundedSoFar = await order.refundedTotalMinor(o.id);
+    var grand     = Number(o.grand_total_minor) || 0;
+    var remaining = grand - refundedSoFar;
+    if (remaining <= 0) {
+      return { handled: true, event_type: eventType, order: o, skipped: "nothing-remaining" };
+    }
+    var meta = { paypal_event_id: event.id, paypal_order_id: ppOrderId, paypal_refund_id: refundId };
+    if (amountMinor >= remaining) {
+      // Balance-clearing — drive the terminal refund edge (full credit
+      // reversal). The stamped amount is CAPPED at the remaining balance so
+      // refundedTotalMinor converges exactly on the grand total.
+      var updated = await order.transition(o.id, "refund", {
+        reason:   "paypal:" + eventType,
+        metadata: Object.assign({}, meta, { amount_minor: remaining }),
+      });
+      return { handled: true, event_type: eventType, order: updated, amount_minor: remaining };
+    }
+    // Partial — append the same-state ledger row; recordPartialRefund runs
+    // the proportional gift-card / loyalty reversal against the cumulative
+    // refunded total.
+    var updatedPartial = await order.recordPartialRefund(o.id, {
+      amount_minor: amountMinor,
+      reason:       "paypal:" + eventType,
+      metadata:     meta,
+    });
+    return { handled: true, event_type: eventType, order: updatedPartial, partial: true, amount_minor: amountMinor };
+  }
+
+  // Mirror a Stripe charge.refunded event into the order ledger,
+  // AMOUNT-AWARE — same discipline as the PayPal mirror above, adapted to
+  // Stripe's shape: charge.refunded fires on EVERY refund (partial
+  // included); `amount_refunded` is the CUMULATIVE minor-unit total refunded
+  // on the charge and `refunded` is true only when the charge is fully
+  // refunded. The mirrored slice is the DELTA between Stripe's cumulative
+  // figure and the local ledger, which makes the mirror naturally
+  // idempotent against the console's own refunds (the console records
+  // first; the event's delta is then zero). A missing/garbled
+  // amount_refunded throws (5xx → Stripe redelivers) — never guess full.
+  async function _mirrorStripeRefund(o, event) {
+    var eventType = event.type;
+    if (o.status === "refunded") {
+      return { handled: true, event_type: eventType, order: o, skipped: "already-advanced" };
+    }
+    var charge = (event.data && event.data.object) || {};
+    var cumulative = charge.amount_refunded;
+    if (!Number.isInteger(cumulative) || cumulative < 0) {
+      var bad = new Error("checkout: charge.refunded carries no integer amount_refunded — refusing to guess a refund amount");
+      bad.code = "STRIPE_REFUND_AMOUNT_INVALID";
+      throw bad;
+    }
+    var refundedSoFar = await order.refundedTotalMinor(o.id);
+    var grand     = Number(o.grand_total_minor) || 0;
+    var remaining = grand - refundedSoFar;
+    var delta     = cumulative - refundedSoFar;
+    var meta = { stripe_event_id: event.id };
+    if (charge.refunded === true || cumulative >= grand) {
+      // Charge fully refunded — terminal edge. (On a split-tender order the
+      // charge covers only the provider-paid share; a full charge refund
+      // still voids the order, and the terminal edge re-credits the
+      // gift-card / loyalty share — same semantics the admin full-refund
+      // console applies.) Stamp the capped remaining balance so the ledger
+      // converges on the grand total.
+      var updated = await order.transition(o.id, "refund", {
+        reason:   "stripe:" + eventType,
+        metadata: remaining > 0 ? Object.assign({}, meta, { amount_minor: remaining }) : meta,
+      });
+      return { handled: true, event_type: eventType, order: updated };
+    }
+    if (delta <= 0) {
+      // Ledger already at (or past) Stripe's cumulative figure — the
+      // console mirrored this refund when it issued it.
+      return { handled: true, event_type: eventType, order: o, skipped: "already-recorded" };
+    }
+    var updatedPartial = await order.recordPartialRefund(o.id, {
+      amount_minor: delta,
+      reason:       "stripe:" + eventType,
+      metadata:     meta,
+    });
+    return { handled: true, event_type: eventType, order: updatedPartial, partial: true, amount_minor: delta };
+  }
+
   // Reprice a list of cart lines through the quantity-discount engine.
   // Returns a shallow copy with `unit_amount_minor` overwritten by the
   // discounted unit for each line's SKU at its quantity. A line whose
@@ -1095,6 +1248,7 @@ function create(deps) {
           shipping_minor:    quote.totals.shipping_minor,
           grand_total_minor: quote.totals.grand_total_minor,
           payment_intent_id: null,
+          payment_provider:  null,   // credits covered the whole total — no provider charge to refund
           ship_to:           input.ship_to,
           customer_email_hash: emailHash,
           lines:             orderLines,
@@ -1162,6 +1316,7 @@ function create(deps) {
         shipping_minor:    quote.totals.shipping_minor,
         grand_total_minor: quote.totals.grand_total_minor,
         payment_intent_id: pi.id,
+        payment_provider:  "stripe",   // refund surfaces route the refund dial by this
         ship_to:           input.ship_to,
         customer_email_hash: emailHash,
         lines:             orderLines,
@@ -1358,6 +1513,13 @@ function create(deps) {
       var o = await order.byPaymentIntent(pi);
       if (!o) return { handled: false, event_type: eventType, reason: "order-not-found" };
 
+      // Refund events are AMOUNT-AWARE — a partial dashboard refund must
+      // append a partial ledger row, never drive the terminal refund edge
+      // (which re-credits every gift-card/loyalty credit on the order).
+      if (eventType === "charge.refunded") {
+        return await _mirrorStripeRefund(o, event);
+      }
+
       // Idempotency: if the order is already in a state the event
       // would advance to, skip the transition (re-deliveries from
       // Stripe are common).
@@ -1424,16 +1586,31 @@ function create(deps) {
       // Resolve an optional gift-card credit before opening the PayPal
       // order so a bad code fails without a remote round-trip.
       var gc = await _resolveGiftCard(input.gift_card_code, quote);
-      var amountDue = quote.totals.grand_total_minor - (gc ? gc.applied_minor : 0);
       var cartRow = await cart.get(quote.cart_id);
+      // Loyalty points credit stacks on top of any gift-card credit — same
+      // resolution + residual re-cap discipline as the Stripe confirm path
+      // (_confirmAfterHolds), so the two payment buttons honor identical
+      // credits. Requires a signed-in customer; the resolver refuses a
+      // points request on a guest cart with a clean coded error.
+      var ppLoyaltyCustomerId = cartRow ? (cartRow.customer_id || null) : null;
+      var loy = await _resolveLoyaltyCredit(input.loyalty_redeem_points, ppLoyaltyCustomerId, quote);
+      var afterGiftCard = quote.totals.grand_total_minor - (gc ? gc.applied_minor : 0);
+      if (loy && loy.applied_minor > afterGiftCard) {
+        loy.applied_minor = afterGiftCard < 0 ? 0 : afterGiftCard;
+        var ppPerUsd = loyalty.REDEMPTION_POINTS_PER_USD;
+        loy.points = Math.ceil((loy.applied_minor * ppPerUsd) / 100);
+        if (loy.applied_minor <= 0) loy = null;
+      }
+      var amountDue = afterGiftCard - (loy ? loy.applied_minor : 0);
       var emailHash = customers ? customers.hashEmail(email) : null;
       var ppLines = quote.lines.map(function (l) {
         return { variant_id: l.variant_id, sku: l.sku, qty: l.qty, unit_amount_minor: l.unit_amount_minor, unit_currency: l.unit_currency, stock_held_qty: l._held_qty || 0 };
       });
 
-      // Gift card fully covers the order — no PayPal order (PayPal
-      // refuses a zero-amount order). Create + burn + mark paid, same
-      // as the Stripe full-coverage path.
+      // Credits fully cover the order — no PayPal order (PayPal refuses a
+      // zero-amount order). Create + burn + mark paid, same as the Stripe
+      // full-coverage path. No provider charge → payment_provider stays
+      // null (there is nothing a provider could refund).
       if (amountDue === 0) {
         var paidOrder = await order.createFromCart({
           cart_id:             quote.cart_id,
@@ -1446,6 +1623,7 @@ function create(deps) {
           shipping_minor:      quote.totals.shipping_minor,
           grand_total_minor:   quote.totals.grand_total_minor,
           payment_intent_id:   null,
+          payment_provider:    null,
           ship_to:             input.ship_to,
           customer_email_hash: emailHash,
           lines:               ppLines,
@@ -1455,11 +1633,20 @@ function create(deps) {
         // so a redeem failure is captured and reconciled, never allowed to
         // strand the cart un-converted.
         await _settleCreditPostCreate("giftcard", paidOrder.id, function () {
-          return _redeemGiftCard(gc, paidOrder.id);
+          return gc ? _redeemGiftCard(gc, paidOrder.id) : null;
+        });
+        await _settleCreditPostCreate("loyalty", paidOrder.id, function () {
+          return loy ? _redeemLoyalty(loy, ppLoyaltyCustomerId, paidOrder.id) : null;
         });
         await cart.setStatus(quote.cart_id, "converted");
-        var settled = await order.transition(paidOrder.id, "mark_paid", { reason: "gift_card:full" });
-        return { order: settled, paypal_order_id: null, status: "PAID_BY_GIFT_CARD", gift_card: { applied_minor: gc.applied_minor, amount_due_minor: 0 } };
+        var settled = await order.transition(paidOrder.id, "mark_paid", {
+          reason: loy && !gc ? "loyalty:full" : "gift_card:full",
+        });
+        return {
+          order: settled, paypal_order_id: null, status: "PAID_BY_GIFT_CARD",
+          gift_card: gc ? { applied_minor: gc.applied_minor, amount_due_minor: 0 } : null,
+          loyalty:   loy ? { points: loy.points, applied_minor: loy.applied_minor, amount_due_minor: 0 } : null,
+        };
       }
 
       var ppOrder = await paypal.createOrder({
@@ -1480,21 +1667,30 @@ function create(deps) {
         shipping_minor:      quote.totals.shipping_minor,
         grand_total_minor:   quote.totals.grand_total_minor,
         payment_intent_id:   ppOrder.id,   // the PayPal order id (opaque); links the webhook + capture
+        payment_provider:    "paypal",     // refund surfaces route the refund dial by this
         ship_to:             input.ship_to,
         customer_email_hash: emailHash,
         lines:               ppLines,
       });
       ppOrderCreated = true;
-      // Post-commit gift-card burn — captured, never stranding. The order row
-      // + the PayPal order already exist; a redeem throw must not bubble to
-      // the outer catch (which re-throws and would leave the cart active with
-      // an orphaned PayPal order). The buyer pays the credit-reduced PayPal
-      // amount; a failed debit is surfaced for reconciliation.
+      // Post-commit gift-card + loyalty burn — captured, never stranding.
+      // The order row + the PayPal order already exist; a redeem throw must
+      // not bubble to the outer catch (which re-throws and would leave the
+      // cart active with an orphaned PayPal order). The buyer pays the
+      // credit-reduced PayPal amount; a failed debit is surfaced for
+      // reconciliation.
       await _settleCreditPostCreate("giftcard", createdOrder.id, function () {
         return gc ? _redeemGiftCard(gc, createdOrder.id) : null;
       });
+      await _settleCreditPostCreate("loyalty", createdOrder.id, function () {
+        return loy ? _redeemLoyalty(loy, ppLoyaltyCustomerId, createdOrder.id) : null;
+      });
       await cart.setStatus(quote.cart_id, "converted");
-      return { order: createdOrder, paypal_order_id: ppOrder.id, status: ppOrder.status, gift_card: gc ? { applied_minor: gc.applied_minor, amount_due_minor: amountDue } : null };
+      return {
+        order: createdOrder, paypal_order_id: ppOrder.id, status: ppOrder.status,
+        gift_card: gc ? { applied_minor: gc.applied_minor, amount_due_minor: amountDue } : null,
+        loyalty:   loy ? { points: loy.points, applied_minor: loy.applied_minor, amount_due_minor: amountDue } : null,
+      };
       } catch (e) {
         // A throw BEFORE the order row commits (PayPal open failure,
         // gift-card error) releases the holds so PayPal can't strand stock.
@@ -1527,6 +1723,16 @@ function create(deps) {
       var completed = cap && (cap.status === "COMPLETED" ||
         (captureId && cap.purchase_units[0].payments.captures[0].status === "COMPLETED"));
       if (completed && o.status === "pending") {
+        // Persist the capture id on the order row — refunds dial
+        // /v2/payments/captures/<capture-id>/refund, NOT the PayPal order id
+        // stored in payment_intent_id. Best-effort (drop-silent — by
+        // design): the metadata stamp on the transition below remains the
+        // recoverable source, and a persistence refusal must never block
+        // settling a real payment.
+        if (captureId) {
+          try { await order.setPaypalCapture(o.id, captureId); }
+          catch (_e2) { /* drop-silent — recoverable from the transition metadata */ }
+        }
         await order.transition(o.id, "mark_paid", {
           reason:   "paypal:capture",
           metadata: { paypal_order_id: paypalOrderId, paypal_capture_id: captureId },
@@ -1554,6 +1760,24 @@ function create(deps) {
       if (!eventType || !Object.prototype.hasOwnProperty.call(PAYPAL_EVENT_MAP, eventType)) {
         return { handled: false, event_type: eventType || null };
       }
+
+      // Replay defense — atomically claim this verified event id BEFORE any
+      // transition or ledger write, same ordering as the Stripe handler.
+      // Load-bearing for the refund mirror below: recordPartialRefund is an
+      // append (not state-idempotent), so a re-delivered partial REFUNDED
+      // event that raced past state checks would otherwise double-append.
+      // A store error fails CLOSED inside the nonceStore (not-fresh), so a
+      // wiped/unreachable store refuses rather than re-applies. No-op when
+      // the store isn't wired (the refund-id dedupe in the mirror still
+      // covers sequential re-delivery).
+      var replay = _stripeReplay();
+      if (replay && typeof event.id === "string" && event.id.length > 0) {
+        var fresh = await replay.checkAndInsert("paypal:" + event.id, Date.now() + PAYPAL_REPLAY_TTL_MS);
+        if (!fresh) {
+          return { handled: true, event_type: eventType, skipped: "replay", event_id: event.id };
+        }
+      }
+
       var fsmEvent = PAYPAL_EVENT_MAP[eventType];
       if (!fsmEvent) return { handled: false, event_type: eventType, reason: "no-state-change" };
       // The PayPal order id lives in the capture resource's related ids.
@@ -1562,14 +1786,34 @@ function create(deps) {
       if (!ppOrderId) return { handled: false, event_type: eventType, reason: "no-order-id" };
       var o = await order.byPaymentIntent(ppOrderId);
       if (!o) return { handled: false, event_type: eventType, reason: "order-not-found" };
-      var alreadyAdvanced = (
-        (fsmEvent === "mark_paid" && o.status !== "pending") ||
-        (fsmEvent === "refund"    && o.status === "refunded")
-      );
-      if (alreadyAdvanced) return { handled: true, event_type: eventType, order: o, skipped: "already-advanced" };
+
+      // Refund events are AMOUNT-AWARE — see _mirrorPaypalRefund: a partial
+      // dashboard refund appends a partial ledger row; only a
+      // balance-clearing slice drives the terminal refund edge.
+      if (eventType === "PAYMENT.CAPTURE.REFUNDED") {
+        return await _mirrorPaypalRefund(o, event, ppOrderId);
+      }
+
+      if (fsmEvent === "mark_paid" && o.status !== "pending") {
+        return { handled: true, event_type: eventType, order: o, skipped: "already-advanced" };
+      }
+      // The COMPLETED resource is the capture itself — persist its id so
+      // refunds can run against the capture without re-dialing PayPal. The
+      // write is best-effort here (the metadata stamp below remains the
+      // recoverable source): a refused write must never block settling a
+      // real payment.
+      var ppCaptureId = (eventType === "PAYMENT.CAPTURE.COMPLETED" && event.resource &&
+                         typeof event.resource.id === "string" && event.resource.id.length)
+        ? event.resource.id : null;
+      if (ppCaptureId) {
+        try { await order.setPaypalCapture(o.id, ppCaptureId); }
+        catch (_e) { /* drop-silent — by design: capture-id persistence must not block mark_paid; the transition metadata keeps it recoverable */ }
+      }
       var updated = await order.transition(o.id, fsmEvent, {
         reason:   "paypal:" + eventType,
-        metadata: { paypal_event_id: event.id, paypal_order_id: ppOrderId },
+        metadata: ppCaptureId
+          ? { paypal_event_id: event.id, paypal_order_id: ppOrderId, paypal_capture_id: ppCaptureId }
+          : { paypal_event_id: event.id, paypal_order_id: ppOrderId },
       });
       return { handled: true, event_type: eventType, order: updated };
     },

package/lib/order.js

@@ -443,19 +443,28 @@ function create(opts) {
       _nonNegInt(input.shipping_minor,    "shipping_minor");
       _nonNegInt(input.grand_total_minor, "grand_total_minor");
       _shipTo(input.ship_to);
+      // Which payment provider captured (or will capture) this order's
+      // charge — refund surfaces route the refund dial by this column.
+      // Optional: a fully-credited order (gift card / loyalty cover the
+      // whole total) carries no provider charge and stays NULL.
+      if (input.payment_provider != null &&
+          input.payment_provider !== "stripe" && input.payment_provider !== "paypal") {
+        throw new TypeError("order.createFromCart: payment_provider must be 'stripe', 'paypal', or null");
+      }
 
       var id = b.uuid.v7();
       var ts = _now();
       await query(
         "INSERT INTO orders (id, cart_id, customer_id, session_id, status, currency, " +
         "subtotal_minor, discount_minor, tax_minor, shipping_minor, grand_total_minor, " +
-        "payment_intent_id, ship_to_json, customer_email_hash, created_at, updated_at) " +
-        "VALUES (?1, ?2, ?3, ?4, 'pending', ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?14)",
+        "payment_intent_id, payment_provider, ship_to_json, customer_email_hash, created_at, updated_at) " +
+        "VALUES (?1, ?2, ?3, ?4, 'pending', ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15, ?15)",
         [
           id, input.cart_id, input.customer_id || null, input.session_id,
           input.currency, input.subtotal_minor, input.discount_minor,
           input.tax_minor, input.shipping_minor, input.grand_total_minor,
-          input.payment_intent_id || null, JSON.stringify(input.ship_to),
+          input.payment_intent_id || null, input.payment_provider || null,
+          JSON.stringify(input.ship_to),
           input.customer_email_hash || null, ts,
         ],
       );
@@ -518,6 +527,63 @@ function create(opts) {
       return await this.get(rows[0].id);
     },
 
+    // Persist the PayPal CAPTURE id on the order (and stamp the provider) —
+    // PayPal refunds run against the capture, not the order id stored in
+    // payment_intent_id. Called by the capture flow and the
+    // PAYMENT.CAPTURE.COMPLETED webhook backstop. Write-once: the first
+    // capture id recorded wins; a different id for an already-captured order
+    // is refused with a coded error (an order has exactly one capture in
+    // this flow — a mismatch means crossed wires, never something to
+    // overwrite silently). Re-recording the SAME id is an idempotent no-op.
+    setPaypalCapture: async function (orderId, captureId) {
+      _uuid(orderId, "order id");
+      if (typeof captureId !== "string" || !captureId.length || captureId.length > 64 ||
+          /[\u0000-\u001f\u007f]/.test(captureId)) {
+        throw new TypeError("order.setPaypalCapture: captureId must be a non-empty string <= 64 chars without control bytes");
+      }
+      var upd = await query(
+        "UPDATE orders SET paypal_capture_id = ?1, payment_provider = 'paypal' " +
+        "WHERE id = ?2 AND (paypal_capture_id IS NULL OR paypal_capture_id = ?1)",
+        [captureId, orderId],
+      );
+      if (Number(upd.rowCount || 0) > 0) return true;
+      var row = (await query("SELECT id, paypal_capture_id FROM orders WHERE id = ?1", [orderId])).rows[0];
+      if (!row) throw new TypeError("order.setPaypalCapture: order " + orderId + " not found");
+      var err = new Error("order.setPaypalCapture: order " + orderId + " already carries capture " +
+                          row.paypal_capture_id + " — refusing to overwrite with " + captureId);
+      err.code = "PAYPAL_CAPTURE_MISMATCH";
+      throw err;
+    },
+
+    // Resolve the PayPal capture id for an order: the persisted column when
+    // present, else recovered from the order's transition metadata (the
+    // capture flow stamps `paypal_capture_id` on the mark_paid transition —
+    // the only place pre-existing orders recorded it) and healed back onto
+    // the column so the scan runs at most once per order. Returns the
+    // capture id string or null (a Stripe / uncaptured order). Callers with
+    // a PayPal handle may fall back to a remote getOrder read when this
+    // local resolution returns null.
+    paypalCaptureId: async function (orderId) {
+      _uuid(orderId, "order id");
+      var row = (await query("SELECT paypal_capture_id FROM orders WHERE id = ?1", [orderId])).rows[0];
+      if (!row) return null;
+      if (row.paypal_capture_id) return row.paypal_capture_id;
+      var transitions = (await query(
+        "SELECT metadata_json FROM order_transitions WHERE order_id = ?1 ORDER BY occurred_at ASC",
+        [orderId],
+      )).rows;
+      for (var i = 0; i < transitions.length; i += 1) {
+        var meta;
+        try { meta = JSON.parse(transitions[i].metadata_json || "{}"); }
+        catch (_e) { meta = {}; }
+        if (meta && typeof meta.paypal_capture_id === "string" && meta.paypal_capture_id.length) {
+          await this.setPaypalCapture(orderId, meta.paypal_capture_id);
+          return meta.paypal_capture_id;
+        }
+      }
+      return null;
+    },
+
     // Fire a transition. Replays the FSM from the current state +
     // history, dispatches the event, and persists the new state on
     // the orders row + appends an order_transitions row.

package/lib/payment.js

@@ -784,6 +784,32 @@ function _minorToDecimalString(minor, currency) {
   return (neg ? "-" : "") + s.slice(0, s.length - dec) + "." + s.slice(s.length - dec);
 }
 
+// Inverse of _minorToDecimalString: parse a PayPal decimal amount string
+// (e.g. webhook `resource.amount.value`) into exact integer minor units,
+// using the same zero-decimal currency table. STRICT — money parsed off an
+// inbound webhook decides refund accounting, so a malformed shape throws a
+// TypeError rather than guessing (the caller maps that to a 5xx so the
+// processor re-delivers; a guessed amount would silently mis-credit). Pure
+// digit-string arithmetic — the value never passes through a float.
+function _decimalToMinor(value, currency) {
+  if (typeof currency !== "string" || !/^[A-Z]{3}$/.test(currency)) {
+    throw new TypeError("payment: decimal amount currency must be a 3-letter uppercase ISO 4217 code");
+  }
+  if (typeof value !== "string" || !/^\d{1,15}(\.\d{1,2})?$/.test(value)) {
+    throw new TypeError("payment: decimal amount must be a plain non-negative decimal string (got " + JSON.stringify(value) + ")");
+  }
+  var dec   = PAYPAL_ZERO_DECIMAL[currency] ? 0 : 2;
+  var parts = value.split(".");
+  var frac  = parts[1] || "";
+  if (frac.length > dec) {
+    // More fractional digits than the currency carries (e.g. "100.50" JPY)
+    // is a garbled amount, not a roundable one — refuse, never round money.
+    throw new TypeError("payment: decimal amount " + JSON.stringify(value) + " has more fractional digits than " + currency + " allows");
+  }
+  while (frac.length < dec) frac += "0";
+  return parseInt(parts[0] + frac, 10);
+}
+
 function _headerCI(headers, name) {
   if (!headers) return undefined;
   if (headers[name] != null) return headers[name];
@@ -833,7 +859,13 @@ async function _paypalToken(opts, state) {
   return state.token;
 }
 
-async function _paypalCall(opts, state, method, path, bodyObj, requestId) {
+// `breaker` selects which circuit the dial rides — every payment call rides
+// the adapter's main `opts._breaker`; the webhook-verification dial rides its
+// own (see verifyWebhook) so attacker-shaped verification traffic can't trip
+// the circuit live checkouts depend on. The token exchange inside always
+// rides the main breaker: its failures are credential/PayPal-health signals,
+// not attacker-controllable per-request outcomes.
+async function _paypalCall(opts, state, method, path, bodyObj, requestId, breaker) {
   var token = await _paypalToken(opts, state);
   var headers = {
     "authorization": "Bearer " + token,
@@ -855,7 +887,7 @@ async function _paypalCall(opts, state, method, path, bodyObj, requestId) {
   // same id rides every retry attempt within one call). A keyless write
   // rides the breaker but not the retry.
   var idempotent = method === "GET" || !!requestId;
-  var json = await _dial(opts._breaker, idempotent, async function () {
+  var json = await _dial(breaker === undefined ? opts._breaker : breaker, idempotent, async function () {
     var res = await httpClient.request({
       method:       method,
       url:          _paypalApiBase(opts) + path,
@@ -898,6 +930,17 @@ function paypal(opts) {
   if (opts._breaker === undefined) {
     opts._breaker = opts.breaker === false ? null : _makeBreaker("psp-paypal");
   }
+  // SEPARATE breaker for the webhook-verification dial. The verify call's
+  // failure rate is attacker-influenceable: any header-complete spam POST to
+  // the (necessarily unauthenticated) webhook route triggers a
+  // verify-webhook-signature dial whose 4xx counts as a breaker failure —
+  // five consecutive spam posts would otherwise open the SAME circuit live
+  // checkout's createOrder/captureOrder ride and fast-fail real payments for
+  // the cooldown window. Verification failures say nothing about PayPal's
+  // health as a payments peer, so they account against their own circuit.
+  if (opts._verifyBreaker === undefined) {
+    opts._verifyBreaker = opts.breaker === false ? null : _makeBreaker("psp-paypal-verify");
+  }
 
   var state = {
     query:          opts.query || null,
@@ -923,8 +966,11 @@ function paypal(opts) {
     name: "paypal",
 
     // The per-adapter circuit breaker (or null when disabled). Same
-    // operator-dashboard surface as the Stripe adapter's.
-    breaker: opts._breaker,
+    // operator-dashboard surface as the Stripe adapter's. `verifyBreaker`
+    // is the webhook-verification dial's own circuit — kept separate so
+    // spam against the webhook route can't open the payment circuit.
+    breaker:       opts._breaker,
+    verifyBreaker: opts._verifyBreaker,
 
     // Create an Orders-v2 order (intent CAPTURE). The returned `id` is the
     // PayPal order id the buyer approves; `captureOrder` finalizes it.
@@ -1020,7 +1066,10 @@ function paypal(opts) {
         webhook_event:     event,
       };
       var res;
-      try { res = await _paypalCall(opts, state, "POST", "/v1/notifications/verify-webhook-signature", verifyBody, null); }
+      // Rides the verify-only breaker (opts._verifyBreaker), never the main
+      // payment circuit — see the factory comment: verification traffic is
+      // attacker-shaped and must not be able to fast-fail live checkouts.
+      try { res = await _paypalCall(opts, state, "POST", "/v1/notifications/verify-webhook-signature", verifyBody, null, opts._verifyBreaker); }
       catch (e) { return { ok: false, reason: "verify-call-failed", error: e && e.message }; }
       if (res && res.verification_status === "SUCCESS") return { ok: true, event: event };
       return { ok: false, reason: "verification-status-" + ((res && res.verification_status) || "unknown") };
@@ -1036,14 +1085,40 @@ function create(opts) {
   throw new TypeError("payment.create: unknown adapter " + JSON.stringify(opts.adapter) + " — 'stripe' and 'paypal' are supported");
 }
 
+// Boot-time PayPal configuration lint, called by the server entry point so
+// an incomplete env surfaces in the boot log instead of as a silent feature
+// gap. Returns an array of operator-actionable warning strings (empty when
+// nothing is wrong). Pure read of the supplied env map — never throws, never
+// changes behavior: webhook verification stays MANDATORY and fails closed
+// whether or not the operator saw the warning.
+function paypalConfigWarnings(env) {
+  env = env && typeof env === "object" ? env : {};
+  var warnings = [];
+  if (env.PAYPAL_CLIENT_ID && env.PAYPAL_SECRET && !env.PAYPAL_WEBHOOK_ID) {
+    warnings.push(
+      "PAYPAL_WEBHOOK_ID is not set: PayPal checkout is configured, but every " +
+      "/api/webhooks/paypal delivery will be refused (verification fails closed " +
+      "without the webhook id), so out-of-band captures and refunds will not " +
+      "reach the order ledger. Set PAYPAL_WEBHOOK_ID to the webhook id from the " +
+      "PayPal developer dashboard.");
+  }
+  return warnings;
+}
+
 module.exports = {
   create:                    create,
   stripe:                    stripe,
   paypal:                    paypal,
+  paypalConfigWarnings:      paypalConfigWarnings,
   STRIPE_WEBHOOK_TOLERANCE:  STRIPE_WEBHOOK_TOLERANCE,
   IDEMPOTENCY_TTL_MS:        IDEMPOTENCY_TTL_MS,
   // Exposed for tests + Worker to share form-encoding shape.
   _formEncode:               _formEncode,
   _verifyWebhook:            _verifyWebhook,
   _canonicalHash:            _canonicalHash,
+  // Exposed for the checkout webhook mirror + admin refund normalization —
+  // exact decimal-string ↔ minor-unit conversion sharing one zero-decimal
+  // currency table.
+  _decimalToMinor:           _decimalToMinor,
+  _minorToDecimalString:     _minorToDecimalString,
 };

package/lib/refund-automation.js

@@ -342,6 +342,11 @@ function create(opts) {
   var refundPolicyHandle  = opts.refundPolicy        || null;
   var returnsHandle       = opts.returns             || null;
   var paymentHandle       = opts.payment             || null;
+  // PayPal adapter — PayPal-captured orders refund against their CAPTURE id
+  // through this handle (executeAutoRefund routes by the request's
+  // `provider`). Absent, PayPal-provider requests are refused with a clear
+  // error instead of dialing Stripe with a PayPal id.
+  var paypalHandle        = opts.paypal              || null;
   var riskProfileHandle   = opts.customerRiskProfile || null;
 
   // Per-factory monotonic clock. Two decisions written against the
@@ -664,6 +669,28 @@ function create(opts) {
       }
       paymentIntent = input.payment_intent;
     }
+    // Which provider captured the order's charge — routes the refund dial.
+    // 'stripe' (default — the original surface) refunds the payment_intent
+    // through the `payment` handle; 'paypal' refunds the CAPTURE
+    // (`paypal_capture_id`, never the PayPal order id) through the `paypal`
+    // handle, with the amount named in `currency`. Validated up front so a
+    // request can never reach the wrong provider's API.
+    var provider = input.provider == null ? "stripe" : input.provider;
+    if (provider !== "stripe" && provider !== "paypal") {
+      throw new TypeError("refundAutomation.executeAutoRefund: provider must be 'stripe' or 'paypal'");
+    }
+    var paypalCaptureId = null;
+    var paypalCurrency  = null;
+    if (provider === "paypal") {
+      if (typeof input.paypal_capture_id !== "string" || !input.paypal_capture_id.length) {
+        throw new TypeError("refundAutomation.executeAutoRefund: paypal_capture_id required when provider is 'paypal'");
+      }
+      if (typeof input.currency !== "string" || !CURRENCY_RE.test(input.currency)) {
+        throw new TypeError("refundAutomation.executeAutoRefund: currency (ISO 4217 alpha) required when provider is 'paypal'");
+      }
+      paypalCaptureId = input.paypal_capture_id;
+      paypalCurrency  = input.currency;
+    }
 
     var verdict = await evaluateForRefundRequest({
       order_id:             orderId,
@@ -685,20 +712,36 @@ function create(opts) {
       [id, orderId, customerId, verdict.applied_rule, amount, reason, ts],
     );
 
-    // Compose payment.refund when wired. The handle's exact shape
-    // mirrors the framework's payment primitive (`{ payment_intent,
-    // amount_minor, reason, metadata }`). Absent a handle the
-    // primitive still records the decision so the operator can
-    // drive the actual refund out-of-band.
+    // Compose the provider refund when the matching handle is wired,
+    // routed by `provider`. Absent the matching handle the primitive still
+    // records the decision so the operator can drive the actual refund
+    // out-of-band — EXCEPT a PayPal request with no PayPal handle, which is
+    // refused up front (falling through to the Stripe handle would dial
+    // Stripe with PayPal identifiers). The decision row above is already
+    // written either way, mirroring the decision-before-payment ordering.
     var paymentResult = null;
-    if (paymentHandle && typeof paymentHandle.refund === "function") {
+    if (provider === "paypal") {
+      if (paypalHandle && typeof paypalHandle.refund === "function") {
+        // Each auto-refund decision is its own refund — the decision id as
+        // the idempotency key keeps a retry of THIS decision deduplicated at
+        // PayPal (the adapter folds it into the PayPal-Request-Id) while two
+        // distinct decisions on the same capture stay distinct refunds.
+        paymentResult = await paypalHandle.refund({
+          capture_id:   paypalCaptureId,
+          amount_minor: amount,
+          currency:     paypalCurrency,
+        }, "auto-refund:" + id);
+      } else if (paymentHandle) {
+        throw new TypeError("refundAutomation.executeAutoRefund: provider is 'paypal' but no paypal handle is wired — refusing to refund PayPal identifiers through the Stripe handle");
+      }
+    } else if (paymentHandle && typeof paymentHandle.refund === "function") {
       var refundInput = {
         amount_minor: amount,
         reason:       reason,
         metadata:     { order_id: orderId, customer_id: customerId, applied_rule: verdict.applied_rule },
       };
       if (paymentIntent != null) refundInput.payment_intent = paymentIntent;
-      paymentResult = await paymentHandle.refund(refundInput);
+      paymentResult = await paymentHandle.refund(refundInput, "auto-refund:" + id);
     }
 
     return {

package/lib/security-middleware.js

@@ -77,6 +77,14 @@ var WEBHOOK_PATHS = [
 // could wedge the health signal.
 var HEALTH_PATH = "/_/health";
 
+// Per-client-IP budget on POST /api/webhooks/paypal (see the limiter in
+// mountRouteGuards). Generous against PayPal's real delivery cadence —
+// redelivery is ~25 attempts per event spread over days, so even a
+// post-downtime backlog flush of distinct events sits far under this —
+// while bounding how many verify-webhook-signature dials a spammer can
+// force per minute.
+var PAYPAL_WEBHOOK_BUDGET_PER_MINUTE = 120;
+
 // Worker→container internal endpoints — machine-to-machine POSTs over
 // the Cloudflare service binding (cron ticks + the InventoryLock DO's
 // low-stock event), each authenticated FIRST thing in its handler by a
@@ -745,6 +753,36 @@ function mountRouteGuards(r) {
       return clientKey(req) + "|" + (req.pathname || req.url || "/");
     },
   });
+  // --- PayPal webhook per-IP budget -----------------------------------
+  //
+  // The webhook paths are exempt from the global + tight limiters above
+  // (a processor's server-to-server POST is unthrottleable by a human
+  // budget), but /api/webhooks/paypal is uniquely expensive to probe:
+  // verification is a server-to-server dial to PayPal's
+  // verify-webhook-signature API, so every header-complete spam POST costs
+  // an outbound request. The adapter's verify dial rides its own circuit
+  // (never the payment circuit — lib/payment.js), so spam can't fast-fail
+  // checkouts; this budget bounds the outbound dial volume itself. Sized
+  // for PayPal's real delivery shape: legitimate redelivery after downtime
+  // is ~25 attempts per event spread over days, so even a backlog flush of
+  // many distinct events sits far under this per-minute ceiling — and a
+  // clipped delivery is never lost: the limiter answers 429, PayPal treats
+  // any non-2xx as retry-later and redelivers. Stripe's webhook keeps no
+  // budget — its verification is a local HMAC (no dial to amplify).
+  var PAYPAL_WEBHOOK_PATH = "/api/webhooks/paypal";
+  var paypalWebhookLimiter = b.middleware.rateLimit({
+    backend:   "memory",
+    algorithm: "fixed-window",
+    max:       PAYPAL_WEBHOOK_BUDGET_PER_MINUTE,
+    windowMs:  C.TIME.minutes(1),
+    keyFn:     clientKey,
+  });
+  r.use(function paypalWebhookRateGuard(req, res, next) {
+    var pathname = req.pathname || req.url || "/";
+    if (pathname !== PAYPAL_WEBHOOK_PATH) return next();
+    return paypalWebhookLimiter(req, res, next);
+  });
+
   r.use(function tightRateGuard(req, res, next) {
     var pathname = req.pathname || req.url || "/";
     // Never throttle the webhook or health paths.
@@ -781,6 +819,7 @@ module.exports = {
   CSP_HOSTS:            CSP_HOSTS,
   WEBHOOK_PATHS:        WEBHOOK_PATHS,
   HEALTH_PATH:          HEALTH_PATH,
+  PAYPAL_WEBHOOK_BUDGET_PER_MINUTE: PAYPAL_WEBHOOK_BUDGET_PER_MINUTE,
   TIGHT_PREFIXES:       TIGHT_PREFIXES,
   EDGE_POST_PATHS:      EDGE_POST_PATHS,
   PUBLIC_WELL_KNOWN_PATHS: PUBLIC_WELL_KNOWN_PATHS,

package/lib/storefront.js

@@ -14976,6 +14976,10 @@ function mount(router, deps) {
             selected_shipping_id: body.selected_shipping_id || defaultShipId || "std",
             customer:             { email: body.email, name: body.name },
             gift_card_code:       body.gift_card_code || undefined,
+            // Loyalty points the signed-in shopper asked to spend — same
+            // parse + credit handling as the card-form confirm, so both
+            // payment buttons honor identical credits.
+            loyalty_redeem_points: _parseRedeemPoints(body.loyalty_redeem_points),
             codes:                ppCodes.length ? ppCodes : undefined,
             idempotency_key:      "paypal:" + c.id + ":" + b.uuid.v7(),
             return_url:           body.return_url || undefined,
@@ -14991,7 +14995,10 @@ function mount(router, deps) {
           return _json(200, { id: created.paypal_order_id, order_id: created.order.id });
         } catch (e) {
           var ecode = (e && typeof e.code === "string") ? e.code : "";
-          var gcErr = ecode.indexOf("GIFTCARD_") === 0;
+          // Customer-correctable credit errors (bad gift-card code,
+          // insufficient loyalty balance, points on a guest cart) are 400s
+          // whose message the button surfaces inline.
+          var gcErr = ecode.indexOf("GIFTCARD_") === 0 || ecode.indexOf("LOYALTY_") === 0;
           // Out-of-stock is a 409 (conflict) carrying the friendly per-line
           // message so the PayPal button surfaces it; nothing was charged
           // and the mid-confirm holds were already released.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.4.27",
+  "version": "0.4.28",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {