@blamejs/blamejs-shop 0.4.27 → 0.4.29

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
@@ -453,35 +606,60 @@ function create(deps) {
     // card; a card worth less reduces the amount due, never below 0.
     var grand = quote.totals.grand_total_minor;
     var applied = card.balance_minor < grand ? card.balance_minor : grand;
+    // A zero balance applies nothing — treat it as no credit rather than
+    // attempting a zero-amount debit (an anomalous active card at 0 would
+    // otherwise turn into a validation throw deep in the redeem).
+    if (applied <= 0) return null;
     // `code_plain` is the bearer code the redeem decrement re-hashes;
     // it lives only in this in-memory resolution, never persisted.
     return { card: card, code_plain: code, applied_minor: applied, balance_minor: card.balance_minor };
   }
 
-  // Burn the resolved credit against the created order. The
-  // `giftcards.redeem` decrement is the authoritative double-spend
-  // guard — its `balance_minor >= ?` SQL predicate refuses a second
-  // spend that would overdraw, and a re-quote of the same card on a
-  // new order only ever debits the remaining balance. The ledger
-  // debit rides alongside as the operator-facing audit row, keyed on
-  // the order id. Called once per order, immediately after the order
-  // row exists, so a card is never burned for an order that failed to
-  // create.
-  //
-  // The ledger debit is BEST-EFFORT: the card row's balance (decremented by
-  // redeem above) is the authoritative spendable balance, and the ledger is
-  // the audit trail. A ledger write failure (e.g. an unmigrated ledger table,
-  // or a ledger view that lags the card row) must not throw out of the
-  // post-create redeem path and strand the already-created order + its live
-  // PaymentIntent. The card-row debit already happened; the ledger row is
-  // reconcilable from the redemption record. Same posture the admin issue
-  // route takes when seeding the opening credit.
-  async function _redeemGiftCard(resolved, orderId) {
-    var redemption = await giftcards.redeem({
+  // Debit the resolved gift-card credit — the authoritative double-spend
+  // gate. Runs BEFORE the order (and any PaymentIntent / PayPal order)
+  // exists: two checkouts presenting the same card race the
+  // `balance_minor >= ?` SQL predicate HERE, while nothing has been
+  // charged or created, so the loser's coded GIFTCARD_INSUFFICIENT_BALANCE
+  // propagates into a clean rollback (holds + claim released) and a
+  // re-quote — never a second paid order against an already-spent card.
+  // The redemption row is written with a NULL order id and attached to the
+  // order by _settleGiftCardPostCreate once the order row exists; a
+  // checkout that dies between debit and order creation reverses the debit
+  // via giftcards.reverseRedemptionById in the rollback path.
+  async function _debitGiftCard(resolved) {
+    return giftcards.redeem({
       code:         resolved.code_plain,
-      order_id:     orderId,
+      order_id:     null,
       amount_minor: resolved.applied_minor,
     });
+  }
+
+  // Attach a pre-charge gift-card debit to the order it paid for and write
+  // the operator-facing ledger audit row. The order link is what the
+  // refund/cancel reversers key on (reverseRedemption /
+  // reverseRedemptionProRata select by order_id), so a link failure is
+  // surfaced LOUDLY to the audit sink for reconciliation — but neither the
+  // link nor the ledger row may throw out of the post-create path: the
+  // order and its live charge already exist, the card debit already
+  // landed, and both writes are reconcilable from the redemption record.
+  async function _settleGiftCardPostCreate(resolved, redemption, orderId) {
+    try {
+      var linked = await giftcards.linkRedemptionToOrder(redemption.redemption_id, orderId);
+      if (!linked) throw new Error("redemption " + redemption.redemption_id + " did not accept the order link");
+    } catch (linkErr) {
+      try {
+        b.audit.safeEmit({
+          action:   "checkout.giftcard.order_link.error",
+          outcome:  "failure",
+          metadata: {
+            gift_card_id:  resolved.card.id,
+            redemption_id: redemption.redemption_id,
+            order_id:      orderId,
+            message:       (linkErr && linkErr.message) || String(linkErr),
+          },
+        });
+      } catch (_auditErr) { /* drop-silent — the redemption record is the durable trail */ }
+    }
     if (giftCardLedger) {
       try {
         await giftCardLedger.debit({
@@ -506,32 +684,51 @@ function create(deps) {
         } catch (_auditErr) { /* drop-silent — the redemption record is the durable trail */ }
       }
     }
-    return redemption;
   }
 
-  // Run a post-create credit redemption (gift-card / loyalty burn) so a
-  // failure can NEVER strand the already-created order + its live
-  // PaymentIntent. The order row and the PaymentIntent exist by the time
-  // this runs, and the buyer will pay the credit-reduced amount — so a
-  // throw out of the redeem (a card that raced to zero, a transient DB
-  // error) must not bubble up and leave the cart un-converted with an
-  // orphaned charge. The failure is captured to the audit sink for operator
-  // reconciliation (the credit reduced the charge but the debit didn't
-  // land, so the operator settles the card / points by hand) and the flow
-  // continues. `fn` returns the redeem promise (or null when there's no
-  // credit of that kind to burn).
-  async function _settleCreditPostCreate(kind, orderId, fn) {
-    try {
-      return await fn();
-    } catch (e) {
+  // Reverse the pre-charge credit debits when a checkout dies BEFORE its
+  // order exists (PaymentIntent refused, PayPal open failed, order insert
+  // threw). The card/points were taken for an order that will now never
+  // be created, so the rollback paths call this before releasing holds and
+  // the cart claim. Both reversals are claim-guarded (exactly-once) and
+  // keyed on the debit row itself — no order id was ever attached. A
+  // reversal failure is audited, never thrown: the original checkout error
+  // is the actionable one, and the unreversed debit is reconcilable from
+  // the audit trail.
+  async function _reverseCreditDebits(rollbackCtx) {
+    if (!rollbackCtx) return;
+    if (rollbackCtx.giftCardDebit) {
       try {
-        b.audit.safeEmit({
-          action:   "checkout." + kind + ".redeem.error",
-          outcome:  "failure",
-          metadata: { order_id: orderId, message: (e && e.message) || String(e) },
-        });
-      } catch (_auditErr) { /* drop-silent — never let the audit write mask the original failure */ }
-      return null;
+        await giftcards.reverseRedemptionById(rollbackCtx.giftCardDebit.redemption.redemption_id);
+      } catch (revErr) {
+        try {
+          b.audit.safeEmit({
+            action:   "checkout.giftcard.rollback_reverse.error",
+            outcome:  "failure",
+            metadata: {
+              redemption_id: rollbackCtx.giftCardDebit.redemption.redemption_id,
+              amount_minor:  rollbackCtx.giftCardDebit.resolved.applied_minor,
+              message:       (revErr && revErr.message) || String(revErr),
+            },
+          });
+        } catch (_auditErr) { /* drop-silent — the original checkout error is the actionable one */ }
+      }
+    }
+    if (rollbackCtx.loyaltyDebit) {
+      try {
+        await loyalty.reverseRedemptionById(rollbackCtx.loyaltyDebit.redemption.tx_id);
+      } catch (revErr) {
+        try {
+          b.audit.safeEmit({
+            action:   "checkout.loyalty.rollback_reverse.error",
+            outcome:  "failure",
+            metadata: {
+              tx_id:   rollbackCtx.loyaltyDebit.redemption.tx_id,
+              message: (revErr && revErr.message) || String(revErr),
+            },
+          });
+        } catch (_auditErr) { /* drop-silent — the original checkout error is the actionable one */ }
+      }
     }
   }
 
@@ -595,45 +792,127 @@ function create(deps) {
     return { points: spentPoints, applied_minor: appliedMinor };
   }
 
-  // Burn the resolved loyalty credit against the created order. The
-  // `loyalty.redeem` decrement is the authoritative double-spend guard
-  // (its `balance_points >= ?` SQL predicate refuses an overdraw), and
-  // the `order_id` link records the redemption against the order in the
-  // loyalty audit trail. Called once per order, after the order row
-  // exists, so points are never spent for an order that failed to
-  // create.
-  async function _redeemLoyalty(resolved, customerId, orderId) {
-    await loyalty.redeem({
+  // Debit the resolved loyalty credit — same pre-charge discipline as the
+  // gift-card debit: the `balance_points >= ?` predicate in loyalty.redeem
+  // is the cross-cart double-spend gate, so it must land before any money
+  // moves. The burn's ledger row is written with a NULL order id and
+  // attached by _settleLoyaltyPostCreate once the order exists; a checkout
+  // that dies in between reverses via loyalty.reverseRedemptionById in the
+  // rollback path.
+  async function _debitLoyalty(resolved, customerId) {
+    return loyalty.redeem({
       customer_id: customerId,
       points:      resolved.points,
-      order_id:    orderId,
-      notes:       "checkout-credit:" + orderId,
+      order_id:    null,
+      notes:       "checkout-credit",
     });
   }
 
-  // Record each applied auto-discount rule against a committed order
-  // so the engine's redemption counter + event log reflect the use.
-  // Best-effort / drop-silent: the customer has already been charged
-  // (or the order is otherwise placed) by the time this runs, so a
-  // recording failure must NEVER fail or reverse the order. Each
-  // record is isolated in its own try/catch so one bad row can't stop
-  // the rest. No-op when the engine isn't wired or nothing applied.
-  async function _recordAutoDiscounts(quote, orderId, customerId) {
-    if (!autoDiscount || typeof autoDiscount.recordApplication !== "function") return;
+  // Attach a pre-charge loyalty burn to the order it tendered for. The
+  // order link is what restoreRedemption keys on for refund restores, so a
+  // link failure is audited loudly — but never thrown: the order and its
+  // live charge already exist and the burn is reconcilable from the
+  // ledger row.
+  async function _settleLoyaltyPostCreate(redemption, orderId) {
+    try {
+      var linked = await loyalty.linkRedemptionToOrder(redemption.tx_id, orderId);
+      if (!linked) throw new Error("loyalty tx " + redemption.tx_id + " did not accept the order link");
+    } catch (linkErr) {
+      try {
+        b.audit.safeEmit({
+          action:   "checkout.loyalty.order_link.error",
+          outcome:  "failure",
+          metadata: {
+            tx_id:    redemption.tx_id,
+            order_id: orderId,
+            message:  (linkErr && linkErr.message) || String(linkErr),
+          },
+        });
+      } catch (_auditErr) { /* drop-silent — the burn row is the durable trail */ }
+    }
+  }
+
+  // Reserve each applied auto-discount rule's redemption BEFORE any money
+  // moves — a capped rule is a finite resource, so checkout claims it
+  // pre-charge under the same reserve-then-settle discipline inventory
+  // holds follow. A refused claim (cap exhausted, or lost to a concurrent
+  // order — the bypass that let a single-use code apply to every racing
+  // checkout) FAILS CLOSED with a coded error: the buyer re-quotes and
+  // sees the true price, never a silently-different charge. Claims are
+  // stashed on the rollback holder so a later pre-order throw releases
+  // them; claim-ref reuse makes a same-checkout retry idempotent.
+  async function _claimAutoDiscounts(quote, customerId, claimRef, rollbackHolder) {
+    if (!autoDiscount || typeof autoDiscount.claimRedemption !== "function") return;
+    var applied = quote && Array.isArray(quote.auto_discounts) ? quote.auto_discounts : [];
+    for (var i = 0; i < applied.length; i += 1) {
+      var a = applied[i];
+      if (!a || !a.rule_slug) continue;
+      var claim = await autoDiscount.claimRedemption({
+        rule_slug:     a.rule_slug,
+        claim_ref:     claimRef,
+        savings_minor: a.savings_minor,
+        customer_id:   customerId || undefined,
+      });
+      if (!claim.claimed) {
+        var gone = new Error("checkout: the " + JSON.stringify(a.rule_slug) +
+                             " discount is no longer available (" + claim.reason + ")");
+        gone.code = "AUTO_DISCOUNT_EXHAUSTED";
+        throw gone;
+      }
+      if (rollbackHolder) {
+        if (!rollbackHolder.autoDiscountClaims) rollbackHolder.autoDiscountClaims = [];
+        rollbackHolder.autoDiscountClaims.push({ rule_slug: a.rule_slug, claim_ref: claimRef });
+      }
+    }
+  }
+
+  // Re-key the pre-charge claims to the order that now exists, so the
+  // redemption rows the metrics/admin surfaces read carry the real order
+  // id. POST-COMMIT best-effort with a loud audit — the order and its
+  // charge already exist; the claim row itself (and the cap it reserved)
+  // landed pre-charge and is correct regardless.
+  async function _linkAutoDiscounts(quote, claimRef, orderId) {
+    if (!autoDiscount || typeof autoDiscount.linkClaimToOrder !== "function") return;
     var applied = quote && Array.isArray(quote.auto_discounts) ? quote.auto_discounts : [];
     for (var i = 0; i < applied.length; i += 1) {
       var a = applied[i];
       if (!a || !a.rule_slug) continue;
       try {
-        await autoDiscount.recordApplication({
-          rule_slug:     a.rule_slug,
-          order_id:      orderId,
-          savings_minor: a.savings_minor,
-          customer_id:   customerId || undefined,
+        await autoDiscount.linkClaimToOrder({
+          rule_slug: a.rule_slug,
+          claim_ref: claimRef,
+          order_id:  orderId,
         });
-      } catch (_e) {
-        // drop-silent — by design: the order is already placed; a
-        // failed redemption record must not surface to the buyer.
+      } catch (linkErr) {
+        try {
+          b.audit.safeEmit({
+            action:   "checkout.autodiscount.order_link.error",
+            outcome:  "failure",
+            metadata: { rule_slug: a.rule_slug, order_id: orderId, message: (linkErr && linkErr.message) || String(linkErr) },
+          });
+        } catch (_auditErr) { /* drop-silent — the claim row is the durable trail */ }
+      }
+    }
+  }
+
+  // Release pre-charge discount claims when the checkout dies before its
+  // order exists — the reservation goes back to the cap. Audited, never
+  // thrown: the original checkout error is the actionable one.
+  async function _releaseAutoDiscountClaims(rollbackHolder) {
+    if (!rollbackHolder || !rollbackHolder.autoDiscountClaims) return;
+    if (!autoDiscount || typeof autoDiscount.releaseClaim !== "function") return;
+    for (var i = 0; i < rollbackHolder.autoDiscountClaims.length; i += 1) {
+      var cl = rollbackHolder.autoDiscountClaims[i];
+      try {
+        await autoDiscount.releaseClaim({ rule_slug: cl.rule_slug, claim_ref: cl.claim_ref });
+      } catch (relErr) {
+        try {
+          b.audit.safeEmit({
+            action:   "checkout.autodiscount.claim_release.error",
+            outcome:  "failure",
+            metadata: { rule_slug: cl.rule_slug, claim_ref: cl.claim_ref, message: (relErr && relErr.message) || String(relErr) },
+          });
+        } catch (_auditErr) { /* drop-silent — the original checkout error is the actionable one */ }
       }
     }
   }
@@ -1002,6 +1281,12 @@ function create(deps) {
         // retry on the same cart. Both releases are atomic + self-targeting,
         // so neither can disturb a genuinely completed checkout.
         if (!rollbackCtx.orderCreated) {
+          // Reverse any pre-charge credit debits and discount claims first
+          // — the card/points/caps were taken for an order that will now
+          // never exist (both helpers are claim-guarded, audited, and
+          // never throw).
+          await _reverseCreditDebits(rollbackCtx);
+          await _releaseAutoDiscountClaims(rollbackCtx);
           if (rollbackCtx.stockHolds) {
             try { await _releaseStockHolds(rollbackCtx.stockHolds); }
             catch (_holdErr) { /* drop-silent — claim release below + original error are the actionable parts */ }
@@ -1060,6 +1345,32 @@ function create(deps) {
       }
       var amountDue = afterGiftCard - (loy ? loy.applied_minor : 0);
 
+      // Reserve the applied auto-discount redemptions FIRST (cheapest
+      // claim, fails closed on an exhausted cap with a clean re-quote),
+      // then the credit debits — all inside the rollback-protected region.
+      await _claimAutoDiscounts(quote, loyaltyCustomerId, idempotencyKey, rollbackCtx);
+
+      // Authoritative credit debits — PRE-charge, inside the rollback-
+      // protected region (rollbackCtx.orderCreated is still false). The SQL
+      // balance gates in giftcards.redeem / loyalty.redeem are the
+      // CROSS-CART double-spend guard: two checkouts presenting the same
+      // card (or the same points balance) race those predicates here,
+      // before any PaymentIntent or order exists, and the loser's coded
+      // error propagates into confirm()'s clean rollback (holds + claim
+      // released) for a re-quote. The debited rows carry no order id yet —
+      // they are linked post-create, or reversed by the rollback when a
+      // later step throws before the order exists.
+      var gcRedemption = null;
+      if (gc) {
+        gcRedemption = await _debitGiftCard(gc);
+        if (rollbackCtx) rollbackCtx.giftCardDebit = { resolved: gc, redemption: gcRedemption };
+      }
+      var loyRedemption = null;
+      if (loy) {
+        loyRedemption = await _debitLoyalty(loy, loyaltyCustomerId);
+        if (rollbackCtx) rollbackCtx.loyaltyDebit = { redemption: loyRedemption };
+      }
+
       var orderLines = quote.lines.map(function (l) {
         return {
           variant_id:        l.variant_id,
@@ -1095,6 +1406,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,
@@ -1102,20 +1414,17 @@ function create(deps) {
         // The pending order now owns the holds — a throw from here on must
         // NOT blanket-release them (see the conditional rollback in confirm).
         if (rollbackCtx) rollbackCtx.orderCreated = true;
-        // Same settlement posture as the PaymentIntent branch below: the
-        // order exists and the credits priced it, so a redeem failure here
-        // must not strand the cart un-converted — it is captured and
-        // reconciled, never propagated.
-        await _settleCreditPostCreate("giftcard", paidOrder.id, function () {
-          return gc ? _redeemGiftCard(gc, paidOrder.id) : null;
-        });
-        await _settleCreditPostCreate("loyalty", paidOrder.id, function () {
-          return loy ? _redeemLoyalty(loy, loyaltyCustomerId, paidOrder.id) : null;
-        });
-        // Best-effort: record the auto-discount redemptions against the
-        // placed order. Runs post-commit so a recording failure can't
-        // reverse an order that's already paid.
-        await _recordAutoDiscounts(quote, paidOrder.id, cartRow.customer_id || null);
+        // The credits were already debited pre-charge above (the debit IS
+        // the double-spend gate); what remains is attaching the debit rows
+        // to the order that now exists + the ledger audit row. Both are
+        // best-effort with loud audits — a failure here must not strand
+        // the cart un-converted.
+        if (gc) await _settleGiftCardPostCreate(gc, gcRedemption, paidOrder.id);
+        if (loy) await _settleLoyaltyPostCreate(loyRedemption, paidOrder.id);
+        // Re-key the pre-charge discount claims to the placed order. Runs
+        // post-commit so a link failure can't reverse an order that's
+        // already paid (the cap reservation itself landed pre-charge).
+        await _linkAutoDiscounts(quote, idempotencyKey, paidOrder.id);
         // Best-effort: record how the cart-level discount split across the
         // order lines (accounting + refund precision). Post-commit +
         // drop-silent — no impact on the already-settled order.
@@ -1162,6 +1471,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,
@@ -1172,25 +1482,21 @@ function create(deps) {
       // settles them now that the order exists.
       if (rollbackCtx) rollbackCtx.orderCreated = true;
 
-      // Burn the gift-card + loyalty credits against the created order.
-      // POST-COMMIT: the order row + its PaymentIntent already exist, so a
-      // redeem failure must NOT throw out of confirm — that would leave the
-      // cart un-converted (still `active`) while a live, charge-able
-      // PaymentIntent and order sit orphaned, and the conditional rollback
-      // above no longer fires (orderCreated is set). Each redeem is captured
-      // and reconciled instead (see _settleCreditPostCreate): the order is
-      // valid and the buyer pays the credit-reduced amount; a failed debit is
-      // surfaced for the operator to reconcile, never a stranded cart.
-      await _settleCreditPostCreate("giftcard", createdOrder.id, function () {
-        return gc ? _redeemGiftCard(gc, createdOrder.id) : null;
-      });
-      await _settleCreditPostCreate("loyalty", createdOrder.id, function () {
-        return loy ? _redeemLoyalty(loy, loyaltyCustomerId, createdOrder.id) : null;
-      });
-      // Best-effort: record the auto-discount redemptions against the
-      // placed order. Runs post-commit so a recording failure can't
-      // reverse or fail an order whose PaymentIntent already exists.
-      await _recordAutoDiscounts(quote, createdOrder.id, cartRow.customer_id || null);
+      // Attach the pre-charge credit debits to the created order. The
+      // authoritative card/points debits already landed BEFORE the
+      // PaymentIntent was opened (the debit is the double-spend gate); the
+      // remaining writes — the order link the refund reversers key on, and
+      // the gift-card ledger audit row — are POST-COMMIT best-effort with
+      // loud audits, because the order + its live PaymentIntent now exist
+      // and a throw from here would leave the cart un-converted with an
+      // orphaned charge (the conditional rollback above no longer fires —
+      // orderCreated is set).
+      if (gc) await _settleGiftCardPostCreate(gc, gcRedemption, createdOrder.id);
+      if (loy) await _settleLoyaltyPostCreate(loyRedemption, createdOrder.id);
+      // Re-key the pre-charge discount claims to the placed order. Runs
+      // post-commit so a link failure can't reverse or fail an order whose
+      // PaymentIntent already exists (the cap reservation landed pre-charge).
+      await _linkAutoDiscounts(quote, idempotencyKey, createdOrder.id);
       // Best-effort: record how the cart-level discount split across the
       // order lines (accounting + refund precision). Post-commit +
       // drop-silent — the PaymentIntent already exists; this never
@@ -1358,6 +1664,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).
@@ -1420,20 +1733,56 @@ function create(deps) {
       // approves is reaped by the stale-pending reaper (no PayPal-side
       // cancel needed — the capture path guards on local status).
       var ppOrderCreated = false;
+      var ppRollback = {};
       try {
       // 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);
+
+      // Reserve the applied auto-discount redemptions, then the credit
+      // debits — PRE-charge, same cross-cart double-spend discipline as
+      // the Stripe confirm (see _confirmAfterHolds): the SQL gates race
+      // here, before the PayPal order or the local order exist, and the
+      // loser's coded error rolls this checkout back cleanly. Linked
+      // post-create; reversed by the catch below when a later step throws
+      // before the order exists.
+      await _claimAutoDiscounts(quote, ppLoyaltyCustomerId, idempotencyKey, ppRollback);
+      var gcRedemption = null;
+      if (gc) {
+        gcRedemption = await _debitGiftCard(gc);
+        ppRollback.giftCardDebit = { resolved: gc, redemption: gcRedemption };
+      }
+      var loyRedemption = null;
+      if (loy) {
+        loyRedemption = await _debitLoyalty(loy, ppLoyaltyCustomerId);
+        ppRollback.loyaltyDebit = { redemption: loyRedemption };
+      }
+
       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,20 +1795,27 @@ 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,
         });
         ppOrderCreated = true;
-        // Same settlement posture as the Stripe branches: the order exists,
-        // 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);
-        });
+        // Same settlement posture as the Stripe branches: the authoritative
+        // debits + claims landed pre-charge; attach them to the order that
+        // now exists (best-effort, loudly audited — never stranding).
+        if (gc) await _settleGiftCardPostCreate(gc, gcRedemption, paidOrder.id);
+        if (loy) await _settleLoyaltyPostCreate(loyRedemption, paidOrder.id);
+        await _linkAutoDiscounts(quote, idempotencyKey, paidOrder.id);
         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,26 +1836,37 @@ 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.
-      await _settleCreditPostCreate("giftcard", createdOrder.id, function () {
-        return gc ? _redeemGiftCard(gc, createdOrder.id) : null;
-      });
+      // Attach the pre-charge debits + claims to the created order — the
+      // authoritative card/points debits and cap reservations landed before
+      // the PayPal order was opened; the order links + ledger row are
+      // post-commit best-effort with loud audits (a throw here would leave
+      // the cart active with an orphaned PayPal order).
+      if (gc) await _settleGiftCardPostCreate(gc, gcRedemption, createdOrder.id);
+      if (loy) await _settleLoyaltyPostCreate(loyRedemption, createdOrder.id);
+      await _linkAutoDiscounts(quote, idempotencyKey, createdOrder.id);
       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.
-        // After the order commits it owns the holds — don't blanket-release.
-        if (!ppOrderCreated) await _releaseStockHolds(ppHolds);
+        // gift-card error) reverses any pre-charge credit debits and
+        // discount claims and releases the holds so PayPal can't strand
+        // stock, burn credit, or leak a cap reservation. After the order
+        // commits it owns the holds — don't blanket-release.
+        if (!ppOrderCreated) {
+          await _reverseCreditDebits(ppRollback);
+          await _releaseAutoDiscountClaims(ppRollback);
+          await _releaseStockHolds(ppHolds);
+        }
         throw e;
       }
     },
@@ -1527,6 +1894,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 +1931,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 +1957,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 };
     },