@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/_internal/server/features/checkout/actions.js

@@ -16,7 +16,18 @@ import { roundShippingUp, } from "../../../shared/shipping/quote.js";
 import { unitOfWork, adminNotificationsRepository, siteSettingsRepository, userRepository, storeRepository, couponsRepository, claimedCouponsRepository, addressesRepository, productRepository, } from "../../../../repositories/index.js";
 import { isIntraStateSupply } from "../../../shared/fees/calculator.js";
 import { resolveStateKey, INDIA_STATES } from "../../../shared/fees/india-states.js";
-import { computePreOrderDepositAmount, lineTotalFor, sumGroupGst, unitPriceFor, } from "../../../shared/checkout/order-math.js";
+import { allocatePointsAcrossGroups, pointsBaseForGroup, computePreOrderDepositAmount, lineTotalFor, resolvePointsTender, sumGroupGst, unitPriceFor, } from "../../../shared/checkout/order-math.js";
+/*
+ * D46/D47 — points as a checkout TENDER.
+ *
+ * `storeAcceptsPoints` resolves decision 22's per-store opt-in (and the
+ * platform store's always-accepts, which is decided in code); the repository
+ * supplies the balance and owns the ledger write. The ARITHMETIC lives in
+ * `resolvePointsTender` above, beside every other money rule, so the tender
+ * cannot become a sixth disagreeing total (D37/D38/D40).
+ */
+import { storeAcceptsPoints } from "../../../shared/features/points/accepts.js";
+import { pointsRepository } from "../../../../features/points/repository/points.repository.js";
 import { COD_MAX_ORDER_VALUE_FALLBACK } from "../../../../features/admin/schemas/firestore.js";
 import { CHECKOUT_ERROR_CODES } from "../../../../errors/error-codes.js";
 import { failedCheckoutRepository } from "../../../../features/checkout/repository/failed-checkout.repository.js";
@@ -31,16 +42,21 @@ import { DEFAULT_STORE_SHIPPING_POLICY, quoteShipping, toStoreShippingPolicy, }
  */
 import { paymentCasesRepository } from "../../../../features/payment-cases/repository/payment-cases.repository.js";
 import { computeProtectionFees } from "../../../shared/features/shipping/protections.js";
+/* S5a — one payer, N destinations. Pure: the rates come in snapshotted, and
+ * an UNPRICED arrangement is refused rather than quoted at ₹0 (D44's lesson). */
+import { countDestinations, quoteSharedPurchase, } from "../../../shared/features/shipping/shared-purchase.js";
 import { resolveCouponCategorySlugs } from "../../../../features/promotions/actions/coupon-actions.js";
 import { assertCheckoutLane, assertLockedLinesStillValid, finalizeLockedLines, } from "./locked-lines.js";
 import { activeLane, defaultCheckoutItems, resolveCheckoutItems, laneOf, } from "../../../shared/checkout/lanes.js";
 import { computeCodHandlingFee, computeGiftWrapFee, computeShipmentProtectionFee, computeSaleProtectionFee, computeCheckoutFees, allocateCheckoutFees, } from "../../../shared/fees/calculator.js";
 import { getAdminDb, getAdminRealtimeDb, RTDB_PATHS, } from "../../../../providers/db-firebase/index.js";
+import { snapshotDeliveryAddress, } from "../../../shared/features/orders/delivery-snapshot.js";
 import { PRODUCT_COLLECTION, PRODUCT_CODES_SUBCOLLECTION } from "../../../../features/products/schemas/firestore.js";
 import { CART_COLLECTION } from "../../../../features/cart/schemas/index.js";
 // S-SBUNI-RULES 2026-05-13 — bundle cart-line stock fan-out helpers.
 import { getCartItemMemberIds, getExpandedDecrements, bucketCartItemsByStock, isMultiMemberLine, } from "./bundle-expansion.js";
 import { expandCartLineToOrderRows } from "./expand-order-items.js";
+import { freezePartsOnItems } from "./freeze-parts.js";
 import { OrderStatusValues, PaymentStatusValues, PaymentMethodValues, OutOfStockPolicyValues, } from "../../../../features/orders/schemas/index.js";
 import { getDefaultCurrency } from "../../../../core/index.js";
 import { getProviders } from "../../../../contracts/index.js";
@@ -53,10 +69,11 @@ import { verifyPaymentSignature as verifyRazorpayPaymentSignature } from "../../
 import { resolveKeys } from "../../../../core/integration-keys.js";
 import { paiseToRupees } from "../../../../core/money.js";
 import { CHECKOUT_DEFAULT_COMMISSIONS, CHECKOUT_DEFAULT_EMI_SETTINGS } from "../../../shared/features/checkout/config.js";
-import { checkEmiEligibility, computeBuyerEmiQuote, computeEmiSchedule } from "../../../shared/features/emi/schedule.js";
+import { emiTenderFor, resolveEmiChoice } from "../../../shared/features/emi/choice.js";
+import { amountDueNow, emiOrderFields, groupEmiGate, groupEmiQuote, groupEmiSchedule, } from "../../../shared/features/emi/group.js";
 import { formatShippingAddress } from "./data.js";
 import { enforceMaxPerUserForCart } from "./prize-bundle-gates.js";
-import { getListingRule, runSyncPreflight, assertPaymentMethodAllowed, } from "../../../shared/checkout/rules/index.js";
+import { getListingRule, runSyncPreflight, assertPaymentMethodAllowed, assertEmiOptInAllowed, } from "../../../shared/checkout/rules/index.js";
 // The `GroupCouponDiscountResult` type is deliberately NOT imported: every
 // call site here destructures the result inline, so naming the type would be
 // an unused import.
@@ -68,7 +85,7 @@ import { sendNotification } from "../../../../features/admin/actions/notificatio
 import { resolveDisplayedUpiId } from "./upi-resolution.js";
 import { resolveSupplierIdentity } from "./supplier-identity.js";
 import { PAYMENT_WINDOW_MS } from "../../../../features/orders/constants/payment-window.js";
-import { isCheckoutValueOtpVerified } from "../../../../features/checkout/actions/checkout-value-otp-actions.js";
+import { assertCheckoutValueOtp } from "./value-otp-gate.js";
 const AUDIT_LOG_FAIL_MSG = "checkout: audit log failed (non-critical)";
 /**
  * How long a `gatewayOrderClaims` holder owns the right to place an order
@@ -262,6 +279,10 @@ opts) {
             shippingPolicy: DEFAULT_STORE_SHIPPING_POLICY,
             shippingUnavailable: false,
             storeProtections: { shipping: false, sale: false },
+            // No store, so no seller to absorb a redemption.
+            acceptsPoints: false,
+            // No store, so nobody to pack N parcels.
+            sharedPurchaseRates: { allowSharedPurchase: false },
             // No store, so no seller registration — the caller falls back to the
             // platform's via resolveSupplierIdentity.
             storeTaxIdentity: undefined,
@@ -381,6 +402,13 @@ opts) {
             shipping: store?.supportsShippingProtection === true,
             sale: store?.supportsSaleProtection === true,
         },
+        acceptsPoints: storeAcceptsPoints(store, storeId),
+        // S5a — raw, so the caller can tell "not configured" from ₹0.
+        sharedPurchaseRates: {
+            allowSharedPurchase: store?.allowSharedPurchase === true,
+            sharedPurchaseHandlingFee: store?.sharedPurchaseHandlingFee,
+            sharedPurchaseExtraShippingPerDestination: store?.sharedPurchaseExtraShippingPerDestination,
+        },
         /*
          * The seller's own tax registration, returned from the store read this
          * function ALREADY does.
@@ -594,6 +622,112 @@ function dispatchOrderConfirmationEmails(emailsToSend) {
         return;
     Promise.all(emailsToSend.map((e) => sendOrderConfirmationEmail(e))).catch((err) => serverLogger.error("Order confirmation email error:", err));
 }
+/**
+ * The buyer's points balance, or **0** if it cannot be read.
+ *
+ * 🛑 Failing OPEN to zero is the safe direction and the only safe direction: a
+ * balance we could not read becomes "no discount applied", so the buyer is
+ * charged the full amount and their points are untouched. The inverse — guessing
+ * a balance — would reduce the charge against points that may not exist, which
+ * is the shape of the deleted D46 block (it debited points and reduced nothing;
+ * this is the same mistake with the signs swapped).
+ *
+ * A buyer who opted in and sees no discount can retry. There is no recoverable
+ * outcome on the other side.
+ */
+async function safePointsBalance(userId) {
+    try {
+        return await pointsRepository.getBalance(userId);
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        serverLogger.warn("[checkout] points balance unreadable — charging full amount", {
+            userId,
+            error: normalized.message,
+        });
+        return 0;
+    }
+}
+/**
+ * Debit the points an order was discounted by — the second half of the tender.
+ *
+ * 🛑 ONE implementation, called from BOTH order-creation paths. They are
+ * ~200-line twins that have already drifted once (add-on fees, Root Cause
+ * #65), and a money rule reachable by copy-paste gets copied (Root Cause #75).
+ *
+ * Runs AFTER the order exists and BEFORE the gateway is asked for anything.
+ * That ordering is the whole D46 fix: the deleted block ran after capture, so a
+ * redemption that succeeded took points from a buyer who had just paid full
+ * price while its own comment claimed "the balance intact".
+ *
+ * 🛑 A REFUSED REDEEM REVERTS THE DISCOUNT; it is never swallowed. `redeem`
+ * re-reads the balance inside its own transaction and refuses rather than going
+ * negative — so a refusal means the budget was wrong and the order is recording
+ * a discount nobody funded. Reverting is the only honest response: the buyer
+ * pays full price, which they can see and query, where an unfunded discount is
+ * a silent under-collection on every order that hits it.
+ *
+ * `orderId` is the natural idempotency key — this runs once per created order,
+ * and an order is created once.
+ */
+async function settlePointsTender(input) {
+    if (input.pointsApplied <= 0)
+        return;
+    try {
+        await pointsRepository.redeem({
+            userId: input.userId,
+            points: input.pointsApplied,
+            orderId: input.orderId,
+            description: `Points applied to order ${input.orderId}`,
+        });
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        serverLogger.error("[checkout] points redemption refused — reverting the discount", {
+            orderId: input.orderId,
+            userId: input.userId,
+            pointsApplied: input.pointsApplied,
+            error: normalized.message,
+        });
+        // Hand the budget back, so a later group in the same checkout is not
+        // charged for a spend that did not happen.
+        input.pointsBudget.remaining += input.pointsApplied;
+        await unitOfWork.orders
+            .update(input.orderId, { pointsApplied: undefined, amountDue: undefined })
+            .catch((e) => {
+            /*
+             * 🛑 The one genuinely bad outcome, so it is reported rather than
+             * logged: the order still says `amountDue`, the points were never
+             * taken, and the gateway is about to be asked for the discounted
+             * figure. A case names the amount and the order; `safeRead`'s silent
+             * degrade would be wrong here because nothing downstream can detect it.
+             */
+            const inner = normalizeError(e);
+            serverLogger.error("[checkout] points revert FAILED — order under-collects", {
+                orderId: input.orderId,
+                amountUnfunded: input.pointsApplied,
+                error: inner.message,
+            });
+            void paymentCasesRepository()
+                .openOrObserve({
+                kind: "amount_mismatch",
+                // The problem is this order's unfunded discount, so the subject is
+                // the order — one case however many times it is observed.
+                subjectId: input.orderId,
+                severity: "error",
+                entityType: "order",
+                entityId: input.orderId,
+                orderIds: [input.orderId],
+                title: "Order carries a points discount that was never funded",
+                detail: `Redemption of ${input.pointsApplied} points was refused and the ` +
+                    `revert also failed, so this order will be captured at its ` +
+                    `discounted amountDue with no matching ledger debit.`,
+                amountAtRisk: input.pointsApplied,
+            })
+                .catch(() => undefined);
+        });
+    }
+}
 /**
  * Places one order for one seller-group of the checkout cart — fee math
  * (COD deposit/handling, EMI schedule), coupon apportionment, order-doc
@@ -602,7 +736,7 @@ function dispatchOrderConfirmationEmails(emailsToSend) {
  * so the caller can accumulate the checkout-wide `total`.
  */
 async function createOrderForGroup(group, orderType, ctx) {
-    const { paymentMethod, emiTenureMonths, emiSettings, commissions, appliedCoupons, cartSubtotal, couponUsageAccumulator, uid, userName, userEmail, shippingAddress, notes, adminBypass, adminBypassBy, adminBatchId, orderIds, emailsToSend, outOfStockPolicy, droppedItems, buyerState, gstSettings, siteContactUpiVpa, storeAddons, platformFeeByStore, selectedShippingQuote, } = ctx;
+    const { paymentMethod, emiOptIn, emiTenureMonths, emiSettings, commissions, appliedCoupons, cartSubtotal, couponUsageAccumulator, uid, userName, userEmail, shippingAddress, deliverySnapshot, notes, adminBypass, adminBypassBy, adminBatchId, orderIds, emailsToSend, outOfStockPolicy, droppedItems, buyerState, gstSettings, siteContactUpiVpa, storeAddons, platformFeeByStore, selectedShippingQuote, useAllPoints, pointsBudget, } = ctx;
     const firstItem = group[0].item;
     const firstProduct = group[0].product;
     // Add-ons are this store's choice, not the cart's — see OrderGroupContext.
@@ -636,11 +770,24 @@ async function createOrderForGroup(group, orderType, ctx) {
     // A multi-member line expands into one row PER MEMBER sharing a groupSlug, so
     // each row carries its own HSN/GST and can be cancelled independently; the
     // receipt still collapses them under one header.
-    const orderItems = group.flatMap(({ item, product }) => {
+    const baseOrderItems = group.flatMap(({ item, product }) => {
         const lt = (product.listingType ?? "standard");
         const itemRule = getListingRule(lt);
         return expandCartLineToOrderRows(item, product, ctx.productById).map((baseLine) => itemRule.decorateOrderItem(baseLine, product));
     });
+    /*
+     * Part 14 — freeze the parts a composed listing was sold as containing.
+     *
+     * A separate pass because composition lives in `modelCompositions` keyed by
+     * the model's CATEGORY leaf, not on the product, so it needs a read — and
+     * `expandCartLineToOrderRows` is pure by design.
+     *
+     * 🛑 Usually free: it returns immediately unless some line's listing type
+     * has a composition at all, and then reads only the DISTINCT leaves,
+     * capped. It never throws — a parts list we could not read must not fail a
+     * payment (see the module header).
+     */
+    const orderItems = await freezePartsOnItems(baseOrderItems);
     const totalQuantity = group.reduce((sum, { item }) => sum + item.quantity, 0);
     /*
      * D44: the group's real goods value, so free-above-threshold can fire.
@@ -650,7 +797,7 @@ async function createOrderForGroup(group, orderType, ctx) {
      * grouped line the two differ.
      */
     const groupGoodsValue = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
-    const { shippingFee: resolvedShippingFee, storeOwnerId, storeEmiEnabled, storeState, storeProtections, storeTaxIdentity } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupGoodsValue });
+    const { shippingFee: resolvedShippingFee, storeOwnerId, storeEmiEnabled, storeState, storeProtections, storeTaxIdentity, acceptsPoints, sharedPurchaseRates } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupGoodsValue });
     /*
      * 🛑 The buyer's quote WINS over the seller's configured rate, and it is
      * re-rounded here rather than trusted as sent.
@@ -699,14 +846,30 @@ async function createOrderForGroup(group, orderType, ctx) {
      * simply did not exist yet. The split now sits immediately after
      * `orderTotal`, which is the only place every term is known.
      */
-    let emiSchedule;
-    if (paymentMethod === "emi" && emiTenureMonths) {
-        const eligibility = checkEmiEligibility(groupTotal, storeEmiEnabled, emiSettings);
-        if (!eligibility.eligible) {
-            throw new ValidationError(`EMI is not available for this order (${eligibility.reason}). Minimum order value per seller is ₹${emiSettings.minOrderValue}.`);
-        }
-        emiSchedule = computeEmiSchedule(groupTotal, emiTenureMonths, emiSettings);
+    /*
+     * 🛑 Keyed on `emiOptIn`, NOT on the tender. An EMI order's `paymentMethod`
+     * is now whatever the buyer picked to pay the token with — `online`,
+     * `upi_manual` or `cash` — so testing `paymentMethod === "emi"` here would
+     * build a schedule for nobody and every instalment plan would silently
+     * vanish into a full-price order.
+     */
+    const emiGroupInput = {
+        emiOptIn,
+        emiTenureMonths,
+        groupSubtotal: groupTotal,
+        sellerEmiEnabled: storeEmiEnabled,
+    };
+    /*
+     * 🛑 REFUSES on an ineligible EMI order rather than quietly dropping the
+     * plan. The preview deliberately does the opposite — see `groupEmiGate`'s
+     * docstring. Silently producing a full-price order from an EMI request is
+     * money the buyer did not agree to.
+     */
+    const emiGate = groupEmiGate(emiGroupInput, emiSettings);
+    if (emiOptIn && emiTenureMonths && !emiGate.applies) {
+        throw new ValidationError(`EMI is not available for this order (${emiGate.reason}). Minimum order value per seller is ₹${emiSettings.minOrderValue}.`);
     }
+    const emiSchedule = groupEmiSchedule(emiGroupInput, emiSettings) ?? undefined;
     // Handling fee charged to the buyer for choosing COD, on top of the order
     // total — not deducted from the deposit/remaining split above.
     const codHandlingFee = paymentMethod === "cod" ? computeCodHandlingFee(groupTotal, commissions) : 0;
@@ -818,6 +981,47 @@ async function createOrderForGroup(group, orderType, ctx) {
             groupCouponCodes.add(discount.code);
         }
     }
+    /*
+     * ── S5a: a shared purchase — one payer, N destinations ────────────────────
+     *
+     * Computed BEFORE `orderTotal` because it is a term in it. The rates come
+     * off the store document and are SNAPSHOTTED onto the order below: a
+     * coordinator commits against a quoted total, and re-reading a rate at
+     * settle would let a seller raise it afterwards. That is D61's rule, and the
+     * precedent is the refund path reading `finalSale` from the order snapshot
+     * for exactly this reason.
+     *
+     * 🛑 `countDestinations` counts DISTINCT addresses and collapses every line
+     * with no `destinationAddressId` into one bucket — the order's own address.
+     * Counting items instead would charge an ordinary three-item order for two
+     * extra legs it never asked for.
+     */
+    const sharedQuote = quoteSharedPurchase({
+        destinationCount: countDestinations(group.map(({ item }) => item)),
+        rates: sharedPurchaseRates,
+    });
+    /*
+     * 🛑 An UNPRICED arrangement is refused, not given away. The seller opted in
+     * without setting a rate, which is not consent to do the extra packing for
+     * free — and quoting ₹0 is exactly D44: `shippingUnavailable` carried a
+     * docstring saying "the caller MUST act on this rather than trusting
+     * `shippingFee: 0`", had zero consumers, and every `estimate`-mode store
+     * shipped free on every path as a result.
+     */
+    if (sharedQuote.unpriced) {
+        throw new ValidationError("This seller has not set a price for splitting an order across addresses. " +
+            "Send everything to one address, or contact the seller.");
+    }
+    /*
+     * A multi-destination order from a store that has NOT opted in. The quote
+     * prices; it does not authorise — so the refusal is here, where the buyer
+     * can be told something true and specific.
+     */
+    if (!sharedQuote.isShared &&
+        countDestinations(group.map(({ item }) => item)) > 1) {
+        throw new ValidationError("This seller ships one order to one address. Remove the extra delivery addresses, " +
+            "or order the items separately.");
+    }
     // The platform commission is now charged on EVERY payment method. It used to
     // be added only on the online-payment path, so COD / UPI-manual / cash / EMI
     // buyers silently never paid it.
@@ -848,7 +1052,7 @@ async function createOrderForGroup(group, orderType, ctx) {
      * compounds nine half-paisa errors instead of one, which is how a total
      * drifts from the sum of the lines shown beside it.
      */
-    roundRupees(Math.max(0, groupTotal - couponDiscount) + shippingFee + codHandlingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee + platformFee + platformFeeGst + (emiSchedule?.surchargeAmount ?? 0));
+    roundRupees(Math.max(0, groupTotal - couponDiscount) + shippingFee + codHandlingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee + platformFee + platformFeeGst + (emiSchedule?.surchargeAmount ?? 0) + sharedQuote.total);
     /*
      * ── D43: the COD deposit/remaining split, on the ORDER TOTAL ──────────────
      *
@@ -891,16 +1095,72 @@ async function createOrderForGroup(group, orderType, ctx) {
     // Deadline + displayed UPI apply only to methods with a buyer-uploaded
     // proof step — never cod (paid on delivery), online (paid before order
     // creation), or admin_bypass (already marked paid above).
+    /*
+     * 🛑 `PaymentMethodValues.EMI` was a third arm here and is gone on purpose,
+     * not by oversight. It is unreachable after `resolveEmiChoice` — an EMI
+     * order's tender is `online` / `upi_manual` / `cash` — and leaving it would
+     * assert that "EMI" is a way of paying, which is exactly the conflation 0f
+     * removed. An EMI buyer paying by bank transfer still gets the window,
+     * because their tender IS `upi_manual`; one paying online does not, because
+     * the token is captured before the order exists.
+     */
     const hasPaymentWindow = !adminBypass &&
         (paymentMethod === PaymentMethodValues.UPI_MANUAL ||
-            paymentMethod === PaymentMethodValues.CASH ||
-            paymentMethod === PaymentMethodValues.EMI);
+            paymentMethod === PaymentMethodValues.CASH);
     const paymentDeadline = hasPaymentWindow
         ? new Date(Date.now() + PAYMENT_WINDOW_MS)
         : undefined;
     const displayedUpiId = hasPaymentWindow
         ? await resolveDisplayedUpiId(firstItem.storeId, siteContactUpiVpa)
         : undefined;
+    /*
+     * ── POINTS TENDER (D46/D47) — a STAGE, after `orderTotal` is rounded ──────
+     *
+     * The deleted code redeemed points AFTER the orders existed and after the
+     * gateway had captured `orderTotal`, so a successful redemption took points
+     * from a buyer who had just paid full price — while its own comment claimed
+     * "the balance intact". This is the same feature done as a pipeline stage:
+     * `amountDue` is derived here, and `amountDue` is what the gateway captures
+     * and what the post-capture guard compares.
+     *
+     * 🛑 `useAllPoints` is the only client input and it is a BOOLEAN (decision
+     * 24). The amount comes from the live balance and the 50% cap; a
+     * client-supplied money figure is a client-supplied discount.
+     *
+     * 🛑 Per group, because the ACCEPTING store absorbs the redemption against
+     * its own payout (decision 3). A cart spanning an accepting and a
+     * non-accepting store must not pool the discount — so this reads
+     * `acceptsPoints`, which `resolveShippingCost` resolved from the store
+     * document it had already fetched.
+     *
+     * 🛑 `pointsBudget` is a SHARED MUTABLE REMAINDER, read once per checkout by
+     * the caller and decremented here — the same shape as
+     * `couponUsageAccumulator` and `platformFeeByStore`. Reading the balance
+     * per group would let two groups each spend the whole balance: `redeem`
+     * would then refuse the second one inside its transaction, leaving an order
+     * recorded at a discount that was never funded. One budget, drawn down in
+     * order, is what makes the sum of the groups equal what the buyer has.
+     */
+    const pointsOptedIn = useAllPoints === true;
+    const pointsAccepted = pointsOptedIn && acceptsPoints;
+    const { pointsApplied, amountDue } = resolvePointsTender({
+        orderTotal,
+        balance: pointsAccepted ? pointsBudget.remaining : 0,
+        accepted: pointsAccepted,
+        optedIn: pointsOptedIn,
+    });
+    if (pointsApplied > 0)
+        pointsBudget.remaining -= pointsApplied;
+    /*
+     * What is COLLECTED, composing both tenders that reduce it. On a plain order
+     * this equals `orderTotal`, so the field is omitted below and every
+     * `amountDue ?? totalPrice` reader is unaffected.
+     */
+    const amountDueOnOrder = amountDueNow({
+        orderTotal,
+        pointsApplied,
+        emiRemainingBalance: emiSchedule?.remainingBalance ?? 0,
+    });
     // Both creation paths call the SAME builder — two hand-written copies is the
     // create-vs-create axis of Root Cause #39, and these two functions have
     // already drifted once before (add-on fees, Root Cause #65).
@@ -914,6 +1174,39 @@ async function createOrderForGroup(group, orderType, ctx) {
         quantity: totalQuantity,
         unitPrice: unitPriceFor(firstItem, firstProduct),
         totalPrice: orderTotal,
+        /*
+         * D46/D47 — what the points paid for, and what is left to collect.
+         *
+         * 🛑 `totalPrice` stays the FULL order value and is not reduced. It is the
+         * value of the supply, it is what the GST breakdown above was computed on,
+         * and it is what `refundableBase` measures against — netting the points
+         * off it would silently shrink the refundable base and the taxable value
+         * at once. Points are a DISCOUNT settled against goods (decision 5), so
+         * they reduce the amount COLLECTED, not the amount supplied.
+         *
+         * 🛑 Both are written only when non-zero, so an order placed without
+         * points carries neither field and every reader's `amountDue ?? totalPrice`
+         * fallback resolves to the right number on the 100% of historical orders
+         * that predate this.
+         */
+        pointsApplied: pointsApplied > 0 ? pointsApplied : undefined,
+        /*
+         * 🛑 WHAT IS COLLECTED NOW, and on an EMI order that is the token — not
+         * the whole total.
+         *
+         * This was `pointsApplied > 0 ? amountDue : undefined`, so an EMI order
+         * carried no `amountDue` at all and every reader fell back to
+         * `order.total`. The buyer's manual-payment page therefore asked an EMI
+         * buyer to transfer the FULL order value up front and then showed them a
+         * schedule of monthly instalments: `emiTokenAmount` was computed, stored,
+         * and read by nothing (measured — zero readers across both repos).
+         *
+         * `amountDueNow` subtracts the deferred balance as well as the points, so
+         * the two tenders compose. Written only when it differs from the total, so
+         * every historical order keeps resolving through the same
+         * `amountDue ?? totalPrice` fallback its readers already use.
+         */
+        amountDue: amountDueOnOrder !== orderTotal ? amountDueOnOrder : undefined,
         currency: firstItem.currency ?? getDefaultCurrency(),
         storeId: firstItem.storeId || undefined,
         storeName: firstItem.storeName || undefined,
@@ -946,6 +1239,12 @@ async function createOrderForGroup(group, orderType, ctx) {
         displayedUpiId,
         adminBypassBy: adminBypassBy,
         shippingAddress,
+        /*
+         * 🛑 Spread BEFORE `placeOfSupply`, which now prefers the snapshot's
+         * state. Spreading after would let an absent snapshot overwrite a
+         * state the digital-cart fallback had already resolved.
+         */
+        ...(deliverySnapshot ?? {}),
         notes,
         shippingFee: shippingFee > 0 ? shippingFee : undefined,
         depositAmount: adminBypass ? undefined : depositAmount,
@@ -971,11 +1270,39 @@ async function createOrderForGroup(group, orderType, ctx) {
         shipmentProtectionFee: !adminBypass && shipmentProtectionFee > 0 ? shipmentProtectionFee : undefined,
         saleProtectionAddon: !adminBypass && saleProtectionFee > 0 ? true : undefined,
         saleProtectionFee: !adminBypass && saleProtectionFee > 0 ? saleProtectionFee : undefined,
+        /*
+         * S5a — the arrangement, snapshotted. Written only when it IS a shared
+         * purchase, so an ordinary order carries no field at all and every reader
+         * can test presence rather than compare a count to 1.
+         *
+         * 🛑 The FEES AS CHARGED, not the store's current rates. That is the whole
+         * point of a snapshot: an order refunded in six months must reverse what
+         * was collected, not what the seller charges by then.
+         */
+        sharedPurchase: sharedQuote.isShared
+            ? {
+                destinationCount: countDestinations(group.map(({ item }) => item)),
+                handlingFee: sharedQuote.handlingFee,
+                extraShippingFee: sharedQuote.extraShippingFee,
+            }
+            : undefined,
         taxableAmount: gstBreakdown?.taxableAmount,
         /* Exempt goods are a reportable nil-rated supply, kept OUT of
          * `taxableAmount` so the taxed base stays the base the tax was charged on,
          * and recorded here so the invoice's columns can reconcile. */
         exemptAmount: gstBreakdown?.exemptAmount || undefined,
+        /*
+         * Phase 7 — the place of supply, which is the INPUT the CGST/SGST-vs-IGST
+         * split above was computed from. Only the split's RESULT was recorded
+         * before, so an order could not state why it was taxed the way it was, and
+         * GSTR-1's mandatory place-of-supply column had nothing to read.
+         */
+        /*
+         * Part 14 — the snapshot's state is authoritative, because it is the
+         * field the invoice and GSTR-1 actually read. `buyerState` stays as
+         * the fallback for a digital cart, which has no delivery address.
+         */
+        placeOfSupply: deliverySnapshot?.deliveryState || buyerState || undefined,
         /* The supplier of record AS IT STANDS NOW. A tax invoice without the
          * supplier's GSTIN is not a tax invoice, and the invoice page cannot read
          * it from site settings — `gst` is in PRIVATE_SITE_FIELDS. See the schema.
@@ -1013,23 +1340,19 @@ async function createOrderForGroup(group, orderType, ctx) {
         cgst: gstBreakdown?.cgst || undefined,
         sgst: gstBreakdown?.sgst || undefined,
         igst: gstBreakdown?.igst || undefined,
-        emiEnabled: !adminBypass && !!emiSchedule ? true : undefined,
-        emiTenureMonths: !adminBypass && emiSchedule ? emiTenureMonths : undefined,
-        emiTokenAmount: !adminBypass ? emiSchedule?.tokenAmount : undefined,
-        emiSurchargeAmount: !adminBypass ? emiSchedule?.surchargeAmount : undefined,
         /*
-         * D45: the seller's share of the surcharge, recorded for the first time.
-         * `computeEmiSchedule` has always returned it and nothing ever stored it,
-         * so a split the admin had configured (default 50%) was computed and
-         * discarded on every EMI order. Persisting it moves no money — see the
-         * field's own 🛑 — it just stops the decision being thrown away.
+         * The eleven `emi*` fields, from one builder shared with the gateway
+         * path — which carried none of them, so every order paid online lost its
+         * instalment plan. D45's note about `emiSurchargeSellerShare` being
+         * computed and discarded now lives on `emiOrderFields` itself.
+         *
+         * 🛑 `adminBypass` nulls the whole group by passing no schedule, rather
+         * than by repeating `!adminBypass &&` eleven times. The bypass marks an
+         * order paid without a payment, so there is no token and no plan — and
+         * `resolveEmiChoice` now refuses that combination outright, making this
+         * a second line of defence rather than the only one.
          */
-        emiSurchargeSellerShare: !adminBypass ? emiSchedule?.surchargeSellerShare : undefined,
-        emiInstallments: !adminBypass && emiSchedule
-            ? emiSchedule.installments.map((i) => ({ index: i.index, dueDate: i.dueDate, amount: i.amount, status: "pending" }))
-            : undefined,
-        emiRemainingBalance: !adminBypass ? emiSchedule?.remainingBalance : undefined,
-        emiComplete: !adminBypass && emiSchedule ? false : undefined,
+        ...emiOrderFields(adminBypass ? null : (emiSchedule ?? null), emiTenureMonths),
         couponCode: appliedDiscounts[0]?.code,
         couponDiscount: couponDiscount > 0 ? couponDiscount : undefined,
         appliedDiscounts: appliedDiscounts.length > 0 ? appliedDiscounts : undefined,
@@ -1039,6 +1362,9 @@ async function createOrderForGroup(group, orderType, ctx) {
         ...extraOrderFields,
     });
     orderIds.push(order.id);
+    // The second half of the points tender — see `settlePointsTender`. Runs
+    // before the caller asks the gateway for anything.
+    await settlePointsTender({ orderId: order.id, userId: uid, pointsApplied, pointsBudget });
     // Close the loop on any locked line this order settled: flip the offer to
     // "paid" (its terminal status had NO server-side writer before 2026-08-21,
     // so an accepted offer could be re-added and re-ordered) and back-link the
@@ -1089,15 +1415,17 @@ async function createOrderForGroup(group, orderType, ctx) {
  * auth + rate-limiting before calling this and supply the resolved user fields.
  */
 export async function createCheckoutOrderAction(input) {
-    const { userId: uid, userName, userEmail, addressId, paymentMethod, emiTenureMonths, notes, excludedProductIds = [], adminBypass = false, adminBypassBy, outOfStockPolicy = OutOfStockPolicyValues.SKIP_ITEMS, } = input;
+    const { userId: uid, userName, userEmail, addressId, notes, excludedProductIds = [], adminBypass = false, adminBypassBy, outOfStockPolicy = OutOfStockPolicyValues.SKIP_ITEMS, } = input;
+    /*
+     * The TENDER, resolved before anything else because the COD and manual-UPI
+     * guards below are about the tender and run before the cart read. The
+     * ARRANGEMENT (`emiOptIn` + tenure) lives on the cart and is resolved after
+     * it — see the block below the cart load.
+     */
+    const paymentMethod = emiTenderFor(input.paymentMethod);
     const siteSettings = await siteSettingsRepository.getSingleton();
     const commissions = siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS;
     const emiSettings = siteSettings?.emi ?? CHECKOUT_DEFAULT_EMI_SETTINGS;
-    if (paymentMethod === "emi") {
-        if (!emiTenureMonths || !emiSettings.tenureOptions.includes(emiTenureMonths)) {
-            throw new ValidationError(`emiTenureMonths must be one of: ${emiSettings.tenureOptions.join(", ")}`);
-        }
-    }
     // W1-43 — enforce COD toggle.
     if (!adminBypass &&
         paymentMethod === "cod" &&
@@ -1114,6 +1442,30 @@ export async function createCheckoutOrderAction(input) {
     if (!cart.items || cart.items.length === 0) {
         throw new ValidationError(ERROR_MESSAGES.CHECKOUT.CART_EMPTY);
     }
+    /*
+     * ── The two payment axes, resolved ONCE, AFTER the cart is loaded ────────
+     *
+     * Everything below reads `paymentMethod` (the tender) and `emiOptIn` (the
+     * arrangement) from here, never from `input`. A second place deciding "is
+     * this an EMI order" is the drift this normaliser exists to prevent, and
+     * the legacy `paymentMethod: "emi"` mapping only holds if exactly one
+     * expression performs it.
+     *
+     * 🛑 It has to sit below the cart read because the plan LIVES on the cart,
+     * not in the request — see `CartDocument.emiPlan`. The cart is loaded here
+     * anyway, so this costs nothing.
+     */
+    const emiChoice = resolveEmiChoice({
+        paymentMethod: input.paymentMethod,
+        cartEmiPlan: cart.emiPlan ?? null,
+        legacyTenureMonths: input.emiTenureMonths,
+    });
+    if (!emiChoice.ok)
+        throw new ValidationError(emiChoice.reason);
+    const { emiOptIn, emiTenureMonths } = emiChoice.choice;
+    if (emiOptIn && (!emiTenureMonths || !emiSettings.tenureOptions.includes(emiTenureMonths))) {
+        throw new ValidationError(`emiTenureMonths must be one of: ${emiSettings.tenureOptions.join(", ")}`);
+    }
     const excludedSet = new Set(excludedProductIds);
     const selectedSet = cart.selectedItemIds?.length
         ? new Set(cart.selectedItemIds)
@@ -1136,16 +1488,13 @@ export async function createCheckoutOrderAction(input) {
     // otherwise a buyer could dodge it by splitting a big cart across
     // sellers. Skipped for COD (physical hand-off at the door is its own
     // verification) and admin-bypass checkouts.
-    const otpThreshold = siteSettings?.payment?.otpCheckoutThreshold;
-    if (!adminBypass && paymentMethod !== "cod" && typeof otpThreshold === "number" && otpThreshold > 0) {
-        const cartTotalForOtpCheck = cartItems.reduce((sum, item) => sum + item.price * item.quantity, 0);
-        if (cartTotalForOtpCheck >= otpThreshold) {
-            const verified = await isCheckoutValueOtpVerified(uid);
-            if (!verified) {
-                throw new ApiError(403, "CHECKOUT_VALUE_OTP_REQUIRED");
-            }
-        }
-    }
+    await assertCheckoutValueOtp({
+        uid,
+        amount: cartItems.reduce((sum, item) => sum + item.price * item.quantity, 0),
+        threshold: siteSettings?.payment?.otpCheckoutThreshold,
+        paymentMethod,
+        adminBypass,
+    });
     /*
      * COD value cap — the SERVER half of the gate.
      *
@@ -1181,6 +1530,7 @@ export async function createCheckoutOrderAction(input) {
     }
     const isDigitalCart = cartIsDigitalOnly(cartItems);
     let shippingAddress;
+    let deliverySnapshot;
     let resolvedAddress = null;
     if (!isDigitalCart) {
         if (!addressId) {
@@ -1201,6 +1551,13 @@ export async function createCheckoutOrderAction(input) {
             throw new NotFoundError(ERROR_MESSAGES.CHECKOUT.ADDRESS_REQUIRED);
         }
         shippingAddress = formatShippingAddress(resolvedAddress);
+        /*
+         * 🛑 REVEALED first. `findById` returns this PII encrypted, and
+         * `snapshotDeliveryAddress` demands `AddressPlain` precisely so that
+         * freezing `enc:v1:…` onto an invoice is a compile error rather than
+         * something discovered on a printed label.
+         */
+        deliverySnapshot = snapshotDeliveryAddress(unitOfWork.addresses.revealAddress(resolvedAddress));
     }
     const db = getAdminDb();
     // SB6-C — pre-tx fetch products so we can run the maxPerUser cap check
@@ -1240,6 +1597,19 @@ export async function createCheckoutOrderAction(input) {
      * is the only safe place for this, and the method is decided here.
      */
     assertPaymentMethodAllowed(cartItems, preTxProductById, paymentMethod);
+    /*
+     * 🛑 The second axis needs its own assertion, and omitting it would have
+     * been a silent regression of a rule that already exists.
+     *
+     * `prizeDrawRule.blockedPaymentMethods` lists `"emi"` because winner
+     * assignment waits on confirmed payment. Once EMI stopped being a tender,
+     * that entry stopped matching anything — the gate above would see
+     * `upi_manual` (explicitly ALLOWED for prize draws) and wave through an
+     * instalment plan on a listing type that forbids one. This reads the SAME
+     * declaration rather than a second list, so a rule written once still
+     * governs both axes.
+     */
+    assertEmiOptInAllowed(cartItems, preTxProductById, emiOptIn);
     const preTxPairs = cartItems
         .map((item) => {
         const [firstMember] = getCartItemMemberIds(item);
@@ -1388,8 +1758,27 @@ export async function createCheckoutOrderAction(input) {
         g[0].item.storeId,
         g.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0),
     ]), computeCheckoutFees(cartSubtotal, commissions));
+    /*
+     * ── The checkout's points budget, read ONCE (D46/D47) ─────────────────────
+     *
+     * 🛑 One read for the whole checkout, not one per order group. Rule #6
+     * budgets ~3 sequential Firestore round-trips per request, and a cart
+     * spanning four sellers would otherwise pay four reads to learn one number.
+     *
+     * 🛑 And ZERO when the buyer did not opt in, so an ordinary checkout performs
+     * no points read at all — the common case must not pay for a feature it is
+     * not using.
+     *
+     * 🛑 `adminBypass` is deliberately excluded: that path takes no payment, so
+     * there is nothing for points to reduce, and debiting a buyer's balance for
+     * an order the admin placed free would be a theft with an audit-log entry
+     * saying otherwise.
+     */
+    const useAllPoints = cart.useAllPoints === true && !adminBypass;
+    const pointsBudget = { remaining: useAllPoints ? await safePointsBalance(uid) : 0 };
     const groupCtx = {
         paymentMethod,
+        emiOptIn,
         emiTenureMonths,
         emiSettings,
         commissions,
@@ -1400,6 +1789,7 @@ export async function createCheckoutOrderAction(input) {
         userName,
         userEmail,
         shippingAddress,
+        deliverySnapshot,
         notes,
         adminBypass,
         adminBypassBy,
@@ -1415,6 +1805,8 @@ export async function createCheckoutOrderAction(input) {
         platformFeeByStore,
         selectedShippingQuote: input.selectedShippingQuote,
         productById: checkoutProductById,
+        useAllPoints,
+        pointsBudget,
     };
     for (const { items: group, orderType } of orderGroups) {
         total += await createOrderForGroup(group, orderType, groupCtx);
@@ -1448,18 +1840,26 @@ export async function createCheckoutOrderAction(input) {
      * Deleting it leaves a promise with no mechanism, which is a disappointment.
      * Keeping it left a mechanism that silently takes points, which is a theft.
      *
-     * ## What the real tender has to do instead
-     *
-     * Points are a TENDER, so they belong in the pricing pipeline, not after it:
-     * a stage in `computeCheckoutTotal` AFTER rounding — `amountDue = total −
-     * pointsApplied` — with the gateway capturing `amountDue` and the
-     * post-capture guard comparing against `amountDue`. Anything else makes
-     * points a sixth way the captured amount can diverge from the recorded order
-     * total, which is the D37/D38/D40 family this plan exists to close.
-     *
-     * Everything that work needs now exists: `purchase_earn`, per-batch expiry,
-     * FIFO consumption, `redemption_reversal` and the seller-funded deduction.
-     * What is missing is the pipeline stage and the two document fields.
+     * ## ✅ The real tender was BUILT 2026-10-22 — and it is not here
+     *
+     * 🛑 Do not look for it at this line. Points are a TENDER, so they are a
+     * STAGE inside each order-creation path, immediately after that path's single
+     * `roundRupees` and BEFORE anything is written or captured:
+     *
+     *   - `resolvePointsTender` (`_internal/shared/checkout/order-math.ts`) —
+     *     the arithmetic, beside every other money rule.
+     *   - the stage in `createOrderForGroup` and `createPhonePeGroupOrder`,
+     *     which write `pointsApplied` + `amountDue` onto the order.
+     *   - `settlePointsTender` — ONE debit implementation shared by both paths,
+     *     running after the order exists so the discount and the debit are two
+     *     halves of one recorded fact, and reverting the discount if `redeem`
+     *     refuses.
+     *
+     * This note stays because the mistake is worth keeping, but a comment saying
+     * a feature is "missing" while it sits 800 lines above is its own trap — it
+     * is how `assertReturnWindowOpen` got reported as absent when my own comment
+     * was shadowing the real answer. The accurate statement is: the tender is
+     * built, and this is the wrong place for it.
      */
     dispatchOrderConfirmationEmails(emailsToSend);
     serverLogger.info(`createCheckoutOrderAction: ${orderIds.length} order(s) placed for uid=${uid}` +
@@ -1489,11 +1889,16 @@ const EMPTY_PRICING_PREVIEW = {
     shipmentProtectionFee: 0,
     saleProtectionFee: 0,
     emiSurcharge: 0,
+    emiDeferred: 0,
     gstAmount: 0,
     couponDiscount: 0,
     platformFee: 0,
     gstOnFee: 0,
+    sharedPurchaseFee: 0,
     total: 0,
+    pointsApplied: 0,
+    amountDue: 0,
+    pointsBalance: 0,
     stores: [],
 };
 /**
@@ -1506,10 +1911,29 @@ const EMPTY_PRICING_PREVIEW = {
  * stock, creates an order, or writes coupon usage.
  */
 export async function previewCheckoutPricing(input) {
-    const { userId: uid, addressId, paymentMethod, excludedProductIds = [], lane, emiTenureMonths, } = input;
+    const { userId: uid, addressId, excludedProductIds = [], lane, } = input;
+    /*
+     * 🛑 Same normaliser as `createCheckoutOrderAction`, and on an INCOMPATIBLE
+     * combination this prices the tender WITHOUT instalments rather than
+     * throwing.
+     *
+     * The preview exists so a buyer can see consequences while they fiddle with
+     * controls; a 500 in the middle of that blanks the Order Summary and reads
+     * as a broken page. The order action still refuses, which is where refusing
+     * belongs — the same split this function already makes for EMI eligibility
+     * two hundred lines below.
+     */
+    const paymentMethod = emiTenderFor(input.paymentMethod);
     const siteSettings = await siteSettingsRepository.getSingleton();
     const commissions = siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS;
     const cart = await unitOfWork.carts.getOrCreate(uid);
+    const emiChoice = resolveEmiChoice({
+        paymentMethod: input.paymentMethod,
+        cartEmiPlan: cart.emiPlan ?? null,
+        legacyTenureMonths: input.emiTenureMonths,
+    });
+    const emiOptIn = emiChoice.ok && emiChoice.choice.emiOptIn;
+    const emiTenureMonths = emiChoice.ok ? emiChoice.choice.emiTenureMonths : undefined;
     const excludedSet = new Set(excludedProductIds);
     const selectedSet = cart.selectedItemIds?.length ? new Set(cart.selectedItemIds) : null;
     // An explicit lane wins: the cart page prices whichever tab is open, which may
@@ -1566,7 +1990,7 @@ export async function previewCheckoutPricing(input) {
          * and then the order path (equally unpassed) charged it. Preview and charge
          * agreed, and both were wrong in the same direction.
          */
-        const { shippingFee: groupShippingFee, storeState, storeProtections, storeEmiEnabled } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupTotal });
+        const { shippingFee: groupShippingFee, storeState, storeProtections, storeEmiEnabled, acceptsPoints, sharedPurchaseRates: previewSharedRates } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupTotal });
         // Add-ons are per store, read off the cart document — the same entry
         // createOrderForGroup will read when the order is actually placed.
         const addons = cart.storeAddons?.[firstItem.storeId] ?? {};
@@ -1597,13 +2021,14 @@ export async function previewCheckoutPricing(input) {
          * ineligible EMI order, which is where refusing belongs. An ineligible
          * cart simply previews no surcharge, because the tenure never applies.
          */
-        let groupEmiSurcharge = 0;
-        if (paymentMethod === "emi" && emiTenureMonths && siteSettings?.emi) {
-            const emiSettings = siteSettings.emi;
-            if (checkEmiEligibility(groupTotal, storeEmiEnabled, emiSettings).eligible) {
-                groupEmiSurcharge = computeBuyerEmiQuote(groupTotal, emiTenureMonths, emiSettings).surchargeAmount;
-            }
-        }
+        const groupEmiPreviewQuote = groupEmiQuote({ emiOptIn, emiTenureMonths, groupSubtotal: groupTotal, sellerEmiEnabled: storeEmiEnabled }, siteSettings?.emi);
+        const groupEmiSurcharge = groupEmiPreviewQuote?.surchargeAmount ?? 0;
+        /*
+         * What the buyer pays TODAY on an instalment order — the token plus every
+         * additive charge. Surfaced so the Order Summary can show both figures
+         * rather than one number the buyer has to interpret.
+         */
+        const groupEmiDeferred = groupEmiPreviewQuote?.remainingBalance ?? 0;
         const groupGiftWrapFee = computeGiftWrapFee(addons.giftWrapAddon ?? false, commissions);
         /*
          * C5e — the same three tiers `createOrderForGroup` enforces, so the figure
@@ -1617,6 +2042,28 @@ export async function previewCheckoutPricing(input) {
          * seller cannot flip the switch after the sale).
          */
         const groupHasFinalSale = group.some(({ product }) => product?.finalSale === true);
+        /*
+         * ── S5a in the PREVIEW ───────────────────────────────────────────────────
+         *
+         * 🛑 Here because a coordinator commits against this figure. The plan is
+         * explicit that the fees "must be shown before the coordinator commits" —
+         * a handling fee plus N−1 shipping legs discovered afterwards is exactly
+         * the surprise the arrangement makes expensive.
+         *
+         * The same function and the same `countDestinations` as both order paths,
+         * so the shown figure and the charged one cannot diverge. D37 is the record
+         * of what ONE money term reaching three of four paths costs: the buyer was
+         * shown one number, charged another, and the order recorded the first.
+         *
+         * 🛑 A preview NEVER throws, so an unpriced arrangement contributes 0 here
+         * rather than raising — `quoteSharedPurchase` reports it on `unpriced` and
+         * the ORDER path is what refuses. A preview that threw would render the
+         * whole cart as an error page for a seller's missing config.
+         */
+        const groupSharedPurchaseFee = quoteSharedPurchase({
+            destinationCount: countDestinations(group.map(({ item }) => item)),
+            rates: previewSharedRates,
+        }).total;
         const { shippingProtectionFee: groupShipmentProtectionFee, saleProtectionFee: groupSaleProtectionFee, } = computeProtectionFees({
             subtotal: groupTotal,
             selected: {
@@ -1681,6 +2128,7 @@ export async function previewCheckoutPricing(input) {
             shippingFee: groupShippingFee,
             codHandlingFee: groupCodHandlingFee,
             emiSurcharge: groupEmiSurcharge,
+            emiDeferred: groupEmiDeferred,
             giftWrapFee: groupGiftWrapFee,
             shipmentProtectionFee: groupShipmentProtectionFee,
             saleProtectionFee: groupSaleProtectionFee,
@@ -1701,24 +2149,44 @@ export async function previewCheckoutPricing(input) {
                 groupEmiSurcharge +
                 groupGiftWrapFee +
                 groupShipmentProtectionFee +
-                groupSaleProtectionFee,
+                groupSaleProtectionFee +
+                // S5a — a term in the per-store total, so the seller card and the
+                // order it previews agree.
+                groupSharedPurchaseFee,
             supportsShippingProtection: storeProtections.shipping,
             supportsSaleProtection: storeProtections.sale,
             hasFinalSaleItem: groupHasFinalSale,
+            acceptsPoints,
+            sharedPurchaseFee: groupSharedPurchaseFee,
+            // Filled by the tender pass below — it needs each store's share of the
+            // one capped commission, which is only allocatable once every group is
+            // known.
+            pointsApplied: 0,
         });
     }
     const sum = (pick) => stores.reduce((acc, s) => acc + pick(s), 0);
     const shippingFee = sum((s) => s.shippingFee);
     const codHandlingFee = sum((s) => s.codHandlingFee);
     const emiSurcharge = sum((s) => s.emiSurcharge);
+    const emiDeferred = sum((s) => s.emiDeferred);
     const giftWrapFeeTotal = sum((s) => s.giftWrapFee);
     const shipmentProtectionFeeTotal = sum((s) => s.shipmentProtectionFee);
     const saleProtectionFeeTotal = sum((s) => s.saleProtectionFee);
+    // S5a — summed from the same per-store figures, so the aggregate cannot
+    // disagree with the seller cards it is built from.
+    const sharedPurchaseFeeTotal = sum((s) => s.sharedPurchaseFee);
     const gstAmount = sum((s) => s.gstAmount);
     const couponDiscount = sum((s) => s.couponDiscount);
     // One capped commission for the whole checkout, on every payment method —
     // deliberately not per store, so it is not added to the per-store rows above.
-    const { platformFee, gstOnFee } = computeCheckoutFees(cartSubtotal, commissions);
+    // The whole object is kept (not just the two fields) because the points
+    // tender below re-allocates it per store through `allocateCheckoutFees`,
+    // which takes a `CheckoutFees` — and `totalFee` carries the
+    // `minimumTransactionFee` floor, which is exactly the field D41 found had no
+    // consumer anywhere. Destructuring it away here would be how it loses its
+    // second one.
+    const checkoutFees = computeCheckoutFees(cartSubtotal, commissions);
+    const { platformFee, gstOnFee } = checkoutFees;
     /*
      * 🛑 `gstAmount` is NOT a term, and leaving it in was a shown-vs-charged
      * drift waiting on a settings flag.
@@ -1751,21 +2219,77 @@ export async function previewCheckoutPricing(input) {
         giftWrapFeeTotal +
         shipmentProtectionFeeTotal +
         saleProtectionFeeTotal +
+        // S5a — a real additive charge, so it belongs in the column with the other
+        // fees rather than below the total like the tax-inclusive `gstAmount`.
+        sharedPurchaseFeeTotal +
         platformFee +
         gstOnFee;
+    /*
+     * ── THE POINTS TENDER, PREVIEWED (D46/D47) ────────────────────────────────
+     *
+     * 🛑 Applied PER STORE against the SAME base the order path uses, which is
+     * why this runs here and not inside the loop above: the base includes each
+     * store's share of the one capped commission, and that share is only
+     * allocatable once every group is known.
+     *
+     * 🛑 Per store is not a detail — it is the only shape that can agree with
+     * what gets charged. A cart-level application gives the same answer as the
+     * per-group one whenever every store accepts (the sum of per-group 50% caps
+     * equals 50% of the sum), and a DIFFERENT answer the moment one store does
+     * not: with ₹500 at an accepting store, ₹500 at a declining one and a 600
+     * balance, per-store applies ₹250 and cart-level would promise ₹500. The
+     * buyer would be shown a discount half of which could never be honoured.
+     *
+     * The iteration order matches `orderGroups`, and so does the order-creation
+     * loop, so the budget is drawn down in the same sequence in both — which is
+     * what makes the two sums identical rather than merely close.
+     */
+    const previewUseAllPoints = cart.useAllPoints === true;
+    const previewBalance = previewUseAllPoints ? await safePointsBalance(uid) : 0;
+    if (previewUseAllPoints && previewBalance > 0) {
+        const feeByStore = allocateCheckoutFees(stores.map((s) => [s.storeId, s.subtotal]), checkoutFees);
+        const { perGroup } = allocatePointsAcrossGroups(stores.map((s) => {
+            const share = feeByStore.get(s.storeId);
+            return {
+                // The SAME base `createOrderForGroup` applies the tender to: the
+                // store's charged total plus its share of the one capped commission.
+                // `store.total` deliberately excludes that share (it is a checkout
+                // charge, not a per-store one), so it is added back here rather than
+                // by widening a published field.
+                total: roundRupees(s.total + (share?.platformFee ?? 0) + (share?.gstOnFee ?? 0)),
+                accepted: s.acceptsPoints,
+            };
+        }), previewBalance, true);
+        perGroup.forEach((applied, i) => {
+            stores[i].pointsApplied = applied;
+        });
+    }
+    const pointsApplied = sum((s) => s.pointsApplied);
     return {
         subtotal: cartSubtotal,
         shippingFee,
         codHandlingFee,
         emiSurcharge,
+        emiDeferred,
         giftWrapFee: giftWrapFeeTotal,
         shipmentProtectionFee: shipmentProtectionFeeTotal,
         saleProtectionFee: saleProtectionFeeTotal,
+        sharedPurchaseFee: sharedPurchaseFeeTotal,
         gstAmount,
         couponDiscount,
         platformFee,
         gstOnFee,
         total,
+        pointsApplied,
+        // Equal to `total` when no points apply, so every existing reader of
+        // either figure keeps getting the right number.
+        /*
+         * 🛑 Both tenders, through the SAME helper the two order writers use —
+         * so the figure the buyer is shown and the figure they are charged are
+         * one expression, not two that agree today.
+         */
+        amountDue: amountDueNow({ orderTotal: total, pointsApplied, emiRemainingBalance: emiDeferred }),
+        pointsBalance: previewBalance,
         stores,
     };
 }
@@ -1916,7 +2440,16 @@ async function refundDroppedItemsForPhonePeCheckout(input) {
  * from the inline version this replaced.
  */
 async function createPhonePeGroupOrder(group, orderType, ctx) {
-    const { appliedCoupons, cartSubtotal, storeAddons, platformFeeByStore, siteSettings, uid, userName, userEmail, merchantOrderId, phonepeOrderId, transactionId, shippingAddress, notes, outOfStockPolicy, unavailablePaid, orderIds, emailsToSend, couponUsageAccumulator, productById: phonepeProductById, buyerState, } = ctx;
+    const { appliedCoupons, cartSubtotal, storeAddons, platformFeeByStore, siteSettings, uid, userName, userEmail, merchantOrderId, phonepeOrderId, transactionId, shippingAddress, notes, outOfStockPolicy, unavailablePaid, orderIds, emailsToSend, couponUsageAccumulator, productById: phonepeProductById, buyerState, useAllPoints, pointsBudget, 
+    /*
+     * 🛑 All three were DECLARED on the params above and never destructured,
+     * so the body referenced them as free names: `emiOptIn`/`emiTenureMonths`
+     * in the schedule call and `deliverySnapshot` in `placeOfSupply`. The
+     * interface promised them and the function could not see them — which is
+     * why appkit's own `tsc` is the gate for this file and not a reading of
+     * the diff.
+     */
+    emiOptIn, emiTenureMonths, deliverySnapshot, } = ctx;
     /*
      * Which online gateway actually took the money, read off the registered
      * provider rather than passed in — exactly one is registered per process
@@ -1932,7 +2465,21 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
     // seller group here, duplicated from resolveShippingCost.
     // D44: `groupTotal` is computed just above — pass it so a free-above
     // threshold can fire and an unpriceable store is recorded.
-    const { shippingFee, storeOwnerId, storeState, storeTaxIdentity, storeProtections } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupTotal });
+    const { shippingFee, storeOwnerId, storeState, storeTaxIdentity, storeProtections, acceptsPoints, sharedPurchaseRates, storeEmiEnabled } = await resolveShippingCost(firstItem.storeId, { goodsValue: groupTotal });
+    /*
+     * The instalment schedule for THIS seller group, through the same helper the
+     * COD/manual writer uses — not a copy of its block. Two hand-written
+     * copies is the create-vs-create axis of Root Cause #39, and these two
+     * functions have already drifted once over add-on fees (#65).
+     *
+     * 🛑 Gate FAILURES are silent here, unlike the manual path, and that is
+     * deliberate rather than sloppy: the money is already captured by the time
+     * this runs, so throwing would produce a charged-with-no-order (the D64
+     * class). `/api/payment/create-order` applies the same gate BEFORE capture,
+     * which is where a refusal belongs; if it declined EMI, it captured the full
+     * total and no schedule is wanted here either.
+     */
+    const phonepeEmiSchedule = groupEmiSchedule({ emiOptIn, emiTenureMonths, groupSubtotal: groupTotal, sellerEmiEnabled: storeEmiEnabled }, siteSettings?.emi);
     /*
      * Same supplier-of-record rule as `createOrderForGroup`, through the same
      * function. This path (PhonePe verify / webhook) is the SECOND place an
@@ -2050,20 +2597,82 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
     /* Product GST is not a term — prices are tax-inclusive, so it is already
      * inside `groupTotal`. Matches the COD/UPI path exactly; `platformFeeGst`
      * stays because that is GST on our fee, charged on top. */
+    /*
+     * ── S5a: the shared-purchase arrangement, matching the COD/manual path ────
+     *
+     * Same function, same inputs, same position — before `orderTotal`, because
+     * it is a term in it. See the fuller 🛑 at the COD/manual site for why the
+     * rates are snapshotted and why an unpriced arrangement is refused rather
+     * than quoted at ₹0.
+     *
+     * 🛑 On THIS path the money is already captured by the time this runs, so a
+     * refusal here means a charged-with-no-order — the D64 class. That is why
+     * `/api/payment/create-order` must apply the same term: the pre-payment
+     * amount and this total have to agree, which is the parity C0c defect 1 was
+     * about and the reason every addition here has to be made in three places.
+     */
+    const phonepeSharedQuote = quoteSharedPurchase({
+        destinationCount: countDestinations(group.map(({ item }) => item)),
+        rates: sharedPurchaseRates,
+    });
     // D42: rounded once on the sum — see the COD/UPI path's 🛑 for why a raw
     // float sum of seven 2dp terms reached Firestore as 1011.8000000000001.
-    const orderTotal = roundRupees(Math.max(0, groupTotal - couponDiscount) + shippingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee + platformFee + platformFeeGst);
+    const orderTotal = roundRupees(Math.max(0, groupTotal - couponDiscount) + shippingFee + giftWrapFee + shipmentProtectionFee + saleProtectionFee + platformFee + platformFeeGst + (phonepeEmiSchedule?.surchargeAmount ?? 0) + phonepeSharedQuote.total);
+    /*
+     * ── POINTS TENDER (D46/D47) — the same STAGE as the COD/manual path ───────
+     *
+     * Same four inputs, same function, same point in the sequence: immediately
+     * after `orderTotal`'s single `roundRupees` and before anything is written.
+     * Computing it here rather than in a shared builder is unavoidable — the two
+     * paths derive `orderTotal` separately — but the ARITHMETIC is
+     * `resolvePointsTender` in both, so they cannot disagree about the amount
+     * the way the add-on fees once did (Root Cause #65).
+     *
+     * 🛑 This is the path whose capture matters most: `amountDue` is what the
+     * Razorpay order is created for, so a divergence here is money taken that
+     * the order does not record.
+     */
+    const pointsOptedIn = useAllPoints === true;
+    const pointsAccepted = pointsOptedIn && acceptsPoints;
+    const { pointsApplied } = resolvePointsTender({
+        orderTotal,
+        balance: pointsAccepted ? pointsBudget.remaining : 0,
+        accepted: pointsAccepted,
+        optedIn: pointsOptedIn,
+    });
+    if (pointsApplied > 0)
+        pointsBudget.remaining -= pointsApplied;
+    /*
+     * 🛑 `resolvePointsTender`'s own `amountDue` is DISCARDED here — it knows
+     * only about points, and on an instalment order the deferred balance reduces
+     * the collection too. `amountDueNow` composes both, and is the same
+     * expression the manual writer and the pricing preview use, so the figure
+     * recorded in `paymentRecord.amount` below cannot drift from the figure
+     * `/api/payment/create-order` actually captured.
+     */
+    const amountDue = amountDueNow({
+        orderTotal,
+        pointsApplied,
+        emiRemainingBalance: phonepeEmiSchedule?.remainingBalance ?? 0,
+    });
     // S-SBUNI-RULES 2026-05-13 — order-item decoration via rule registry.
     // Same expansion as the COD/UPI path. This was a THIRD hand-rolled copy of
     // the price rule (`isBundle ? item.price : product.price`) that — like the
     // two in the consumer's checkout route — silently omitted `lockedPrice`, so
     // an accepted offer paid through PhonePe was RECORDED at the seller's list
     // price. `lineTotalFor` inside the expansion is the single definition.
-    const orderItems = group.flatMap(({ item, product }) => {
+    const basePhonepeItems = group.flatMap(({ item, product }) => {
         const lt = (product?.listingType ?? "standard");
         const itemRule = getListingRule(lt);
         return expandCartLineToOrderRows(item, product, phonepeProductById).map((baseLine) => itemRule.decorateOrderItem(baseLine, product));
     });
+    /*
+     * Part 14 — the parts freeze, on THIS path too. The comment four lines
+     * above records the cost of the last thing added to one path and not the
+     * other: an accepted offer paid through PhonePe was recorded at the
+     * seller's list price.
+     */
+    const orderItems = await freezePartsOnItems(basePhonepeItems);
     const totalQuantity = group.reduce((sum, { item }) => sum + item.quantity, 0);
     const imageUrls = [
         ...new Set(group
@@ -2089,6 +2698,16 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         quantity: totalQuantity,
         unitPrice: group[0].product.price,
         totalPrice: orderTotal,
+        // D46/D47 — see the identical pair in `createOrderForGroup`. `totalPrice`
+        // stays the full value of the supply; points reduce what is COLLECTED.
+        pointsApplied: pointsApplied > 0 ? pointsApplied : undefined,
+        /*
+         * Written whenever it differs from the total — points OR instalments. It
+         * was `pointsApplied > 0 ? … : undefined`, so an EMI order carried no
+         * `amountDue` and every reader fell back to the full total.
+         */
+        amountDue: amountDue !== orderTotal ? amountDue : undefined,
+        ...emiOrderFields(phonepeEmiSchedule, emiTenureMonths),
         currency: firstItem.currency ?? getDefaultCurrency(),
         storeId: firstItem.storeId || undefined,
         storeName: firstItem.storeName || undefined,
@@ -2120,7 +2739,15 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         paymentRecord: {
             method: gatewayName === "razorpay" ? "razorpay" : "phonepe",
             transactionId: transactionId ?? merchantOrderId,
-            amount: orderTotal,
+            /*
+             * 🛑 What the gateway actually CAPTURED, which is `amountDue` once points
+             * are applied — not the order's value. This record is the evidence a
+             * reconciler compares against the gateway's own figure (Phase 4 R2), so
+             * writing `orderTotal` here would open an `amount_mismatch` case on every
+             * points-funded order: the discount would read as money we failed to
+             * collect.
+             */
+            amount: amountDue,
             paidAt: new Date(),
             verifiedBy: `${gatewayName}-order-status`,
             verificationMethod: "order-status",
@@ -2148,6 +2775,14 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         // Recorded as well as charged — an order that collects a protection fee
         // without a record of it cannot be reconciled against a later claim.
         saleProtectionFee: saleProtectionFee > 0 ? saleProtectionFee : undefined,
+        // S5a — snapshotted, matching the COD/manual path field for field.
+        sharedPurchase: phonepeSharedQuote.isShared
+            ? {
+                destinationCount: countDestinations(group.map(({ item }) => item)),
+                handlingFee: phonepeSharedQuote.handlingFee,
+                extraShippingFee: phonepeSharedQuote.extraShippingFee,
+            }
+            : undefined,
         /*
          * The tax breakdown, matching `createOrderForGroup` field for field.
          * This path recorded NONE of it before C0c defect 1 — so an online order
@@ -2158,6 +2793,15 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
          */
         taxableAmount: phonepeGst?.taxableAmount,
         exemptAmount: phonepeGst?.exemptAmount || undefined,
+        // Phase 7 — the place of supply, matching `createOrderForGroup` field for
+        // field. This path recorded NONE of the tax breakdown until C0c defect 1,
+        // which is precisely why every addition here has to be made twice.
+        /*
+         * Part 14 — the snapshot's state is authoritative, because it is the
+         * field the invoice and GSTR-1 actually read. `buyerState` stays as
+         * the fallback for a digital cart, which has no delivery address.
+         */
+        placeOfSupply: deliverySnapshot?.deliveryState || buyerState || undefined,
         // Our registration at the moment of supply — see the schema. Mirrors the
         // COD/UPI path so both produce an invoiceable order.
         supplierGstin: supplier.gstin,
@@ -2177,6 +2821,9 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         ...extraOrderFields,
     });
     orderIds.push(order.id);
+    // The second half of the points tender — one implementation, shared with the
+    // COD/manual path. See `settlePointsTender`.
+    await settlePointsTender({ orderId: order.id, userId: uid, pointsApplied, pointsBudget });
     // Close the loop on any locked line this order settled: flip the offer to
     // "paid" (its terminal status had NO server-side writer before 2026-08-21,
     // so an accepted offer could be re-added and re-ordered) and back-link the
@@ -2426,6 +3073,7 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
     await assertLockedLinesStillValid(settleItems, uid);
     const isDigitalCartPp = cartIsDigitalOnly(settleItems);
     let shippingAddress;
+    let deliverySnapshot;
     let resolvedAddressPp = null;
     if (!isDigitalCartPp) {
         if (!addressId) {
@@ -2440,6 +3088,13 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
             throw new NotFoundError(ERROR_MESSAGES.CHECKOUT.ADDRESS_REQUIRED);
         }
         shippingAddress = formatShippingAddress(resolvedAddressPp);
+        /*
+         * 🛑 REVEALED first. `findById` returns this PII encrypted, and
+         * `snapshotDeliveryAddress` demands `AddressPlain` precisely so that
+         * freezing `enc:v1:…` onto an invoice is a compile error rather than
+         * something discovered on a printed label.
+         */
+        deliverySnapshot = snapshotDeliveryAddress(unitOfWork.addresses.revealAddress(resolvedAddressPp));
     }
     // SB-UNI-5 2026-05-13 — bundle-aware product fetch + validation. Each
     // cart line gets paired with a "representative" product (first member id
@@ -2538,7 +3193,12 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
         // percentages, so the moment the cap landed it would have expected more
         // than was actually collected and rejected every legitimate payment.
         const commissionRates = siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS;
-        const { platformFee: expectedPlatformFee, gstOnFee: expectedGstOnFee } = computeCheckoutFees(cartSubtotalRs, commissionRates);
+        // The whole object is kept so the points tender below can re-allocate it
+        // per group — see the same note in `previewCheckoutPricing`. `totalFee`
+        // carries the `minimumTransactionFee` floor, and destructuring it away is
+        // how it lost every consumer once already (D41).
+        const expectedFees = computeCheckoutFees(cartSubtotalRs, commissionRates);
+        const { platformFee: expectedPlatformFee, gstOnFee: expectedGstOnFee } = expectedFees;
         // Same per-seller-group shipping sum /api/payment/create-order charged
         // upfront (and the same resolveShippingCost createPhonePeGroupOrder
         // below will use to build each order's recorded totalPrice) — keeps this
@@ -2584,6 +3244,36 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
             goodsValue: g.items.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0),
         })));
         const expectedShippingFee = expectedShippingFees.reduce((sum, r) => sum + r.shippingFee, 0);
+        /*
+         * ── The instalment terms, which this guard must expect BOTH of ──────────
+         *
+         * 🛑 Two terms, pulling in opposite directions, and omitting either one
+         * breaks the guard in the direction that costs the buyer an order:
+         *
+         *   + surcharge — the cost of credit, a real addition to the total
+         *   − deferred  — the financed principal plus that surcharge, which is NOT
+         *                 collected today
+         *
+         * With neither term the guard would expect the un-surcharged FULL total
+         * while the gateway captured only the token, trip `paid < expected − 1`,
+         * and throw **after the money was taken** — a charged-with-no-order, the
+         * D64 class, on every single EMI order. That is strictly worse than the
+         * overcharge this guard exists to catch, which is the same trap D44's note
+         * above records one defect over.
+         *
+         * Built from the same per-group goods values and the same `groupEmiQuote`
+         * the capture route and the order writer call, so the only way the three
+         * can disagree is a change made to one and not the others.
+         */
+        const guardEmiPlanTenure = cart.emiPlan?.tenureMonths;
+        const expectedEmiQuotes = expectedShippingGroups.map((g, i) => groupEmiQuote({
+            emiOptIn: guardEmiPlanTenure !== undefined,
+            emiTenureMonths: guardEmiPlanTenure,
+            groupSubtotal: g.items.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0),
+            sellerEmiEnabled: expectedShippingFees[i]?.storeEmiEnabled === true,
+        }, siteSettings?.emi));
+        const expectedEmiSurcharge = expectedEmiQuotes.reduce((sum, q) => sum + (q?.surchargeAmount ?? 0), 0);
+        const expectedEmiDeferred = expectedEmiQuotes.reduce((sum, q) => sum + (q?.remainingBalance ?? 0), 0);
         // Add-ons are per store, so the expected total sums each group's own
         // selection — a single cart-wide figure would over- or under-count as soon
         // as the buyer picked add-ons for only some sellers.
@@ -2624,11 +3314,70 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
          * would make this guard demand ~₹580 more than the buyer owes on a
          * ₹5,547 cart — rejecting every correctly-charged order.
          */
-        const expectedPaymentAmountRs = expectedDiscountedSubtotal +
+        /*
+         * ── D46/D47 — the guard must expect the amount NET OF POINTS ─────────────
+         *
+         * 🛑 Omitting this term would make the guard reject every correctly-charged
+         * points order, which is worse than the overcharge it exists to catch: the
+         * money is already captured by the time this runs, so a false rejection is
+         * a charged-with-no-order — the D64 class.
+         *
+         * The bases are rebuilt here from the same terms in the same order, and the
+         * draw-down is the same shared allocator, so the only way this can diverge
+         * from the capture route is a change made to one and not the other. That is
+         * precisely the drift the four-way export comment on
+         * `allocatePointsAcrossGroups` exists to make visible.
+         */
+        const guardUseAllPoints = cart.useAllPoints === true;
+        let expectedPointsApplied = 0;
+        if (guardUseAllPoints) {
+            const guardBalance = await safePointsBalance(uid);
+            if (guardBalance > 0) {
+                const guardSubtotals = expectedShippingGroups.map((g) => [
+                    g.items[0].item.storeId,
+                    g.items.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0),
+                ]);
+                const guardFeeByGroup = allocateCheckoutFees(guardSubtotals, expectedFees);
+                const guardCouponByGroup = computeCartCouponDiscount(cart.appliedCoupons ?? [], expectedShippingGroups.map((g) => ({
+                    storeId: g.items[0].item.storeId,
+                    lines: g.items.map(({ item, product }) => ({
+                        itemId: item.itemId,
+                        lineTotal: lineTotalFor(item, product),
+                    })),
+                }))).perGroup;
+                /*
+                 * The per-group add-on fee, lifted out of the `map` below so that
+                 * callback has no block body. Its statements sat at brace-depth 6
+                 * inside `if → if → callback`, which DEEP_NESTING blocks — and the
+                 * add-on sum is the one part of this base the sibling money path
+                 * (`POST /api/payment/create-order`) computes earlier rather than
+                 * inline, so it is also the natural seam.
+                 */
+                const guardAddonFee = (storeId, goods) => {
+                    const addons = cart.storeAddons?.[storeId] ?? {};
+                    return (computeGiftWrapFee(addons.giftWrapAddon ?? false, commissionRates) +
+                        computeShipmentProtectionFee(goods, addons.shipmentProtectionAddon ?? false, commissionRates));
+                };
+                const guardBases = expectedShippingGroups.map((g, i) => pointsBaseForGroup({
+                    goods: guardSubtotals[i][1],
+                    couponDiscount: guardCouponByGroup[i]?.couponDiscount ?? 0,
+                    shippingFee: expectedShippingFees[i]?.shippingFee ?? 0,
+                    addonFee: guardAddonFee(g.items[0].item.storeId, guardSubtotals[i][1]),
+                    platformFee: guardFeeByGroup.get(g.items[0].item.storeId)?.platformFee ?? 0,
+                    gstOnFee: guardFeeByGroup.get(g.items[0].item.storeId)?.gstOnFee ?? 0,
+                    acceptsPoints: expectedShippingFees[i]?.acceptsPoints === true,
+                }));
+                expectedPointsApplied = allocatePointsAcrossGroups(guardBases, guardBalance, true).pointsApplied;
+            }
+        }
+        const expectedPaymentAmountRs = roundRupees(Math.max(0, expectedDiscountedSubtotal +
             expectedPlatformFee +
             expectedGstOnFee +
             expectedAddonFees +
-            expectedShippingFee;
+            expectedShippingFee +
+            expectedEmiSurcharge -
+            expectedEmiDeferred -
+            expectedPointsApplied));
         // Reuses the order already fetched above to confirm COMPLETED — PhonePe's
         // own amount is in its wire-format smallest unit. // audit-money-units-ok: describes the PhonePe boundary conversion this line performs, not our storage convention
         const paidAmountRs = paiseToRupees(gatewayOrder.amount);
@@ -2703,6 +3452,19 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
         g[0].item.storeId,
         g.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0),
     ]), computeCheckoutFees(cartSubtotal, siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS));
+    /*
+     * The points budget for this checkout — one read, zero when not opted in.
+     * See the identical pair in the COD/manual path for why it is a shared
+     * remainder rather than a per-group balance read.
+     *
+     * 🛑 On THIS path the money has already been captured by the time these
+     * orders are created, so the budget must match whatever the pre-payment
+     * amount was computed against. That is why `useAllPoints` is read off the
+     * cart here too and not re-decided: the figure quoted to the gateway and the
+     * figure recorded on the orders come from the same cart flag.
+     */
+    const useAllPoints = cart.useAllPoints === true;
+    const pointsBudget = { remaining: useAllPoints ? await safePointsBalance(uid) : 0 };
     for (const { items: group, orderType } of orderGroups) {
         total += await createPhonePeGroupOrder(group, orderType, {
             appliedCoupons,
@@ -2728,6 +3490,15 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
             emailsToSend,
             couponUsageAccumulator,
             productById: productByIdPaid,
+            useAllPoints,
+            pointsBudget,
+            /*
+             * Resolved from the CART, exactly as the capture route did — so the
+             * schedule written onto the order is built from the same tenure the
+             * gateway was asked to capture against.
+             */
+            emiOptIn: cart.emiPlan?.tenureMonths !== undefined,
+            emiTenureMonths: cart.emiPlan?.tenureMonths,
         });
     }
     await flushCouponUsageAccumulator(couponUsageAccumulator, uid);