@blamejs/blamejs-shop 0.4.26 → 0.4.28

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.26",
+  "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,
 };