@mohasinac/appkit 4.62.1 → 4.63.1

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

@@ -16,7 +16,7 @@ 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 { allocatePointsAcrossGroups, computePreOrderDepositAmount, lineTotalFor, resolvePointsTender, 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.
  *
@@ -50,11 +50,13 @@ import { assertCheckoutLane, assertLockedLinesStillValid, finalizeLockedLines, }
 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";
@@ -67,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.
@@ -82,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
@@ -733,7 +736,7 @@ async function settlePointsTender(input) {
  * 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, useAllPoints, pointsBudget, } = 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.
@@ -767,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.
@@ -830,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;
@@ -1063,10 +1095,18 @@ 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;
@@ -1111,6 +1151,16 @@ async function createOrderForGroup(group, orderType, ctx) {
     });
     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).
@@ -1140,7 +1190,23 @@ async function createOrderForGroup(group, orderType, ctx) {
          * that predate this.
          */
         pointsApplied: pointsApplied > 0 ? pointsApplied : undefined,
-        amountDue: pointsApplied > 0 ? amountDue : 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,
@@ -1173,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,
@@ -1225,7 +1297,12 @@ async function createOrderForGroup(group, orderType, ctx) {
          * 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.
          */
-        placeOfSupply: buyerState || undefined,
+        /*
+         * 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.
@@ -1263,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,
@@ -1342,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" &&
@@ -1367,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)
@@ -1389,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.
      *
@@ -1434,6 +1530,7 @@ export async function createCheckoutOrderAction(input) {
     }
     const isDigitalCart = cartIsDigitalOnly(cartItems);
     let shippingAddress;
+    let deliverySnapshot;
     let resolvedAddress = null;
     if (!isDigitalCart) {
         if (!addressId) {
@@ -1454,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
@@ -1493,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);
@@ -1661,6 +1778,7 @@ export async function createCheckoutOrderAction(input) {
     const pointsBudget = { remaining: useAllPoints ? await safePointsBalance(uid) : 0 };
     const groupCtx = {
         paymentMethod,
+        emiOptIn,
         emiTenureMonths,
         emiSettings,
         commissions,
@@ -1671,6 +1789,7 @@ export async function createCheckoutOrderAction(input) {
         userName,
         userEmail,
         shippingAddress,
+        deliverySnapshot,
         notes,
         adminBypass,
         adminBypassBy,
@@ -1770,6 +1889,7 @@ const EMPTY_PRICING_PREVIEW = {
     shipmentProtectionFee: 0,
     saleProtectionFee: 0,
     emiSurcharge: 0,
+    emiDeferred: 0,
     gstAmount: 0,
     couponDiscount: 0,
     platformFee: 0,
@@ -1791,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
@@ -1882,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
@@ -1988,6 +2128,7 @@ export async function previewCheckoutPricing(input) {
             shippingFee: groupShippingFee,
             codHandlingFee: groupCodHandlingFee,
             emiSurcharge: groupEmiSurcharge,
+            emiDeferred: groupEmiDeferred,
             giftWrapFee: groupGiftWrapFee,
             shipmentProtectionFee: groupShipmentProtectionFee,
             saleProtectionFee: groupSaleProtectionFee,
@@ -2027,6 +2168,7 @@ export async function previewCheckoutPricing(input) {
     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);
@@ -2128,6 +2270,7 @@ export async function previewCheckoutPricing(input) {
         shippingFee,
         codHandlingFee,
         emiSurcharge,
+        emiDeferred,
         giftWrapFee: giftWrapFeeTotal,
         shipmentProtectionFee: shipmentProtectionFeeTotal,
         saleProtectionFee: saleProtectionFeeTotal,
@@ -2140,7 +2283,12 @@ export async function previewCheckoutPricing(input) {
         pointsApplied,
         // Equal to `total` when no points apply, so every existing reader of
         // either figure keeps getting the right number.
-        amountDue: roundRupees(total - pointsApplied),
+        /*
+         * 🛑 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,
     };
@@ -2292,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, useAllPoints, pointsBudget, } = 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
@@ -2308,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, acceptsPoints, sharedPurchaseRates } = 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
@@ -2446,7 +2617,7 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
     });
     // 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 + phonepeSharedQuote.total);
+    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 ───────
      *
@@ -2463,7 +2634,7 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
      */
     const pointsOptedIn = useAllPoints === true;
     const pointsAccepted = pointsOptedIn && acceptsPoints;
-    const { pointsApplied, amountDue } = resolvePointsTender({
+    const { pointsApplied } = resolvePointsTender({
         orderTotal,
         balance: pointsAccepted ? pointsBudget.remaining : 0,
         accepted: pointsAccepted,
@@ -2471,17 +2642,37 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
     });
     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
@@ -2510,7 +2701,13 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         // 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,
-        amountDue: pointsApplied > 0 ? amountDue : 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,
@@ -2599,7 +2796,12 @@ async function createPhonePeGroupOrder(group, orderType, ctx) {
         // 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.
-        placeOfSupply: buyerState || undefined,
+        /*
+         * 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,
@@ -2871,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) {
@@ -2885,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
@@ -3034,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.
@@ -3105,22 +3345,28 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
                         lineTotal: lineTotalFor(item, product),
                     })),
                 }))).perGroup;
-                const guardBases = expectedShippingGroups.map((g, i) => {
-                    const storeId = g.items[0].item.storeId;
+                /*
+                 * 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] ?? {};
-                    const goods = guardSubtotals[i][1];
-                    const share = guardFeeByGroup.get(storeId);
-                    const groupAddons = computeGiftWrapFee(addons.giftWrapAddon ?? false, commissionRates) +
-                        computeShipmentProtectionFee(goods, addons.shipmentProtectionAddon ?? false, commissionRates);
-                    return {
-                        total: roundRupees(Math.max(0, goods - (guardCouponByGroup[i]?.couponDiscount ?? 0)) +
-                            (expectedShippingFees[i]?.shippingFee ?? 0) +
-                            groupAddons +
-                            (share?.platformFee ?? 0) +
-                            (share?.gstOnFee ?? 0)),
-                        accepted: expectedShippingFees[i]?.acceptsPoints === true,
-                    };
-                });
+                    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;
             }
         }
@@ -3128,7 +3374,9 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
             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
@@ -3244,6 +3492,13 @@ export async function verifyAndPlaceGatewayOrderAction(input) {
             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);