(null);
const [useReferralCredits, setUseReferralCredits] = useState(false);
+ // #1365 — GST place of supply. Blank is the statutory s.12(2)(b) default, so
+ // this never blocks checkout.
+ const billingState = useBillingState(checkoutTaxContext.billingStateCode);
const [selectedOrganizationId, setSelectedOrganizationId] = useState<
string | null
>(null);
@@ -188,7 +214,7 @@ export default function ConsultationCheckoutPage({
);
}
} catch (error) {
- Sentry.captureException(error instanceof Error ? error : new Error(String(error)), { tags: { subsystem: "payments" } });
+ reportPaymentsError(error);
console.error("Error fetching referral credits:", error);
} finally {
setIsLoadingCredits(false);
@@ -269,7 +295,10 @@ export default function ConsultationCheckoutPage({
);
const handleCheckout = useCallback(
- async (gateway: SupportedCheckoutGateway, isMockPayment: boolean = false) => {
+ async (
+ gateway: SupportedCheckoutGateway,
+ isMockPayment: boolean = false,
+ ) => {
// Block checkout during maintenance mode
if (isMaintenanceBlocked) {
toast({
@@ -317,6 +346,7 @@ export default function ConsultationCheckoutPage({
? false
: useReferralCredits,
organizationId: selectedOrganizationId ?? undefined,
+ ...billingState.bodyField,
});
// Make single API call - backend decides dev vs prod flow
@@ -356,11 +386,7 @@ export default function ConsultationCheckoutPage({
) {
toast({
title: "✅ Consultation Booked Successfully!",
- description: data.isZeroAmountPayment
- ? "Payment completed via referral credits. Your consultation has been confirmed."
- : data.isMockPayment
- ? "Mock payment processed. Your consultation has been confirmed. Check your dashboard for details."
- : "Your consultation has been confirmed. Check your dashboard for details.",
+ description: gatewaylessConfirmationText(data),
variant: "default",
});
@@ -371,7 +397,7 @@ export default function ConsultationCheckoutPage({
} catch (error) {
// Only fires for unexpected errors (network failure, JSON parse error, etc.)
// API errors are handled above with handleApiError() + return
- Sentry.captureException(error instanceof Error ? error : new Error(String(error)), { tags: { subsystem: "payments" } });
+ reportPaymentsError(error);
toast({
title: "Checkout Failed",
description:
@@ -394,6 +420,7 @@ export default function ConsultationCheckoutPage({
appliedDiscount,
useReferralCredits,
selectedOrganizationId,
+ billingState.bodyField,
validatedSearchParams,
currency,
handleApiError,
@@ -443,7 +470,7 @@ export default function ConsultationCheckoutPage({
const reviewsData = await fetchReviews(data.data.consultantProfile.id);
setReviews(reviewsData);
} catch (error) {
- Sentry.captureException(error instanceof Error ? error : new Error(String(error)), { tags: { subsystem: "payments" } });
+ reportPaymentsError(error);
console.error("[Checkout] Error fetching event data:", error);
setError(
error instanceof Error
@@ -627,14 +654,15 @@ export default function ConsultationCheckoutPage({
Date
{validatedSearchParams
- ? new Date(
- validatedSearchParams.startsAt,
- ).toLocaleDateString(undefined, {
- weekday: "long",
- year: "numeric",
- month: "long",
- day: "numeric",
- })
+ ? new Date(validatedSearchParams.startsAt).toLocaleDateString(
+ undefined,
+ {
+ weekday: "long",
+ year: "numeric",
+ month: "long",
+ day: "numeric",
+ },
+ )
: "—"}
@@ -684,6 +712,11 @@ export default function ConsultationCheckoutPage({
}}
/>
+
+
Discount Codes
@@ -829,6 +862,12 @@ export default function ConsultationCheckoutPage({
: formatPrice(pricing.total)}
+ {!isLicenseCovered && (
+
+ )}
{isLicenseCovered && (
Session value {formatPrice(pricing.total)} — covered by
@@ -845,23 +884,12 @@ export default function ConsultationCheckoutPage({
Select your preferred payment method
- {[
- {
- name: "Stripe",
- description: "Card payments (international)",
- gateway: "STRIPE" as const,
- isActive: true,
- },
- {
- name: "Razorpay",
- description: "UPI, cards & bank transfer",
- gateway: "RAZORPAY" as const,
- isActive: true,
- },
- ].map((gateway) => (
+ {paymentGateways.map((gateway) => (
- {gateway.name}
+
+ {gateway.name}
+
@@ -885,10 +913,8 @@ export default function ConsultationCheckoutPage({
appointmentType: "CONSULTATION",
planId: resolvedParams.planId,
paymentGateway: "RAZORPAY",
- startsAt:
- validatedSearchParams.startsAt,
- endsAt:
- validatedSearchParams.endsAt,
+ startsAt: validatedSearchParams.startsAt,
+ endsAt: validatedSearchParams.endsAt,
slotOfAvailabilityWeeklyId:
validatedSearchParams.slotOfAvailabilityWeeklyId,
slotOfAvailabilityCustomId:
@@ -900,6 +926,7 @@ export default function ConsultationCheckoutPage({
? false
: useReferralCredits,
organizationId: selectedOrganizationId ?? undefined,
+ ...billingState.bodyField,
})}
onPaymentSuccess={(response: {
razorpay_payment_id?: string;
@@ -934,10 +961,8 @@ export default function ConsultationCheckoutPage({
appointmentType: "CONSULTATION",
planId: resolvedParams.planId,
paymentGateway: "STRIPE",
- startsAt:
- validatedSearchParams.startsAt,
- endsAt:
- validatedSearchParams.endsAt,
+ startsAt: validatedSearchParams.startsAt,
+ endsAt: validatedSearchParams.endsAt,
slotOfAvailabilityWeeklyId:
validatedSearchParams.slotOfAvailabilityWeeklyId,
slotOfAvailabilityCustomId:
@@ -949,6 +974,7 @@ export default function ConsultationCheckoutPage({
? false
: useReferralCredits,
organizationId: selectedOrganizationId ?? undefined,
+ ...billingState.bodyField,
})}
onPaymentSuccess={(response: {
message?: string;
diff --git a/app/checkout/plans/subscription/[planId]/page.tsx b/app/checkout/plans/subscription/[planId]/page.tsx
index 3bfeb9aaa..9c01aaba6 100644
--- a/app/checkout/plans/subscription/[planId]/page.tsx
+++ b/app/checkout/plans/subscription/[planId]/page.tsx
@@ -1,6 +1,5 @@
"use client";
-import * as Sentry from "@sentry/nextjs";
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
import { Button } from "@/components/ui/button";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
@@ -21,6 +20,11 @@ import {
} from "@/schemas/checkout";
import type { AppliedDiscount } from "@/types/checkout";
import { OrgPayerSelector } from "@/app/checkout/components/OrgPayerSelector";
+import { FxEstimateNote } from "@/app/checkout/components/FxEstimateNote";
+import {
+ BillingStateSelect,
+ useBillingState,
+} from "@/app/checkout/components/BillingStateSelect";
import {
ConsultantProfile,
ConsultantReview,
@@ -35,13 +39,16 @@ import {
createHandleApiError,
createRazorpayCheckoutHandlers,
createStripeCheckoutHandlers,
+ paymentGateways,
} from "../../utils";
import { calculatePricing, formatPercentage } from "../../math";
import { useCurrency } from "@/hooks/useCurrency";
import { useCheckoutTaxContext } from "../../useCheckoutTaxContext";
-import { mintClientIdempotencyKey,
+import {
+ mintClientIdempotencyKey,
busyRetryToast,
fetchCheckoutWithBusyRetry,
+ reportPaymentsError,
} from "@/app/checkout/plans/utils";
// price arrives as number: extended client + JSON serialization (#780)
@@ -98,6 +105,9 @@ export default function SubscriptionCheckoutPage({
const [isApplyingDiscount, setIsApplyingDiscount] = useState(false);
const [discountError, setDiscountError] = useState
(null);
const [useReferralCredits, setUseReferralCredits] = useState(false);
+ // #1365 — GST place of supply. Blank is the statutory s.12(2)(b) default, so
+ // this never blocks checkout.
+ const billingState = useBillingState(checkoutTaxContext.billingStateCode);
const [selectedOrganizationId, setSelectedOrganizationId] = useState<
string | null
>(null);
@@ -202,7 +212,7 @@ export default function SubscriptionCheckoutPage({
);
}
} catch (error) {
- Sentry.captureException(error instanceof Error ? error : new Error(String(error)), { tags: { subsystem: "payments" } });
+ reportPaymentsError(error);
console.error("Error fetching referral credits:", error);
} finally {
setIsLoadingCredits(false);
@@ -236,7 +246,10 @@ export default function SubscriptionCheckoutPage({
);
const handleCheckout = useCallback(
- async (gateway: SupportedCheckoutGateway, isMockPayment: boolean = false) => {
+ async (
+ gateway: SupportedCheckoutGateway,
+ isMockPayment: boolean = false,
+ ) => {
// Block checkout during maintenance mode
if (isMaintenanceBlocked) {
toast({
@@ -301,6 +314,7 @@ export default function SubscriptionCheckoutPage({
? false
: useReferralCredits,
organizationId: selectedOrganizationId ?? undefined,
+ ...billingState.bodyField,
});
// Make API call - backend decides dev vs prod flow
@@ -351,7 +365,7 @@ export default function SubscriptionCheckoutPage({
handleApiError({ error: data.error, errorType: data.errorType });
}
} catch (error) {
- Sentry.captureException(error instanceof Error ? error : new Error(String(error)), { tags: { subsystem: "payments" } });
+ reportPaymentsError(error);
console.error("Checkout error:", error);
if (error instanceof Error) {
toast({
@@ -375,6 +389,7 @@ export default function SubscriptionCheckoutPage({
appliedDiscount,
useReferralCredits,
selectedOrganizationId,
+ billingState.bodyField,
effectiveSearchParams,
currency,
handleApiError,
@@ -405,7 +420,7 @@ export default function SubscriptionCheckoutPage({
const reviewsData = await fetchReviews(data.data.consultantProfile.id);
setReviews(reviewsData);
} catch (error) {
- Sentry.captureException(error instanceof Error ? error : new Error(String(error)), { tags: { subsystem: "payments" } });
+ reportPaymentsError(error);
console.error("Error fetching plan data:", error);
setError(
error instanceof Error
@@ -657,6 +672,11 @@ export default function SubscriptionCheckoutPage({
}}
/>
+
+
Discount Codes
@@ -787,7 +807,9 @@ export default function SubscriptionCheckoutPage({
(planData?.data?.sessionDurationInHours || 1)}{" "}
hours)
-
{planData?.data?.sessionsPerWeek || 1} sessions per week
+
+ {planData?.data?.sessionsPerWeek || 1} sessions per week
+
{planData?.data?.sessionDurationInHours || 1} hour
sessions
@@ -831,6 +853,10 @@ export default function SubscriptionCheckoutPage({
Total
{formatPrice(pricing.total)}
+
@@ -841,23 +867,12 @@ export default function SubscriptionCheckoutPage({
Select your preferred payment method
@@ -892,6 +907,7 @@ export default function SubscriptionCheckoutPage({
? false
: useReferralCredits,
organizationId: selectedOrganizationId ?? undefined,
+ ...billingState.bodyField,
})}
onPaymentSuccess={razorpayHandlers.onPaymentSuccess}
onPaymentError={razorpayHandlers.onPaymentError}
@@ -915,6 +931,7 @@ export default function SubscriptionCheckoutPage({
? false
: useReferralCredits,
organizationId: selectedOrganizationId ?? undefined,
+ ...billingState.bodyField,
})}
onPaymentSuccess={stripeHandlers.onPaymentSuccess}
onPaymentError={stripeHandlers.onPaymentError}
diff --git a/app/checkout/plans/useCheckoutTaxContext.ts b/app/checkout/plans/useCheckoutTaxContext.ts
index 9429ac70f..e734aa568 100644
--- a/app/checkout/plans/useCheckoutTaxContext.ts
+++ b/app/checkout/plans/useCheckoutTaxContext.ts
@@ -7,12 +7,15 @@ type CheckoutTaxContext = {
isInternational: boolean;
/** Server-decided (#1230): international AND a valid platform LUT exists. */
exportZeroRated: boolean;
+ /** #1365 — remembered GST billing state, used to pre-fill the picker. */
+ billingStateCode: string | null;
};
const DEFAULT_CONTEXT: CheckoutTaxContext = {
buyerCountry: "IN",
isInternational: false,
exportZeroRated: false,
+ billingStateCode: null,
};
export function useCheckoutTaxContext() {
diff --git a/app/checkout/plans/utils.ts b/app/checkout/plans/utils.ts
index e02994943..d7e287fb7 100644
--- a/app/checkout/plans/utils.ts
+++ b/app/checkout/plans/utils.ts
@@ -1,11 +1,24 @@
"use client";
+import * as Sentry from "@sentry/nextjs";
import { useToast } from "@/hooks/use-toast";
import { getErrorToast } from "@/lib/errors/mapping/payment-error-toast-map";
import { ErrorTypes } from "@/lib/errors/classification/payment-error-classification";
import { CheckoutInput, checkoutResponseSchema } from "@/schemas/checkout";
import { PaymentGateway } from "@prisma/client";
+// #1396 — every checkout page and both gateway components caught an
+// unexpected error the same way; centralising it removed the repeated
+// three-line block flagged as duplication rather than leaving the copies.
+export function reportPaymentsError(error: unknown): void {
+ Sentry.captureException(
+ error instanceof Error ? error : new Error(String(error)),
+ {
+ tags: { subsystem: "payments" },
+ },
+ );
+}
+
export function loadScript(src: string): Promise
{
return new Promise((resolve, reject) => {
const script = document.createElement("script");
@@ -40,7 +53,6 @@ export function createHandleApiError(
};
}
-
// #828 — one key per logical checkout attempt (stable across double-clicks
// and network retries within a mount; a fresh mount = a fresh attempt). The
// server CASes on Payment.clientIdempotencyKey and replays the original
@@ -81,7 +93,10 @@ export async function makeCheckoutRequest(
* commits or releases within seconds — yet they used to dead-end as terminal
* error toasts while the buyer watched a hot slot slip away.
*/
-const BUSY_ERROR_TYPES = new Set(["EVENT_CHECKOUT_BUSY", "CONSULTEE_BOOKING_BUSY"]);
+const BUSY_ERROR_TYPES = new Set([
+ "EVENT_CHECKOUT_BUSY",
+ "CONSULTEE_BOOKING_BUSY",
+]);
/** Never wait longer than this server-advised pause (function-ceiling friendly). */
const MAX_BUSY_WAIT_SECONDS = 20;
@@ -114,11 +129,18 @@ export async function fetchCheckoutWithBusyRetry(
return response;
}
const retryAfter = Number(body?.retryAfter);
- if (!body?.errorType || !BUSY_ERROR_TYPES.has(body.errorType) || !Number.isFinite(retryAfter)) {
+ if (
+ !body?.errorType ||
+ !BUSY_ERROR_TYPES.has(body.errorType) ||
+ !Number.isFinite(retryAfter)
+ ) {
return response;
}
- const waitSeconds = Math.min(Math.max(1, Math.round(retryAfter)), MAX_BUSY_WAIT_SECONDS);
+ const waitSeconds = Math.min(
+ Math.max(1, Math.round(retryAfter)),
+ MAX_BUSY_WAIT_SECONDS,
+ );
notifyBusy(waitSeconds);
await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
@@ -127,16 +149,16 @@ export async function fetchCheckoutWithBusyRetry(
}
/** Shared copy for the during-wait notice so all four surfaces sound alike. */
-export function busyRetryToast(
- waitSeconds: number,
-): { title: string; description: string } {
+export function busyRetryToast(waitSeconds: number): {
+ title: string;
+ description: string;
+} {
return {
title: "Almost got it — someone is one step ahead",
description: `Your card has not been charged. Retrying automatically in ${waitSeconds}s…`,
};
}
-
// Common success handling logic for different appointment types
export function createHandleCheckoutSuccess(
toast: ReturnType["toast"],
@@ -243,17 +265,41 @@ export async function handleUnifiedCheckout(
}
}
-// Gateway configuration for UI rendering
+// #1437 — WALLET/INVOICE/LICENSE org funding, zero-amount (credits) and mock
+// payments all confirm synchronously server-side with a synthetic id and no
+// gateway order/client secret. Opening Razorpay/Stripe on that id 400s and
+// shows a false "Payment Failed" alert over a booking that already
+// succeeded, so every gateway component must check this before opening.
+export function checkoutNeedsGateway(data: {
+ skipPayment?: boolean;
+ isZeroAmountPayment?: boolean;
+ [key: string]: unknown;
+}): boolean {
+ return !(data.skipPayment || data.isZeroAmountPayment);
+}
+
+// Gateway configuration for UI rendering. The four checkout pages each carried
+// their own copy of this array with `isActive: true` hardcoded on both entries,
+// so the fence had to be applied in four places to hold. One list now.
+//
+// #1351 — Stripe is a contingency rail kept in the tree in case RBI rules
+// change, not a live payment method: without NEXT_PUBLIC_STRIPE_ENABLED=true
+// the card renders the disabled "Coming Soon" button and no StripeCheckout
+// mounts. The server-side fence (STRIPE_ENABLED, assertGatewayUsable) is the
+// one that actually protects money; this only keeps the UI honest, because a
+// NEXT_PUBLIC_ value is inlined into the client bundle and a buyer can edit it.
export const paymentGateways = [
{
name: "Stripe",
description: "Card payments (international)",
gateway: "STRIPE" as const,
+ isActive: process.env.NEXT_PUBLIC_STRIPE_ENABLED === "true",
},
{
name: "Razorpay",
description: "UPI, cards & bank transfer",
gateway: "RAZORPAY" as const,
+ isActive: true,
},
];
@@ -270,7 +316,12 @@ export function createStripeCheckoutHandlers(
});
window.location.href = "/checkout/checkout-success";
},
- onPaymentError: (error: { message?: string; code?: string; errorType?: string; error?: string }) => {
+ onPaymentError: (error: {
+ message?: string;
+ code?: string;
+ errorType?: string;
+ error?: string;
+ }) => {
// Booking-conflict errors from /api/checkout (slot taken/relinquished,
// event expired) carry our own errorType — route them through the precise
// toast map instead of the gateway card-decline heuristics.
diff --git a/app/checkout/plans/webinar/[planId]/page.tsx b/app/checkout/plans/webinar/[planId]/page.tsx
index a5a51855e..a83815dc2 100644
--- a/app/checkout/plans/webinar/[planId]/page.tsx
+++ b/app/checkout/plans/webinar/[planId]/page.tsx
@@ -1,6 +1,5 @@
"use client";
-import * as Sentry from "@sentry/nextjs";
import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
import { Button } from "@/components/ui/button";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
@@ -28,6 +27,8 @@ import {
createRazorpayCheckoutHandlers,
createStripeCheckoutHandlers,
handleUnifiedCheckout,
+ paymentGateways,
+ reportPaymentsError,
} from "../../utils";
import { calculatePricing, formatPercentage } from "../../math";
import { getWebinarCapacity } from "@/lib/events/capacity";
@@ -35,6 +36,11 @@ import { useCurrency } from "@/hooks/useCurrency";
import { useCheckoutTaxContext } from "../../useCheckoutTaxContext";
import type { AppliedDiscount } from "@/types/checkout";
import { OrgPayerSelector } from "@/app/checkout/components/OrgPayerSelector";
+import { FxEstimateNote } from "@/app/checkout/components/FxEstimateNote";
+import {
+ BillingStateSelect,
+ useBillingState,
+} from "@/app/checkout/components/BillingStateSelect";
import type {
Appointment,
@@ -119,6 +125,9 @@ export default function WebinarCheckoutPage({
const [isApplyingDiscount, setIsApplyingDiscount] = useState(false);
const [discountError, setDiscountError] = useState(null);
const [useReferralCredits, setUseReferralCredits] = useState(false);
+ // #1365 — GST place of supply. Blank is the statutory s.12(2)(b) default, so
+ // this never blocks checkout.
+ const billingState = useBillingState(checkoutTaxContext.billingStateCode);
const [selectedOrganizationId, setSelectedOrganizationId] = useState<
string | null
>(null);
@@ -194,10 +203,7 @@ export default function WebinarCheckoutPage({
);
}
} catch (error) {
- Sentry.captureException(
- error instanceof Error ? error : new Error(String(error)),
- { tags: { subsystem: "payments" } },
- );
+ reportPaymentsError(error);
console.error("Error fetching referral credits:", error);
} finally {
setIsLoadingCredits(false);
@@ -290,6 +296,7 @@ export default function WebinarCheckoutPage({
? false
: useReferralCredits,
organizationId: selectedOrganizationId ?? undefined,
+ ...billingState.bodyField,
});
// Handle unified checkout flow using the utility
@@ -301,10 +308,7 @@ export default function WebinarCheckoutPage({
isMockPayment,
);
} catch (error) {
- Sentry.captureException(
- error instanceof Error ? error : new Error(String(error)),
- { tags: { subsystem: "payments" } },
- );
+ reportPaymentsError(error);
console.error("Checkout error:", error);
if (error instanceof Error) {
// Provide more informative error messages based on the error type
@@ -356,6 +360,7 @@ export default function WebinarCheckoutPage({
appliedDiscount,
useReferralCredits,
selectedOrganizationId,
+ billingState.bodyField,
validatedSearchParams,
currency,
],
@@ -415,11 +420,7 @@ export default function WebinarCheckoutPage({
} catch {
return true;
}
- }, [
- resolvedParams.planId,
- validatedSearchParams?.eventId,
- toast,
- ]);
+ }, [resolvedParams.planId, validatedSearchParams?.eventId, toast]);
useEffect(() => {
async function fetchPlanData() {
@@ -446,10 +447,7 @@ export default function WebinarCheckoutPage({
);
_setReviews(reviewsData);
} catch (error) {
- Sentry.captureException(
- error instanceof Error ? error : new Error(String(error)),
- { tags: { subsystem: "payments" } },
- );
+ reportPaymentsError(error);
console.error("Error fetching plan data:", error);
setError(
error instanceof Error
@@ -725,6 +723,11 @@ export default function WebinarCheckoutPage({
}}
/>
+
+
Discount Codes
@@ -879,6 +882,10 @@ export default function WebinarCheckoutPage({
Total
{formatPrice(pricing.total)}
+
@@ -889,20 +896,7 @@ export default function WebinarCheckoutPage({
Select your preferred payment method
@@ -390,6 +434,11 @@ export function PaymentsTab({ data }: { data: PaymentsData | undefined }) {
);
},
},
+ {
+ key: "invoice",
+ header: "Tax invoice",
+ cell: renderInvoiceCell,
+ },
{
key: "expires",
header: "Expires",
diff --git a/app/dashboard/organization/[orgId]/billing/BillingPageClient.tsx b/app/dashboard/organization/[orgId]/billing/BillingPageClient.tsx
index 90a23b994..41ad72d02 100644
--- a/app/dashboard/organization/[orgId]/billing/BillingPageClient.tsx
+++ b/app/dashboard/organization/[orgId]/billing/BillingPageClient.tsx
@@ -60,6 +60,7 @@ import type {
OrgReceivablesPayload,
} from "@/lib/data/org-receivables";
import { WalletTab } from "./WalletTab";
+import { BillingBlockBanner } from "@/components/billing/BillingBlockBanner";
// ---------------------------------------------------------------------------
// Zod schemas — narrow API responses at the network boundary so the rest
@@ -67,6 +68,12 @@ import { WalletTab } from "./WalletTab";
// ---------------------------------------------------------------------------
const billingSummarySchema = z.object({
+ // #1427/#1430 — resolved server-side next to the account read; see
+ // app/api/organizations/[orgId]/billing/route.ts.
+ walletFrozen: z.boolean().default(false),
+ walletFrozenReason: z.string().nullable().default(null),
+ dunningSuspended: z.boolean().default(false),
+ dunningSuspendedInvoiceNumber: z.string().nullable().default(null),
fundingSource: z
.enum(["PERSONAL", "WALLET", "INVOICE", "LICENSE"])
.nullable(),
@@ -345,12 +352,23 @@ export function BillingPageClient({
staleTime: 60_000,
});
const orgStatus = orgDetails.data?.organization.status;
+ // #1427/#1430 — a frozen wallet or a dunning-suspended org blocks the same
+ // pay/top-up affordances as an unverified org; fold both into the one
+ // gate rather than leaving the buttons live until checkout rejects them.
+ const walletFrozen = summary.data?.walletFrozen ?? false;
+ const dunningSuspended = summary.data?.dunningSuspended ?? false;
const moneyMoveBlocked =
- orgStatus === "PENDING_VERIFICATION" || orgStatus === "SUSPENDED";
- const moneyMoveReason =
- orgStatus === "SUSPENDED"
- ? "Organization suspended"
- : "Verify your organization to move money";
+ orgStatus === "PENDING_VERIFICATION" ||
+ orgStatus === "SUSPENDED" ||
+ walletFrozen ||
+ dunningSuspended;
+ const moneyMoveReason = walletFrozen
+ ? (summary.data?.walletFrozenReason ?? "Wallet spend is frozen")
+ : dunningSuspended
+ ? "Bookings are paused until the overdue invoice is settled"
+ : orgStatus === "SUSPENDED"
+ ? "Organization suspended"
+ : "Verify your organization to move money";
const generateMutation = useMutation({
mutationFn: () => generateInvoice(orgId),
@@ -826,9 +844,19 @@ export function BillingPageClient({
)}
+ {/* #1427/#1430 — the freeze/dunning states get the shared
+ banner (with the support link); org-verification status
+ keeps its own inline reason below. */}
+
+
{/* #779 §B: org can't move money until ACTIVE; surface the reason
inline so the disabled Pay/Top-up affordances aren't silent. */}
- {moneyMoveBlocked && (
+ {moneyMoveBlocked && !walletFrozen && !dunningSuspended && (
diff --git a/app/dashboard/organization/[orgId]/home/FinanceLeadViewCard.tsx b/app/dashboard/organization/[orgId]/home/FinanceLeadViewCard.tsx
index cb076acc2..d6c3efa45 100644
--- a/app/dashboard/organization/[orgId]/home/FinanceLeadViewCard.tsx
+++ b/app/dashboard/organization/[orgId]/home/FinanceLeadViewCard.tsx
@@ -20,6 +20,7 @@
import Link from "next/link";
import { useRouter } from "next/navigation";
+import { useQuery } from "@tanstack/react-query";
import {
CreditCard,
Wallet,
@@ -39,6 +40,7 @@ import { StatCard } from "@/components/dashboard/StatCard";
import { Button } from "@/components/ui/button";
import { DashboardGrid } from "@/components/dashboard/PageScaffold";
import { formatCurrencyAmount } from "@/utils/formatting";
+import { BillingBlockBanner } from "@/components/billing/BillingBlockBanner";
/**
* Shape mirrors the live `/api/organizations/[orgId]/analytics` payload
@@ -72,6 +74,23 @@ export function FinanceLeadViewCard({ orgId, data }: FinanceLeadViewProps) {
const billingHref = `/dashboard/organization/${orgId}/billing`;
const pastDueCount = data.invoices?.pastDueCount ?? 0;
+ // #1427/#1430 — same query key as BillingPageClient's `fetchBilling`
+ // (["org-billing", orgId]), so the two share react-query's cache instead
+ // of double-fetching when a finance lead lands here first. The route is
+ // a cheap DB-side aggregate, not the heavier analytics payload above.
+ const billingBlock = useQuery({
+ queryKey: ["org-billing", orgId],
+ queryFn: async () => {
+ const res = await fetch(`/api/organizations/${orgId}/billing`);
+ if (!res.ok) throw new Error("Failed to load billing status");
+ return (await res.json()) as {
+ walletFrozen: boolean;
+ walletFrozenReason: string | null;
+ dunningSuspended: boolean;
+ };
+ },
+ });
+
const stats: Array<{
label: string;
value: string;
@@ -97,9 +116,7 @@ export function FinanceLeadViewCard({ orgId, data }: FinanceLeadViewProps) {
value: data.wallet
? formatCurrencyAmount(data.wallet.balancePaise, currency)
: "—",
- subtitle: data.wallet
- ? "Available to debit"
- : "No wallet configured",
+ subtitle: data.wallet ? "Available to debit" : "No wallet configured",
icon: Wallet,
href: `/dashboard/organization/${orgId}/billing?tab=wallet`,
cta: "Top up wallet",
@@ -124,14 +141,23 @@ export function FinanceLeadViewCard({ orgId, data }: FinanceLeadViewProps) {
return (
<>
+ {billingBlock.data && (
+
+ )}
+
Finance overview
- Everything you can act on as the finance lead — invoices to
- chase, payouts to approve, wallet headroom, PO burndown.
- Member and SSO surfaces are intentionally hidden; coordinate
- with your OWNER for those.
+ Everything you can act on as the finance lead — invoices to chase,
+ payouts to approve, wallet headroom, PO burndown. Member and SSO
+ surfaces are intentionally hidden; coordinate with your OWNER for
+ those.
@@ -158,9 +184,7 @@ export function FinanceLeadViewCard({ orgId, data }: FinanceLeadViewProps) {
variant={
isOutstanding && pastDueCount > 0 ? "danger" : "default"
}
- onClick={
- deepLinks ? () => router.push(stat.href) : undefined
- }
+ onClick={deepLinks ? () => router.push(stat.href) : undefined}
/>
{/* Past-due needs more than a number — give the finance lead a
one-click jump to the invoices they have to chase. */}
@@ -200,13 +224,17 @@ export function FinanceLeadViewCard({ orgId, data }: FinanceLeadViewProps) {
))}
+ {/* #1396 — this is the headline price of a plan the server will
+ charge, so it renders in the plan's own currency, exactly as
+ the trial price above it does for the reason given at #1167.
+ `formatPrice` took INR paise and applied the viewer's FX rate,
+ which relabelled the plan and disagreed with the trial line
+ two elements away. */}
- {formatPrice(option.price)}
+ {formatCurrencyAmount(option.price, option.priceCurrency || "INR")}
/ month
diff --git a/bugs/compliance/b2c-vs-b2b-gaps.md b/bugs/compliance/b2c-vs-b2b-gaps.md
index 6da6eb71a..6c69a4f34 100644
--- a/bugs/compliance/b2c-vs-b2b-gaps.md
+++ b/bugs/compliance/b2c-vs-b2b-gaps.md
@@ -1,5 +1,7 @@
# B2C vs B2B Compliance Gaps
+> **Verdict pass 2026-09-03/04.** Every money claim in this file was re-checked against `dev@e1766fa2d` and the live database as part of the 2026-09-03 finance-subsystem verification. Of 9 claims, 3 are still true today, 3 have been addressed since this dossier was written, and 3 are stale. See [`docs/payments/audits/2026-09-03-finance-verdicts.md`](../../docs/payments/audits/2026-09-03-finance-verdicts.md) for the per-item disposition.
+
## Context
Enterprise rail: org tax info, invoices, credit notes, MSME alerts, org payout TDS, audit export. Marketplace rail: consultant verification (manual), PAN encryption, payout tax fields — but filing automation and TCS lag. Shipping checklist grades MUST vs DEFER in `docs/compliance/15-india-compliance-shipping-checklist.md`.
@@ -8,20 +10,20 @@ Enterprise rail: org tax info, invoices, credit notes, MSME alerts, org payout T
Triaged 2026-07-12 against real code (3 verifier agents cross-checked every claim); fix wave PRs #981–#994 shipped. This dossier's claims map as follows:
-| Claim (short) | Verdict |
-|---|---|
-| Dual TDS engines (#778 planned consolidation) | ❌ STALE — consultant path is already 194-O via `computeTdsForPayout`; `tds-service.ts` is FY-helper/audit only |
-| No GSTR-8 aggregator job | 🟡 LEGIT-DEFERRED |
-| Refund tax adjustment wiring gaps | ❌ OVERSTATED — TdsAdjustment (via reversal) and GstTcsAdjustment are both wired from `refund.ts`; only monthly `GstTcsBatch` collection deferred |
-| Seller disclosure (name/address/GSTIN on public profiles) incomplete | 🟡 LEGIT-DEFERRED |
-| RBI PA Path C needs legal confirmation | 🎯 legal/CA gate, not code |
-| Form 26Q/140 automation missing | 🔵 TRACKED #737 (code cites #737; audit said #738) |
+| Claim (short) | Verdict |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Dual TDS engines (#778 planned consolidation) | ❌ STALE — consultant path is already 194-O via `computeTdsForPayout`; `tds-service.ts` is FY-helper/audit only |
+| No GSTR-8 aggregator job | 🟡 LEGIT-DEFERRED |
+| Refund tax adjustment wiring gaps | ❌ OVERSTATED — TdsAdjustment (via reversal) and GstTcsAdjustment are both wired from `refund.ts`; only monthly `GstTcsBatch` collection deferred |
+| Seller disclosure (name/address/GSTIN on public profiles) incomplete | 🟡 LEGIT-DEFERRED |
+| RBI PA Path C needs legal confirmation | 🎯 legal/CA gate, not code |
+| Form 26Q/140 automation missing | 🔵 TRACKED #737 (code cites #737; audit said #738) |
## Known gaps / bugs
-- Dual TDS engines (#778 planned consolidation).
+- Dual TDS engines (#778 planned consolidation). The 2026-09-03 verdict pass marked this stale: the consultant path already runs 194-O via `computeTdsForPayout`, so `tds-service.ts` is FY-helper/audit-only, not a live second engine.
- No GSTR-8 aggregator job.
-- Refund tax adjustment wiring gaps.
+- Refund tax adjustment wiring gaps. The 2026-09-03 verdict pass marked this overstated: `TdsAdjustment` (reversal) and `GstTcsAdjustment` are both wired from `refund.ts`; only the monthly `GstTcsBatch` collection is deferred.
- Seller disclosure (legal name, address, GSTIN on public profiles) incomplete for e-commerce rules.
- RBI PA Path C needs legal confirmation (finance pack).
- Form 26Q/140 automation missing before quarterly deadlines.
@@ -33,31 +35,34 @@ Triaged 2026-07-12 against real code (3 verifier agents cross-checked every clai
## Questions (handled?)
-1. **Block B2C payouts until 194-O unified + TCS plan?**
- - A) Hard block
- - B) Soft warn + CA escrow
- - C) Proceed with documented risk acceptance
+1. **Block B2C payouts until 194-O unified + TCS plan?**
+ - A) Hard block
+ - B) Soft warn + CA escrow
+ - C) Proceed with documented risk acceptance
+
+**Recommendation: A.** Unify TDS before B2C payouts — wrong 194-O path is not acceptable risk at scale.
-**Recommendation: A.** Unify TDS before B2C payouts — wrong 194-O path is not acceptable risk at scale.
-- Not B: Soft warn still pays out on the wrong engine.
+- Not B: Soft warn still pays out on the wrong engine.
- Not C: Documented risk acceptance does not fix GSTN notices to consultants.
-2. **Public seller disclosure minimum on consultant profile?**
- - A) Legal name + address + GSTIN if registered
- - B) Display name only
- - C) Disclosure only at checkout
+2. **Public seller disclosure minimum on consultant profile?**
+ - A) Legal name + address + GSTIN if registered
+ - B) Display name only
+ - C) Disclosure only at checkout
-**Recommendation: A.** E-commerce seller disclosure belongs on the public profile, not only at payment.
-- Not B: Display name alone fails consumer disclosure expectations.
+**Recommendation: A.** E-commerce seller disclosure belongs on the public profile, not only at payment.
+
+- Not B: Display name alone fails consumer disclosure expectations.
- Not C: Checkout-only disclosure is easy to miss and weak for trust/browse.
-3. **Who files quarterly TDS returns?**
- - A) In-house automation
- - B) CA retainer
- - C) Hybrid export + CA upload
+3. **Who files quarterly TDS returns?**
+ - A) In-house automation
+ - B) CA retainer
+ - C) Hybrid export + CA upload
+
+**Recommendation: C.** Hybrid export + CA upload is the realistic interim until Form 26Q automation is trustworthy.
-**Recommendation: C.** Hybrid export + CA upload is the realistic interim until Form 26Q automation is trustworthy.
-- Not A: Full in-house automation is not ready before quarterly deadlines.
+- Not A: Full in-house automation is not ready before quarterly deadlines.
- Not B: CA-only without clean exports recreates spreadsheet chaos.
## High concurrency / multi-device
diff --git a/bugs/cross-cutting/deadlocks-and-inconsistencies.md b/bugs/cross-cutting/deadlocks-and-inconsistencies.md
index 0bf29fe71..47847a014 100644
--- a/bugs/cross-cutting/deadlocks-and-inconsistencies.md
+++ b/bugs/cross-cutting/deadlocks-and-inconsistencies.md
@@ -1,5 +1,7 @@
# Cross-Cutting — Deadlocks & Inconsistencies
+> **Verdict pass 2026-09-03/04.** Every money-related claim in this file was re-checked against `dev@e1766fa2d` and the live database as part of the 2026-09-03 finance-subsystem verification. Of 8 claims, 4 are still true today, 3 have been addressed since this dossier was written, and 1 are stale. See [`docs/payments/audits/2026-09-03-finance-verdicts.md`](../../docs/payments/audits/2026-09-03-finance-verdicts.md) for the per-item disposition.
+
## Context
Familiarise avoids classic DB deadlocks with documented Redis lock ordering (consultant/event → consultee → slot) and sorted ledger account updates. Residual pain is less “DB deadlock” and more **distributed inconsistency windows**, **doc/code drift**, and **asymmetric fail modes**.
@@ -8,21 +10,21 @@ Familiarise avoids classic DB deadlocks with documented Redis lock ordering (con
Triaged 2026-07-12 against real code (3 verifier agents cross-checked every claim); fix wave PRs #981–#994 shipped. This dossier's claims map as follows:
-| Claim (short) | Verdict |
-|---|---|
-| Payment Phase-2 side effects outside confirm tx (skew healed by crons) | 🔵 by-design (ACK-before-complete + sweeper) |
-| Sorted ledger-account locking / deadlock avoidance | 🔵 by-design |
-| Consent "stub" comments vs live fail-closed checks | ✅ FIXED-BY #989 (checkConsent docstring corrected) |
-| `revokeSession` comment-only vs real mechanism | ✅ FIXED-BY #985 (comment corrected; true revoke follow-up #725) |
-| Payment critical-bugs task file vs fixed code (doc drift) | ✅ resolved (task file superseded; code fixed) |
-| Subscription status vs per-session slot after partial reschedule (#448) | ✅ FIXED-BY #988 |
-| Rating denormalization vs review rows | ✅ FIXED-BY #987 |
-| Wallet cache vs ledger journal drift | ✅ FIXED-BY #990 (freeze + page on reconcile `ok=false`) |
-| Stream call exists before MeetingSession row (orphan window) | 🟡 LEGIT-DEFERRED |
-| BetterAuth `Member` vs `Membership` dual source | 🟡 LEGIT-DEFERRED (large) |
-| SCIM/docs vs live implementation drift | 🟡 doc drift (SCIM implemented; docs say parked) |
-| Display currency vs INR settlement dual truth | 🔵 TRACKED #783 |
-| Novu vs Resend delivery split brain | 🟡 LEGIT-DEFERRED |
+| Claim (short) | Verdict |
+| ----------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Payment Phase-2 side effects outside confirm tx (skew healed by crons) | 🔵 by-design (ACK-before-complete + sweeper) |
+| Sorted ledger-account locking / deadlock avoidance | 🔵 by-design |
+| Consent "stub" comments vs live fail-closed checks | ✅ FIXED-BY #989 (checkConsent docstring corrected) |
+| `revokeSession` comment-only vs real mechanism | ✅ FIXED-BY #985 (comment corrected; true revoke follow-up #725) |
+| Payment critical-bugs task file vs fixed code (doc drift) | ✅ resolved (task file superseded; code fixed) |
+| Subscription status vs per-session slot after partial reschedule (#448) | ✅ FIXED-BY #988 |
+| Rating denormalization vs review rows | ✅ FIXED-BY #987 |
+| Wallet cache vs ledger journal drift | ✅ FIXED-BY #990 (freeze + page on reconcile `ok=false`) |
+| Stream call exists before MeetingSession row (orphan window) | 🟡 LEGIT-DEFERRED |
+| BetterAuth `Member` vs `Membership` dual source | 🟡 LEGIT-DEFERRED (large) |
+| SCIM/docs vs live implementation drift | 🟡 doc drift (SCIM implemented; docs say parked) |
+| Display currency vs INR settlement dual truth | 🔵 TRACKED #783 |
+| Novu vs Resend delivery split brain | 🟡 LEGIT-DEFERRED |
## Known gaps / bugs
@@ -42,7 +44,7 @@ Triaged 2026-07-12 against real code (3 verifier agents cross-checked every clai
- Subscription status vs per-session slot state after partial reschedule (#448).
- Rating denormalization vs review rows.
- Novu vs Resend delivery split brain.
-- SCIM/docs vs live implementation; payment critical-bugs task file vs fixed code; consent “stub” comments vs live checks.
+- SCIM/docs vs live implementation drift (doc drift only — SCIM is implemented). Payment critical-bugs task file vs fixed code and consent “stub” comments vs live checks are both resolved per the verdict table above.
### Dual sources of truth
@@ -61,52 +63,51 @@ Triaged 2026-07-12 against real code (3 verifier agents cross-checked every clai
## Questions (handled?)
-1. **How to govern new distributed locks?**
- - A) ADR + checklist in PR template
- - B) Central lock registry module only
- - C) Prefer DB constraints over new Redis locks
+1. **How to govern new distributed locks?**
+ - A) ADR + checklist in PR template
+ - B) Central lock registry module only
+ - C) Prefer DB constraints over new Redis locks
- **Recommendation: A.** Require an ADR plus PR-template checklist for every new distributed lock so order and fail-open/closed stay reviewable.
- - Not B: a registry without process still drifts when someone adds a lock ad hoc
- - Not C: DB constraints cannot cover Redis slot and appointment intent races
+ **Recommendation: A.** Require an ADR plus PR-template checklist for every new distributed lock so order and fail-open/closed stay reviewable.
+ - Not B: a registry without process still drifts when someone adds a lock ad hoc
+ - Not C: DB constraints cannot cover Redis slot and appointment intent races
-2. **Accept eventual consistency for Phase-2 side effects?**
- - A) Yes + status page + SLA
- - B) Move earnings inside confirm txn
- - C) Outbox pattern with visible pending
+2. **Accept eventual consistency for Phase-2 side effects?**
+ - A) Yes + status page + SLA
+ - B) Move earnings inside confirm txn
+ - C) Outbox pattern with visible pending
> 🎯 Locked: Phase-2 stays by-design ACK-before-complete with a sweeper/cron backstop; not moved into the confirm txn (B) and no new outbox this wave.
+ **Historical recommendation (2026-07-12): C.** Use an outbox (or explicit pending status) for Phase-2 earnings/notifications so users see “processing” instead of silent skew. This was superseded by the 2026-09-03 Locked decision above, which keeps ACK-before-complete with no new outbox this wave.
+ - Not A: a status page alone still leaves confirm→side-effect gaps invisible in-product
+ - Not B: stuffing earnings into confirm lengthens ACK windows and timeouts
- **Recommendation: C.** Use an outbox (or explicit pending status) for Phase-2 earnings/notifications so users see “processing” instead of silent skew.
- - Not A: a status page alone still leaves confirm→side-effect gaps invisible in-product
- - Not B: stuffing earnings into confirm lengthens ACK windows and timeouts
-
-3. **Doc drift process?**
- - A) Docs CI check against flags/paths
- - B) Quarterly audit only
- - C) Delete stale task files when fixed
+3. **Doc drift process?**
+ - A) Docs CI check against flags/paths
+ - B) Quarterly audit only
+ - C) Delete stale task files when fixed
- **Recommendation: C.** Delete stale task docs when bugs are fixed so ops never follows a runbook that disagrees with code.
- - Not A: full docs CI is heavier process than Familiarise needs right now
- - Not B: quarterly-only lets wrong payment/security docs linger for months
+ **Recommendation: C.** Delete stale task docs when bugs are fixed so ops never follows a runbook that disagrees with code.
+ - Not A: full docs CI is heavier process than Familiarise needs right now
+ - Not B: quarterly-only lets wrong payment/security docs linger for months
-4. **Unify dual truth pairs?**
- - A) Hard deprecate BetterAuth Member fields in app logic
- - B) Keep bridge forever
- - C) Generate Membership from Member only
+4. **Unify dual truth pairs?**
+ - A) Hard deprecate BetterAuth Member fields in app logic
+ - B) Keep bridge forever
+ - C) Generate Membership from Member only
- **Recommendation: A.** Hard-deprecate BetterAuth `Member` fields in app logic and lean on `Membership` — dual truth is how role bugs keep returning.
- - Not B: keeping the bridge forever preserves every UI misuse of the wrong role model
- - Not C: generating Membership from Member only still couples product auth to BetterAuth’s shape
+ **Recommendation: A.** Hard-deprecate BetterAuth `Member` fields in app logic and lean on `Membership` — dual truth is how role bugs keep returning.
+ - Not B: keeping the bridge forever preserves every UI misuse of the wrong role model
+ - Not C: generating Membership from Member only still couples product auth to BetterAuth’s shape
## High concurrency / multi-device
-Under spike, inconsistency windows lengthen (sweeper lag, pool wait, Stream breaker open). Multi-device users observe *different slices* of the window and conclude the system is random.
+Under spike, inconsistency windows lengthen (sweeper lag, pool wait, Stream breaker open). Multi-device users observe _different slices_ of the window and conclude the system is random.
## Suggested directions
-1. Outbox or explicit “pending side effects” for payment Phase-2.
-2. PR template: lock order + idempotency key + fail-open/closed choice.
-3. Monthly “doc drift” pass on flags, SCIM, payment bug register, compliance stubs.
+1. Outbox or explicit “pending side effects” for payment Phase-2.
+2. PR template: lock order + idempotency key + fail-open/closed choice.
+3. Monthly “doc drift” pass on flags, SCIM, payment bug register, compliance stubs.
4. Prefer one user-visible status model for “money vs booking vs meeting” alignment.
diff --git a/bugs/enterprise/compliance-kyb-gst-tds.md b/bugs/enterprise/compliance-kyb-gst-tds.md
index 3b29e751c..3988642f7 100644
--- a/bugs/enterprise/compliance-kyb-gst-tds.md
+++ b/bugs/enterprise/compliance-kyb-gst-tds.md
@@ -1,5 +1,7 @@
# Enterprise Compliance — KYB, GST, TDS, MSME, IRP
+> **Verdict pass 2026-09-03/04.** Every money claim in this file was re-checked against `dev@e1766fa2d` and the live database as part of the 2026-09-03 finance-subsystem verification. Of 12 claims, 7 are still true today, 4 have been addressed since this dossier was written, and 1 are stale. See [`docs/payments/audits/2026-09-03-finance-verdicts.md`](../../docs/payments/audits/2026-09-03-finance-verdicts.md) for the per-item disposition.
+
## Context
Enterprise buyers expect audit-ready invoices, TDS on org payouts, MSME timelines, and eventually IRN. Schema and helpers are deep ([`lib/compliance/`](../../lib/compliance/), org tax models, invoice counters). Several **gates are UI/docs only** — money APIs still move without KYB/domain hard checks. That is incompatible with “enterprise respect.”
@@ -8,30 +10,30 @@ Enterprise buyers expect audit-ready invoices, TDS on org payouts, MSME timeline
Triaged 2026-07-12 against real code (3 verifier agents cross-checked every claim); fix wave PRs #981–#994 shipped. This dossier's claims map as follows:
-| Claim (short) | Verdict |
-|---|---|
-| K-01 KYB not a hard gate on INVOICE | 🔵/✅ partial via #991 (domain gate) |
-| K-02 `assertVerifiedDomainOrThrow` unwired | ✅ FIXED-BY #991 (INVOICE now hard-requires verified domain) |
-| K-03 IRP uploader gated / stub | 🔵 TRACKED #713 |
-| K-04 `requireActive` inconsistent across money surfaces | 🟡 LEGIT-DEFERRED |
-| K-05 MSME §16 interest not accrued | 🟡 LEGIT-DEFERRED |
-| K-06 `TdsAdjustment` / Form 26Q export schema-only | 🔵 TRACKED #737 (audit cited #738 — misattribution) |
-| K-07 Dual TDS engines vs B2C deprecated 194J path | ❌ STALE (194-O already live via `computeTdsForPayout`) |
-| K-08 Invoice GST not per-line; credit-note length | 🟡 LEGIT-DEFERRED |
-| Refund tax cascade incomplete (implied) | ❌ OVERSTATED (`TdsAdjustment` + `GstTcsAdjustment` both wired) |
+| Claim (short) | Verdict |
+| ------------------------------------------------------- | --------------------------------------------------------------- |
+| K-01 KYB not a hard gate on INVOICE | 🔵/✅ partial via #991 (domain gate) |
+| K-02 `assertVerifiedDomainOrThrow` unwired | ✅ FIXED-BY #991 (INVOICE now hard-requires verified domain) |
+| K-03 IRP uploader gated / stub | 🔵 TRACKED #713 |
+| K-04 `requireActive` inconsistent across money surfaces | 🟡 LEGIT-DEFERRED |
+| K-05 MSME §16 interest not accrued | 🟡 LEGIT-DEFERRED |
+| K-06 `TdsAdjustment` / Form 26Q export schema-only | 🔵 TRACKED #737 (audit cited #738 — misattribution) |
+| K-07 Dual TDS engines vs B2C deprecated 194J path | ❌ STALE (194-O already live via `computeTdsForPayout`) |
+| K-08 Invoice GST not per-line; credit-note length | 🟡 LEGIT-DEFERRED |
+| Refund tax cascade incomplete (implied) | ❌ OVERSTATED (`TdsAdjustment` + `GstTcsAdjustment` both wired) |
## Known gaps / bugs
-| ID | Severity | Issue |
-|----|----------|-------|
-| K-01 | **P0** | `OrgKybVerification.kybVerifiedAt` / Sumsub fields — **not a hard gate** on INVOICE booking, invoice issue, or funding-source switch |
-| K-02 | **P1** | `assertVerifiedDomainOrThrow` for INVOICE_FUNDING **defined but unwired** on critical routes |
-| K-03 | **P1** | IRP uploader gated / stub without ClearTax — B2B ITC buyers may require IRN |
-| K-04 | **P1** | Manual invoice POST / rollup paths weak on `requireActive` vs top-up which requires ACTIVE |
-| K-05 | **P2** | MSME `mustPayByDate` alerts live; §16 interest not accrued; deadline semantics soft |
-| K-06 | **P2** | `TdsAdjustment` / Form 26Q export largely schema-only |
-| K-07 | **P2** | Dual TDS engines vs B2C deprecated path — keep B2B on `lib/compliance/tds.ts` only |
-| K-08 | **P2** | Invoice GST not always per-line; credit-note length limits |
+| ID | Severity | Issue |
+| ---- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| K-01 | **P0** | `OrgKybVerification.kybVerifiedAt` / Sumsub fields — **not a hard gate** on INVOICE booking, invoice issue, or funding-source switch |
+| K-02 | ✅ fixed | `assertVerifiedDomainOrThrow` for INVOICE_FUNDING — the 2026-09-03 verdict pass confirmed FIXED-BY #991: INVOICE now hard-requires a verified domain. |
+| K-03 | **P1** | IRP uploader gated / stub without ClearTax — B2B ITC buyers may require IRN |
+| K-04 | **P1** | Manual invoice POST / rollup paths weak on `requireActive` vs top-up which requires ACTIVE |
+| K-05 | **P2** | MSME `mustPayByDate` alerts live; §16 interest not accrued; deadline semantics soft |
+| K-06 | **P2** | `TdsAdjustment` / Form 26Q export largely schema-only |
+| K-07 | ❌ stale | Dual TDS engines vs B2C deprecated path — the 2026-09-03 verdict pass marked this stale: 194-O is already live via `computeTdsForPayout`. |
+| K-08 | **P2** | Invoice GST not always per-line; credit-note length limits |
Working well: GST derive helper, sequential invoice numbers, org payout TDS 194-O compute, MSME alert cron, credit note mint on refund.
@@ -44,31 +46,34 @@ Working well: GST derive helper, sequential invoice numbers, org payout TDS 194-
## Questions (handled?)
-1. **Hard-gate INVOICE on KYB + verified domain?**
- - A) Yes on funding switch, checkout, invoice issue
- - B) Soft checklist forever
- - C) Cap-only for unverified
+1. **Hard-gate INVOICE on KYB + verified domain?**
+ - A) Yes on funding switch, checkout, invoice issue
+ - B) Soft checklist forever
+ - C) Cap-only for unverified
+
+**Recommendation: A.** Enterprise INVOICE without KYB/domain is a fraud and reputation hole.
-**Recommendation: A.** Enterprise INVOICE without KYB/domain is a fraud and reputation hole.
-- Not B: Checklists do not stop API clients.
+- Not B: Checklists do not stop API clients.
- Not C: Cap is blast-radius control, not identity assurance.
-2. **IRP before enterprise invoice GA?**
- - A) Enable for orgs above AATO / all B2B
- - B) PDF-only until first audit ask
- - C) Per-customer ClearTax allowlist
+2. **IRP before enterprise invoice GA?**
+ - A) Enable for orgs above AATO / all B2B
+ - B) PDF-only until first audit ask
+ - C) Per-customer ClearTax allowlist
-**Recommendation: C then A.** Allowlist design partners who need IRN; expand when ClearTax prod-ready.
-- Not B if selling to GST-registered enterprises that demand IRN now.
+**Recommendation: C then A.** Allowlist design partners who need IRN; expand when ClearTax prod-ready.
+
+- Not B if selling to GST-registered enterprises that demand IRN now.
- A immediately only if ops ready.
-3. **MSME payment SLA productization?**
- - A) Prioritize MSME payouts in batch + surface mustPayByDate in UI
- - B) Alerts-only (current-ish)
- - C) Accrue statutory interest in ledger
+3. **MSME payment SLA productization?**
+ - A) Prioritize MSME payouts in batch + surface mustPayByDate in UI
+ - B) Alerts-only (current-ish)
+ - C) Accrue statutory interest in ledger
+
+**Recommendation: A.** UI + batch priority first; interest accrual (C) after legal sign-off.
-**Recommendation: A.** UI + batch priority first; interest accrual (C) after legal sign-off.
-- Not B alone at host-agency scale.
+- Not B alone at host-agency scale.
- C without legal template is premature.
## High concurrency / multi-device / spikes
@@ -77,6 +82,6 @@ Invoice numbering must stay gapless under concurrent rollups (Serializable prese
## Suggested directions
-1. Wire domain + KYB asserts on INVOICE paths.
-2. Align `requireActive` across money surfaces.
+1. Wire domain + KYB asserts on INVOICE paths.
+2. Align `requireActive` across money surfaces.
3. ClearTax allowlist for IRP; keep TDS on single engine for org payouts.
diff --git a/bugs/enterprise/concurrency-deadlocks-spikes.md b/bugs/enterprise/concurrency-deadlocks-spikes.md
index 810190596..3f5d8c0e2 100644
--- a/bugs/enterprise/concurrency-deadlocks-spikes.md
+++ b/bugs/enterprise/concurrency-deadlocks-spikes.md
@@ -1,5 +1,7 @@
# Enterprise Concurrency, Deadlocks & Traffic Spikes
+> **Verdict pass 2026-09-03/04.** Every money-related claim in this file was re-checked against `dev@e1766fa2d` and the live database as part of the 2026-09-03 finance-subsystem verification. Of 5 claims, 3 are still true today, 2 have been addressed since this dossier was written, and 0 are stale. See [`docs/payments/audits/2026-09-03-finance-verdicts.md`](../../docs/payments/audits/2026-09-03-finance-verdicts.md) for the per-item disposition.
+
## Context
Enterprise concurrency is **Postgres-native** by ADR 13: conditional UPDATEs, unique constraints, sorted ledger account locks. Serializable appears on checkout, some governance, and crons — not on every point mutation. Redis locks protect booking/checkout and cron exclusion. Documented intent: [`docs/enterprise/30-programs-and-lifecycle/01-concurrency-and-idempotency.md`](../../docs/enterprise/30-programs-and-lifecycle/01-concurrency-and-idempotency.md). Chaos go/no-go covers B2C-heavy races; **enterprise 14c (seats, invoice void, wallet top-up replay) is staged, not blocking**.
@@ -8,42 +10,42 @@ Enterprise concurrency is **Postgres-native** by ADR 13: conditional UPDATEs, un
Triaged 2026-07-12 against real code (3 verifier agents cross-checked every claim); fix wave PRs #981–#994 shipped. This dossier's claims map as follows:
-| Claim (short) | Verdict |
-|---|---|
-| X-01 chaos 14c unstaged | 🟡 LEGIT-DEFERRED (staging chaos gate remains) |
-| X-02 SSO PATCH last-write-wins (has `version`) | ✅ FIXED-BY #985 (`expectedVersion` CAS) |
-| X-03 SCIM bypasses unverified seat governance | ✅ FIXED-BY #985 |
-| X-04 `revokeSession` on member removal comment-only | ✅ FIXED-BY #985 (comment corrected to real bump; TRUE revoke blocked — BetterAuth admin plugin not installed → follow-up #725) |
-| X-05 no contractual seat ceiling at assign | 🟡 LEGIT-DEFERRED |
-| X-06 JIT SSO auto-join may not bump `sessionGeneration` | 🟡 LEGIT-DEFERRED |
-| X-07 long Serializable checkout + pool pressure (#368) | 🔵 TRACKED #368 (CLOSED — pooler fix landed) |
-| X-08 CREDIT_POOL lacks reserve-hold-TTL | 🟡 LEGIT-DEFERRED |
+| Claim (short) | Verdict |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| X-01 chaos 14c unstaged | 🟡 LEGIT-DEFERRED (staging chaos gate remains) |
+| X-02 SSO PATCH last-write-wins (has `version`) | ✅ FIXED-BY #985 (`expectedVersion` CAS) |
+| X-03 SCIM bypasses unverified seat governance | ✅ FIXED-BY #985 |
+| X-04 `revokeSession` on member removal comment-only | ✅ FIXED-BY #985 (comment corrected to real bump; TRUE revoke blocked — BetterAuth admin plugin not installed → follow-up #725) |
+| X-05 no contractual seat ceiling at assign | 🟡 LEGIT-DEFERRED |
+| X-06 JIT SSO auto-join may not bump `sessionGeneration` | 🟡 LEGIT-DEFERRED |
+| X-07 long Serializable checkout + pool pressure (#368) | 🔵 TRACKED #368 (CLOSED — pooler fix landed) |
+| X-08 CREDIT_POOL lacks reserve-hold-TTL | 🟡 LEGIT-DEFERRED |
## What works
-| Path | Pattern |
-|------|---------|
-| Wallet debit | `updateMany WHERE walletBalance >= amount` |
-| Engagement / credit cap BLOCK | Guarded `updateMany` on used/consumed |
-| Assignment claim | `createMany skipDuplicates` + unique (program, membership, period) |
-| Invite accept | Atomic pending→accepted claim + P2002 retry |
-| Org capability flip | `expectedVersion` CAS + Serializable wind-down |
-| Ledger postings | Sorted `accountId` balance updates |
-| Invoice void vs pay | Status CAS |
-| Org payout batch | Redis org lock + idempotency key |
+| Path | Pattern |
+| ----------------------------- | ------------------------------------------------------------------ |
+| Wallet debit | `updateMany WHERE walletBalance >= amount` |
+| Engagement / credit cap BLOCK | Guarded `updateMany` on used/consumed |
+| Assignment claim | `createMany skipDuplicates` + unique (program, membership, period) |
+| Invite accept | Atomic pending→accepted claim + P2002 retry |
+| Org capability flip | `expectedVersion` CAS + Serializable wind-down |
+| Ledger postings | Sorted `accountId` balance updates |
+| Invoice void vs pay | Status CAS |
+| Org payout batch | Redis org lock + idempotency key |
## Known gaps / bugs
-| ID | Severity | Issue |
-|----|----------|-------|
-| X-01 | **P1** | Chaos **14c unstaged** — N+1 seat assign, invoice generate-vs-void, wallet top-up replay not in go/no-go suite |
-| X-02 | **P1** | SSO settings have `version` column but PATCH is **last-write-wins** (multi-admin) |
-| X-03 | **P1** | SCIM provisioning **bypasses** unverified 5-seat invite governance |
-| X-04 | **P1** | Docs claim `revokeSession` on member removal — **not implemented**; 5-min cookie membership lag |
-| X-05 | **P2** | No contractual seat ceiling at assign — counter honest, commercial cap absent |
-| X-06 | **P2** | JIT SSO auto-join may not bump `sessionGeneration` — sidebar lag |
-| X-07 | **P2** | Long Serializable checkout + Redis event lock → timeouts under spike (pool #368), looks like deadlock |
-| X-08 | **P2** | CREDIT_POOL lacks reserve-hold-TTL pattern used in industry credit engines — fine now, fragile at massive parallel enroll |
+| ID | Severity | Issue |
+| ---- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| X-01 | **P1** | Chaos **14c unstaged** — N+1 seat assign, invoice generate-vs-void, wallet top-up replay not in go/no-go suite |
+| X-02 | ✅ fixed | SSO settings PATCH — the 2026-09-03 verdict pass confirmed FIXED-BY #985: PATCH now uses `expectedVersion` CAS. |
+| X-03 | ✅ fixed | SCIM provisioning vs unverified 5-seat invite governance — the 2026-09-03 verdict pass confirmed FIXED-BY #985. |
+| X-04 | ✅ fixed | `revokeSession` on member removal — the 2026-09-03 verdict pass confirmed FIXED-BY #985 (comment corrected to the real session-generation bump; true revoke is blocked on the BetterAuth admin plugin, follow-up #725). |
+| X-05 | **P2** | No contractual seat ceiling at assign — counter honest, commercial cap absent |
+| X-06 | **P2** | JIT SSO auto-join may not bump `sessionGeneration` — sidebar lag |
+| X-07 | **P2** | Long Serializable checkout + Redis event lock → timeouts under spike (pool #368), looks like deadlock |
+| X-08 | **P2** | CREDIT_POOL lacks reserve-hold-TTL pattern used in industry credit engines — fine now, fragile at massive parallel enroll |
## Unhappy paths & multi-device psychology
@@ -62,31 +64,34 @@ True AB-BA DB deadlocks are mitigated by sorted ledger locks. Residual “deadlo
## Questions (handled?)
-1. **Stage chaos 14c before enterprise GTM?**
- - A) Yes — hard gate
- - B) Service-level tests enough
- - C) Only after first design partner
+1. **Stage chaos 14c before enterprise GTM?**
+ - A) Yes — hard gate
+ - B) Service-level tests enough
+ - C) Only after first design partner
+
+**Recommendation: A.** Enterprise money paths deserve the same go/no-go rigor as booking races.
-**Recommendation: A.** Enterprise money paths deserve the same go/no-go rigor as booking races.
-- Not B: Unit CAS ≠ API storm behavior.
+- Not B: Unit CAS ≠ API storm behavior.
- Not C: First partner should not be the load test.
-2. **SSO settings CAS?**
- - A) Wire `expectedVersion` like org PATCH
- - B) Accept last-write-wins
- - C) Single-admin lockout for SSO edits
+2. **SSO settings CAS?**
+ - A) Wire `expectedVersion` like org PATCH
+ - B) Accept last-write-wins
+ - C) Single-admin lockout for SSO edits
-**Recommendation: A.** Security settings must not silently clobber across devices.
-- Not B: EnforceSSO flip is too dangerous for LWW.
+**Recommendation: A.** Security settings must not silently clobber across devices.
+
+- Not B: EnforceSSO flip is too dangerous for LWW.
- Not C: Overkill if version CAS works.
-3. **Seat ceiling enforcement?**
- - A) Enforce purchased seats at assignment
- - B) Bill whatever counter says (current)
- - C) Soft warn only
+3. **Seat ceiling enforcement?**
+ - A) Enforce purchased seats at assignment
+ - B) Bill whatever counter says (current)
+ - C) Soft warn only
+
+**Recommendation: A.** Fail closed on revenue seats under concurrency (industry standard).
-**Recommendation: A.** Fail closed on revenue seats under concurrency (industry standard).
-- Not B: Over-assign then dispute is predictable gaming.
+- Not B: Over-assign then dispute is predictable gaming.
- Not C: Warns don’t stop scripts.
## High concurrency / multi-device / spikes
@@ -95,7 +100,7 @@ Millions of users: bottleneck is **Postgres pool + Serializable checkout**, not
## Suggested directions
-1. Implement and green-bar chaos 14c.
-2. SSO version CAS; SCIM seat governance parity.
-3. Implement or delete `revokeSession` docs.
+1. Implement and green-bar chaos 14c.
+2. SSO version CAS; SCIM seat governance parity.
+3. Implement or delete `revokeSession` docs.
4. Plan CREDIT_POOL reserve-hold if enroll becomes long-running.
diff --git a/bugs/enterprise/money-checkout-wallet-invoice.md b/bugs/enterprise/money-checkout-wallet-invoice.md
index 6e0e0071c..4189aa689 100644
--- a/bugs/enterprise/money-checkout-wallet-invoice.md
+++ b/bugs/enterprise/money-checkout-wallet-invoice.md
@@ -1,5 +1,7 @@
# Enterprise Money — Checkout, Wallet, Invoice, License
+> **Verdict pass 2026-09-03/04.** Every money claim in this file was re-checked against `dev@e1766fa2d` and the live database as part of the 2026-09-03 finance-subsystem verification. Of 9 claims, 2 are still true today, 7 have been addressed since this dossier was written, and 0 are stale. See [`docs/payments/audits/2026-09-03-finance-verdicts.md`](../../docs/payments/audits/2026-09-03-finance-verdicts.md) for the per-item disposition.
+
## Context
Org-funded checkout ([`lib/payments/operations/checkout.ts`](../../lib/payments/operations/checkout.ts)) resolves membership + program, then funds via WALLET (conditional debit), INVOICE (accrual leg + credit-limit recheck inside Serializable tx), or LICENSE (zero-amount leg + utilization). Ledger `BOOKING` posts usually via `createEarningsFromPayment` **after** checkout commit (try/catch + cron heal). Enterprise trust requires books to match what finance sees in wallet and invoices.
@@ -8,25 +10,25 @@ Org-funded checkout ([`lib/payments/operations/checkout.ts`](../../lib/payments/
Triaged 2026-07-12 against real code (3 verifier agents cross-checked every claim); fix wave PRs #981–#994 shipped. This dossier's claims map as follows:
-| Claim (short) | Verdict |
-|---|---|
-| C-01 checkout↔ledger non-atomic → `WALLET_BALANCE_DRIFT` / missing earnings | ✅ FIXED-BY #994 |
-| C-02 payment leg sum mismatch warn-only | 🟡 LEGIT-DEFERRED (nightly reconcile backstops) |
-| C-03 INVOICE booking for PENDING_VERIFICATION without hard KYB | ✅ partial via #991 (domain gate) |
-| C-04 CHARGE_MEMBER on non-INVOICE parent fail-closed (#715) | 🔵 TRACKED #715 |
-| C-05 auto-top-up notify-only (#777) | 🔵 TRACKED #777 |
-| C-06 dunning suspend behind flag | 🔵 TRACKED #779 |
+| Claim (short) | Verdict |
+| --------------------------------------------------------------------------- | ----------------------------------------------- |
+| C-01 checkout↔ledger non-atomic → `WALLET_BALANCE_DRIFT` / missing earnings | ✅ FIXED-BY #994 |
+| C-02 payment leg sum mismatch warn-only | 🟡 LEGIT-DEFERRED (nightly reconcile backstops) |
+| C-03 INVOICE booking for PENDING_VERIFICATION without hard KYB | ✅ partial via #991 (domain gate) |
+| C-04 CHARGE_MEMBER on non-INVOICE parent fail-closed (#715) | 🔵 TRACKED #715 |
+| C-05 auto-top-up notify-only (#777) | 🔵 TRACKED #777 |
+| C-06 dunning suspend behind flag | 🔵 TRACKED #779 |
## Known gaps / bugs
-| ID | Severity | Issue |
-|----|----------|-------|
-| C-01 | **P0** | Wallet/legs commit in checkout tx; earnings + `BOOKING` journal in a later swallowed try/catch → transient `WALLET_BALANCE_DRIFT` / missing earnings |
-| C-02 | **P1** | Payment leg sum mismatch is **warn-only** at checkout (nightly reconcile catches) |
-| C-03 | **P1** | INVOICE booking allowed for `PENDING_VERIFICATION` under ₹50k-ish governance cap without hard KYB |
-| C-04 | **P2** | CHARGE_MEMBER on non-INVOICE parent fail-closed (#715) — correct but misconfig hard-fails |
-| C-05 | **P2** | Auto-top-up schema present; cron is **notify-only** (#777) |
-| C-06 | **P2** | Dunning reminders live; booking suspend behind `ENABLE_DUNNING_SUSPEND` (off) |
+| ID | Severity | Issue |
+| ---- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| C-01 | ✅ fixed | Wallet/legs vs earnings + `BOOKING` journal — the 2026-09-03 verdict pass confirmed FIXED-BY #994; checkout and the journal are no longer split across a swallowed try/catch. |
+| C-02 | **P1** | Payment leg sum mismatch is **warn-only** at checkout (nightly reconcile catches) |
+| C-03 | **P1** | INVOICE booking allowed for `PENDING_VERIFICATION` under ₹50k-ish governance cap without hard KYB |
+| C-04 | **P2** | CHARGE_MEMBER on non-INVOICE parent fail-closed (#715) — correct but misconfig hard-fails |
+| C-05 | **P2** | Auto-top-up schema present; cron is **notify-only** (#777) |
+| C-06 | **P2** | Dunning reminders live; booking suspend behind `ENABLE_DUNNING_SUSPEND` (off) |
Working well: wallet `updateMany WHERE balance >= amount`; in-tx INVOICE exposure re-check; LICENSE metering without money legs; Redis + Serializable for slots/capacity.
@@ -39,31 +41,34 @@ Working well: wallet `updateMany WHERE balance >= amount`; in-tx INVOICE exposur
## Questions (handled?)
-1. **Org-sponsored checkout + earnings + ledger atomicity?**
- - A) Single Serializable tx for org paths
- - B) Compensating wallet credit if earnings fail
- - C) Keep try/catch + nightly heal
+1. **Org-sponsored checkout + earnings + ledger atomicity?**
+ - A) Single Serializable tx for org paths
+ - B) Compensating wallet credit if earnings fail
+ - C) Keep try/catch + nightly heal
+
+**Recommendation: A (or B as interim).** Enterprise cannot respect “eventual books”; prefer one tx, or immediate compensating credit + alert.
-**Recommendation: A (or B as interim).** Enterprise cannot respect “eventual books”; prefer one tx, or immediate compensating credit + alert.
-- Not C: Cron heal is fine for B2C noise; fatal for design-partner CFOs.
+- Not C: Cron heal is fine for B2C noise; fatal for design-partner CFOs.
- B acceptable short-term if A is large; never silent swallow alone.
-2. **Leg sum mismatch — throw or warn?**
- - A) Hard throw / 500 abort checkout
- - B) Warn + ship (current)
- - C) Quarantine payment to manual review state
+2. **Leg sum mismatch — throw or warn?**
+ - A) Hard throw / 500 abort checkout
+ - B) Warn + ship (current)
+ - C) Quarantine payment to manual review state
-**Recommendation: A.** Bad legs must not reach SUCCEEDED — overnight reconcile is too late for trust.
-- Not B: Warn-only ships corrupt money shapes.
+**Recommendation: A.** Bad legs must not reach SUCCEEDED — overnight reconcile is too late for trust.
+
+- Not B: Warn-only ships corrupt money shapes.
- Not C: Quarantine is heavier than fail-closed at write time.
-3. **INVOICE for PENDING_VERIFICATION orgs?**
- - A) Block until ACTIVE + KYB/domain
- - B) Keep ₹50k pilot cap
- - C) Cap + park all payables (see payouts file)
+3. **INVOICE for PENDING_VERIFICATION orgs?**
+ - A) Block until ACTIVE + KYB/domain
+ - B) Keep ₹50k pilot cap
+ - C) Cap + park all payables (see payouts file)
+
+**Recommendation: C near-term, A for GA.** Cap alone still creates platform liability if consultants accrue; park payables or block.
-**Recommendation: C near-term, A for GA.** Cap alone still creates platform liability if consultants accrue; park payables or block.
-- Not B alone: Cap limits blast radius but still burns trust and cash.
+- Not B alone: Cap limits blast radius but still burns trust and cash.
- A alone without payable parking still needed for GA.
## High concurrency / multi-device / spikes
@@ -72,6 +77,6 @@ Month-end + cohort enroll: many Serializable checkouts + wallet row contention
## Suggested directions
-1. Unify org checkout money write with ledger/earnings.
-2. Throw on leg sum mismatch.
+1. Unify org checkout money write with ledger/earnings.
+2. Throw on leg sum mismatch.
3. Pair with KYB + PENDING_TRUST sponsor-scope fixes (sibling files).
diff --git a/bugs/enterprise/money-payouts-earnings-trust.md b/bugs/enterprise/money-payouts-earnings-trust.md
index 07be00441..4e4c45f69 100644
--- a/bugs/enterprise/money-payouts-earnings-trust.md
+++ b/bugs/enterprise/money-payouts-earnings-trust.md
@@ -1,5 +1,7 @@
# Enterprise Money — Payouts, Earnings & Trust Parking
+> **Verdict pass 2026-09-03/04.** Every money claim in this file was re-checked against `dev@e1766fa2d` and the live database as part of the 2026-09-03 finance-subsystem verification. Of 10 claims, 2 are still true today, 8 have been addressed since this dossier was written, and 0 are stale. See [`docs/payments/audits/2026-09-03-finance-verdicts.md`](../../docs/payments/audits/2026-09-03-finance-verdicts.md) for the per-item disposition.
+
## Context
Successful org/host flows create `OrganizationEarnings` + `ConsultantEarnings`, hold, then batch into `OrganizationPayout` / `ConsultantPayout`. `PENDING_TRUST` was meant to park payables when **unverified INVOICE sponsors** ghost. Live disbursement requires `ENABLE_LIVE_PAYOUTS`. Host split requires `ENABLE_HOST_ORGS`. This file is about **whether enterprise money-out tells the truth**.
@@ -10,27 +12,27 @@ Key: [`lib/payments/payouts/earnings-service.ts`](../../lib/payments/payouts/ear
Triaged 2026-07-12 against real code (3 verifier agents cross-checked every claim); fix wave PRs #981–#994 shipped. This dossier's claims map as follows:
-| Claim (short) | Verdict |
-|---|---|
-| E-01 PENDING_TRUST scopes host not sponsoring org | ✅ FIXED-BY #991 |
-| E-02 consultant earnings for ghost INVOICE not parked | ✅ FIXED-BY #991 |
-| E-03 earnings flip PAID at batch creation | ✅ FIXED-BY #993 (BATCHED status) |
-| E-04 LIVE_PAYOUTS off → batches PAID without UTR | ✅ FIXED-BY #993 |
-| E-05 post-COMPLETED clawback manual; org-side TDS reversal | 🟡 LEGIT-DEFERRED |
-| E-06 no RazorpayX balance pre-check before batch | 🟡 LEGIT-DEFERRED |
-| E-07 poller vs webhook reverse-status edges | 🟡 LEGIT-DEFERRED |
+| Claim (short) | Verdict |
+| ---------------------------------------------------------- | --------------------------------- |
+| E-01 PENDING_TRUST scopes host not sponsoring org | ✅ FIXED-BY #991 |
+| E-02 consultant earnings for ghost INVOICE not parked | ✅ FIXED-BY #991 |
+| E-03 earnings flip PAID at batch creation | ✅ FIXED-BY #993 (BATCHED status) |
+| E-04 LIVE_PAYOUTS off → batches PAID without UTR | ✅ FIXED-BY #993 |
+| E-05 post-COMPLETED clawback manual; org-side TDS reversal | 🟡 LEGIT-DEFERRED |
+| E-06 no RazorpayX balance pre-check before batch | 🟡 LEGIT-DEFERRED |
+| E-07 poller vs webhook reverse-status edges | 🟡 LEGIT-DEFERRED |
## Known gaps / bugs
-| ID | Severity | Issue |
-|----|----------|-------|
-| E-01 | **P0** | `PENDING_TRUST` scopes **host** `orgSplit.organizationId`, not sponsoring `payment.organizationId` — ghost INVOICE sponsor + ACTIVE host still accrues host share |
-| E-02 | **P0** | Marketplace / consultant earnings for unverified INVOICE org bookings are **not parked** — platform can owe experts for unpaid sponsor invoices |
-| E-03 | **P1** | Earnings flipped to **PAID when batch is created**, before gateway wire / COMPLETED |
-| E-04 | **P1** | `ENABLE_LIVE_PAYOUTS` off → batches exist, no UTR — trust erosion if UI says paid |
-| E-05 | **P2** | Org clawback after COMPLETED payout is manual; TDS org-side reversal incomplete |
-| E-06 | **P2** | No RazorpayX balance pre-check before batch |
-| E-07 | **P2** | Poller vs webhook reverse-status edge cases on payouts |
+| ID | Severity | Issue |
+| ---- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| E-01 | ✅ fixed | `PENDING_TRUST` scoping — the 2026-09-03 verdict pass confirmed FIXED-BY #991: it now scopes the sponsoring `payment.organizationId`, not the host. |
+| E-02 | ✅ fixed | Marketplace / consultant earnings for unverified INVOICE org bookings — the 2026-09-03 verdict pass confirmed FIXED-BY #991: these now park. |
+| E-03 | ✅ fixed | Earnings-flip timing — the 2026-09-03 verdict pass confirmed FIXED-BY #993: earnings go BATCHED at batch creation and only PAID after the gateway wire completes. |
+| E-04 | ✅ fixed | `ENABLE_LIVE_PAYOUTS` off + no UTR — the 2026-09-03 verdict pass confirmed FIXED-BY #993, tied to the same BATCHED-status change as E-03. |
+| E-05 | **P2** | Org clawback after COMPLETED payout is manual; TDS org-side reversal incomplete |
+| E-06 | **P2** | No RazorpayX balance pre-check before batch |
+| E-07 | **P2** | Poller vs webhook reverse-status edge cases on payouts |
## Unhappy paths & multi-device psychology
@@ -41,35 +43,38 @@ Triaged 2026-07-12 against real code (3 verifier agents cross-checked every clai
## Questions (handled?)
-1. **Fix PENDING_TRUST scope before any INVOICE sponsor GA?**
- - A) Park consultant + correct sponsor org id; or block checkout until ACTIVE/KYB
- - B) Keep current host-scoped park
- - C) Rely on ₹50k cap only
+1. **Fix PENDING_TRUST scope before any INVOICE sponsor GA?**
+ - A) Park consultant + correct sponsor org id; or block checkout until ACTIVE/KYB
+ - B) Keep current host-scoped park
+ - C) Rely on ₹50k cap only
+
+**Recommendation: A.** Mis-scoped park is an existential balance-sheet bug for enterprise respect.
-**Recommendation: A.** Mis-scoped park is an existential balance-sheet bug for enterprise respect.
-- Not B: Current behavior does not match ADR intent.
+- Not B: Current behavior does not match ADR intent.
- Not C: Cap limits size, not wrong payables.
-2. **When to mark earnings PAID?**
- - A) Only on payout COMPLETED + UTR
- - B) At batch creation (current)
- - C) Intermediate status `BATCHED` then `PAID`
+2. **When to mark earnings PAID?**
+ - A) Only on payout COMPLETED + UTR
+ - B) At batch creation (current)
+ - C) Intermediate status `BATCHED` then `PAID`
> 🎯 Locked: BATCHED status (rec C, shipped #993) — earnings go BATCHED at batch creation and only PAID after the gateway wire completes.
-**Recommendation: C (or A).** Introduce `BATCHED`/`IN_FLIGHT` so UI never lies; `PAID` only after wire.
-- Not B: “Paid” before cash is how enterprise trust dies.
+**Recommendation: C (or A).** Introduce `BATCHED`/`IN_FLIGHT` so UI never lies; `PAID` only after wire.
+
+- Not B: “Paid” before cash is how enterprise trust dies.
- A alone may be enough if batch UI uses non-PAID labels.
-3. **Live payouts go-live coupling?**
- - A) With HOST flag + Path C CA memo + sandbox UTR
- - B) Enable anytime for consultant-only
- - C) Stay manual bank forever
+3. **Live payouts go-live coupling?**
+ - A) With HOST flag + Path C CA memo + sandbox UTR
+ - B) Enable anytime for consultant-only
+ - C) Stay manual bank forever
> 🎯 Locked: sponsor-first — the live-payouts flip couples with the host flag as one go-live program after the sponsor rail ships.
-**Recommendation: A.** One runbook: host split + live payouts + CA Path C + UTR proof.
-- Not B: Consultant-only still needs trust parking + TDS correctness.
+**Recommendation: A.** One runbook: host split + live payouts + CA Path C + UTR proof.
+
+- Not B: Consultant-only still needs trust parking + TDS correctness.
- Not C: Manual does not scale past design partners.
## High concurrency / multi-device / spikes
@@ -78,6 +83,6 @@ Batch creation uses Redis org lock + Serializable + idempotency keys — solid u
## Suggested directions
-1. Re-implement PENDING_TRUST against `payment.organizationId` + park `ConsultantEarnings`.
-2. Rename/split PAID vs BATCHED.
+1. Re-implement PENDING_TRUST against `payment.organizationId` + park `ConsultantEarnings`.
+2. Rename/split PAID vs BATCHED.
3. Dual-flag go-live runbook before host agency sales.
diff --git a/bugs/enterprise/money-refunds-disputes-overage.md b/bugs/enterprise/money-refunds-disputes-overage.md
index 5c52ae0cc..85552d407 100644
--- a/bugs/enterprise/money-refunds-disputes-overage.md
+++ b/bugs/enterprise/money-refunds-disputes-overage.md
@@ -1,5 +1,7 @@
# Enterprise Money — Refunds, Disputes & Overage
+> **Verdict pass 2026-09-03/04.** Every money claim in this file was re-checked against `dev@e1766fa2d` and the live database as part of the 2026-09-03 finance-subsystem verification. Of 10 claims, 4 are still true today, 5 have been addressed since this dossier was written, and 1 are stale. See [`docs/payments/audits/2026-09-03-finance-verdicts.md`](../../docs/payments/audits/2026-09-03-finance-verdicts.md) for the per-item disposition.
+
## Context
Canonical cascade: [`lib/payments/operations/refund.ts`](../../lib/payments/operations/refund.ts) (`applyRefundCascade`) — Serializable, `cascadedAt` claim, reverse legs (wallet credit, accrual reversals, LICENSE utilization), earnings clawback, credit notes, best-effort `REFUND` ledger. Disputes: hold earnings → LOST applies org chargeback (`Dr WALLET` / receivable) + credit note. Overage: PENDING/ACCRUED can reverse on refund; **CHARGED overage (#716) is an explicit gap**.
@@ -8,27 +10,27 @@ Canonical cascade: [`lib/payments/operations/refund.ts`](../../lib/payments/oper
Triaged 2026-07-12 against real code (3 verifier agents cross-checked every claim); fix wave PRs #981–#994 shipped. This dossier's claims map as follows:
-| Claim (short) | Verdict |
-|---|---|
-| R-01 #716 CHARGED overage lacks auto credit-note / return | 🟡 LEGIT-DEFERRED (#716) |
-| R-02 ledger reversal on refund best-effort | 🟡 LEGIT-DEFERRED (append-only legs + cron heal) |
-| R-03 org chargeback can drive wallet negative | 🟡 LEGIT-DEFERRED (dunning recovery) |
-| R-04 credit-note serial length / prefix edges | 🟡 LEGIT-DEFERRED |
-| R-05 Razorpay dispute reconciler manual-heavy | 🟡 LEGIT-DEFERRED |
-| R-06 post-COMPLETED payout clawback manual | 🟡 LEGIT-DEFERRED (post-payout netting not in this wave) |
-| R-07 docs claim multi-leg refund incomplete | ❌ STALE/OVERSTATED (cascade + tax adjustment rows already wired — don't chase ghosts) |
+| Claim (short) | Verdict |
+| --------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| R-01 #716 CHARGED overage lacks auto credit-note / return | 🟡 LEGIT-DEFERRED (#716) |
+| R-02 ledger reversal on refund best-effort | 🟡 LEGIT-DEFERRED (append-only legs + cron heal) |
+| R-03 org chargeback can drive wallet negative | 🟡 LEGIT-DEFERRED (dunning recovery) |
+| R-04 credit-note serial length / prefix edges | 🟡 LEGIT-DEFERRED |
+| R-05 Razorpay dispute reconciler manual-heavy | 🟡 LEGIT-DEFERRED |
+| R-06 post-COMPLETED payout clawback manual | 🟡 LEGIT-DEFERRED (post-payout netting not in this wave) |
+| R-07 docs claim multi-leg refund incomplete | ❌ STALE/OVERSTATED (cascade + tax adjustment rows already wired — don't chase ghosts) |
## Known gaps / bugs
-| ID | Severity | Issue |
-|----|----------|-------|
-| R-01 | **P1** | #716 — CHARGED `OVERAGE_INVOICE_ACCRUAL` / member side-charge lacks automated credit-note + money return |
-| R-02 | **P1** | Ledger reversal on refund can be best-effort — books lag customer money |
-| R-03 | **P1** | Org chargeback can drive wallet negative — dunning must recover |
-| R-04 | **P2** | Credit note serial length / prefix edge cases for long org codes |
-| R-05 | **P2** | Razorpay dispute list/reconciler still manual-heavy |
-| R-06 | **P2** | Post-COMPLETED org payout clawback is manual (no auto net-next-batch) |
-| R-07 | **P2** | Readiness docs may still claim multi-leg refund incomplete — **code largely fixed**; don’t chase ghosts |
+| ID | Severity | Issue |
+| ---- | -------- | -------------------------------------------------------------------------------------------------------- |
+| R-01 | **P1** | #716 — CHARGED `OVERAGE_INVOICE_ACCRUAL` / member side-charge lacks automated credit-note + money return |
+| R-02 | **P1** | Ledger reversal on refund can be best-effort — books lag customer money |
+| R-03 | **P1** | Org chargeback can drive wallet negative — dunning must recover |
+| R-04 | **P2** | Credit note serial length / prefix edge cases for long org codes |
+| R-05 | **P2** | Razorpay dispute list/reconciler still manual-heavy |
+| R-06 | **P2** | Post-COMPLETED org payout clawback is manual (no auto net-next-batch) |
+| R-07 | **P2** | Readiness docs may still claim multi-leg refund incomplete — **code largely fixed**; don’t chase ghosts |
Working well: refund vs chargeback Serializable pairing (#785); append-only reversal legs (#786); idempotent credit notes on `refundId`.
@@ -41,31 +43,34 @@ Working well: refund vs chargeback Serializable pairing (#785); append-only reve
## Questions (handled?)
-1. **#716 CHARGED overage on refund — priority before enterprise GA?**
- - A) Hard gate — implement credit note + reverse/chargeback policy
- - B) Manual finance runbook only
- - C) Forbid CHARGE_* overage until fixed
+1. **#716 CHARGED overage on refund — priority before enterprise GA?**
+ - A) Hard gate — implement credit note + reverse/chargeback policy
+ - B) Manual finance runbook only
+ - C) Forbid CHARGE\_\* overage until fixed
+
+**Recommendation: A (or C interim).** Un-reversed CHARGED overage destroys AP trust; implement or disable CHARGE paths until done.
-**Recommendation: A (or C interim).** Un-reversed CHARGED overage destroys AP trust; implement or disable CHARGE paths until done.
-- Not B: Manual-only fails at cohort scale.
+- Not B: Manual-only fails at cohort scale.
- C valid freeze if eng capacity tight before A ships.
-2. **Org chargeback recovery?**
- - A) Auto-dunning + optional suspend
- - B) Immediate negative wallet + invoice
- - C) Platform absorbs
+2. **Org chargeback recovery?**
+ - A) Auto-dunning + optional suspend
+ - B) Immediate negative wallet + invoice
+ - C) Platform absorbs
-**Recommendation: A.** Negative wallet is a signal; recover via dunning/suspend policy, not silent absorption.
-- Not B alone without dunning UX.
+**Recommendation: A.** Negative wallet is a signal; recover via dunning/suspend policy, not silent absorption.
+
+- Not B alone without dunning UX.
- Not C: Teaches sponsors disputes are free.
-3. **Post-payout clawback?**
- - A) Net against next OrganizationPayout
- - B) Manual collection forever
- - C) Hold future host bookings until cleared
+3. **Post-payout clawback?**
+ - A) Net against next OrganizationPayout
+ - B) Manual collection forever
+ - C) Hold future host bookings until cleared
+
+**Recommendation: A.** Auto-net next batch; escalate to C only for chronic offenders.
-**Recommendation: A.** Auto-net next batch; escalate to C only for chronic offenders.
-- Not B: Ops debt grows with every refund-after-payout.
+- Not B: Ops debt grows with every refund-after-payout.
- C too harsh as default.
## High concurrency / multi-device / spikes
@@ -74,6 +79,6 @@ Refund × dispute × webhook storms are among the best-tested money races. Resid
## Suggested directions
-1. Ship #716 with tests for INVOICE + CHARGE_MEMBER parents.
-2. Enable dunning suspend when AR policy ready.
+1. Ship #716 with tests for INVOICE + CHARGE_MEMBER parents.
+2. Enable dunning suspend when AR policy ready.
3. Clawback auto-net in org payout batch creator.
diff --git a/bugs/finances/00-overview.md b/bugs/finances/00-overview.md
index fcb3b8eed..a0a582a8e 100644
--- a/bugs/finances/00-overview.md
+++ b/bugs/finances/00-overview.md
@@ -1,5 +1,7 @@
# Finances — Overview
+> **Verdict pass 2026-09-03/04.** Every money claim in this file was re-checked against `dev@e1766fa2d` and the live database as part of the 2026-09-03 finance-subsystem verification. Of 10 claims, 4 are still true today, 4 have been addressed since this dossier was written, and 2 are stale. See [`docs/payments/audits/2026-09-03-finance-verdicts.md`](../../docs/payments/audits/2026-09-03-finance-verdicts.md) for the per-item disposition.
+
## Context
Familiarise’s money stack is Razorpay-primary (Stripe legacy/fallback), with integer paise amounts, a double-entry ledger (`LedgerTransaction` / `LedgerEntry`), and enterprise funding paths (wallet, invoice accrual, license). Consumer checkout creates tentative bookings; webhooks confirm payment and slots. Consultant/org payouts run through RazorpayX (Path C: PG → operating account → FAA), gated by `ENABLE_LIVE_PAYOUTS`.
@@ -10,25 +12,25 @@ Canonical engineering: `docs/payments/`, `docs/enterprise/10-money-and-ledger/`,
Triaged 2026-07-12 against real code (3 verifier agents cross-checked every claim); fix wave PRs #981–#994 shipped. This dossier's claims map as follows:
-| Claim (short) | Verdict |
-|---|---|
-| Live payout disbursement flag-gated off | 🔵 by-design gate (`ENABLE_LIVE_PAYOUTS`); not a bug |
-| INR-only ledger, FX fields cosmetic | 🔵 TRACKED #783 (multi-currency deferred) |
-| Phase-2 side effects outside confirm tx | 🔵 by-design ACK-before-complete; sweeper backstop |
-| Amount mismatch marks recovery, no auto-refund | ✅ FIXED-BY #990 (auto-refund + Sentry, manual-recovery fallback) |
-| Dual TDS engines, B2C consultant on 194J (P0) | ❌ STALE — consultant withholding is already 194-O via `computeTdsForPayout` (payout-service.ts:592-607); the P0 does not exist in current code |
-| Lemon Squeezy / XFlow `NOT_IMPLEMENTED` + routes | ✅ FIXED-BY #984 (removed; Stripe kept; DODO_PAYMENTS enum added post-MVP) |
-| Day-pass doc-only, no Prisma model | ✅ FIXED-BY #984 (doc mentions removed) |
+| Claim (short) | Verdict |
+| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Live payout disbursement flag-gated off | 🔵 by-design gate (`ENABLE_LIVE_PAYOUTS`); not a bug |
+| INR-only ledger, FX fields cosmetic | 🔵 TRACKED #783 (multi-currency deferred) |
+| Phase-2 side effects outside confirm tx | 🔵 by-design ACK-before-complete; sweeper backstop |
+| Amount mismatch marks recovery, no auto-refund | ✅ FIXED-BY #990 (auto-refund + Sentry, manual-recovery fallback) |
+| Dual TDS engines, B2C consultant on 194J (P0) | ❌ STALE — consultant withholding is already 194-O via `computeTdsForPayout` (payout-service.ts:592-607); the P0 does not exist in current code |
+| Lemon Squeezy / XFlow `NOT_IMPLEMENTED` + routes | ✅ FIXED-BY #984 (removed; Stripe kept; DODO_PAYMENTS enum added post-MVP) |
+| Day-pass doc-only, no Prisma model | ✅ FIXED-BY #984 (doc mentions removed) |
## Known gaps / bugs
- Live payout disbursement is feature-flagged off by default — earnings accrue without real money movement until ops flips the flag.
- Ledger and plan pricing are **INR settlement only**; display FX fields exist for international buyers but are audit cosmetics (#783).
- Phase-2 webhook side effects (earnings, notifications) sit outside the confirmation transaction — temporary inconsistency until crons heal.
-- Amount mismatch on capture marks recovery flags but does not auto-refund.
-- Dual TDS engines: B2B uses `lib/compliance/tds.ts` (194-O); B2C consultant path still touches deprecated `lib/payments/tax/tds-service.ts` (194J rates) — **P0** if B2C payouts go live.
-- Lemon Squeezy / XFlow checkout throw `NOT_IMPLEMENTED`; webhook routes still exist.
-- Day-pass product appears in Razorpay skill docs only — no Prisma model.
+- Amount mismatch on capture — the 2026-09-03 verdict pass confirmed this FIXED-BY #990 (auto-refund + Sentry paging, with manual-recovery as the fallback).
+- Dual TDS engines — the 2026-09-03 verdict pass marked this stale: consultant withholding is already 194-O via `computeTdsForPayout` (payout-service.ts:592-607); the B2C-on-194J path described here does not exist in current code.
+- Lemon Squeezy / XFlow checkout — the 2026-09-03 verdict pass confirmed this FIXED-BY #984 (removed; Stripe kept as the live rail; Dodo Payments added post-MVP).
+- Day-pass product doc-only — the 2026-09-03 verdict pass confirmed this FIXED-BY #984 (the doc mentions were removed).
## Unhappy paths & user psychology
@@ -39,34 +41,37 @@ Triaged 2026-07-12 against real code (3 verifier agents cross-checked every clai
## Questions (handled?)
-1. **Is Path C (operating account + RazorpayX) signed off by a CA under RBI PA Directions 2025?**
- - A) Written CA/RBI memo before first live payout
- - B) Ship design partners with escrow-like hold language only
- - C) Move to Razorpay Route sub-merchants per consultant
+1. **Is Path C (operating account + RazorpayX) signed off by a CA under RBI PA Directions 2025?**
+ - A) Written CA/RBI memo before first live payout
+ - B) Ship design partners with escrow-like hold language only
+ - C) Move to Razorpay Route sub-merchants per consultant
**Recommendation: A.** Money movement under Path C needs a written CA/RBI memo before the first live payout so Familiarise does not invent escrow language or redesign onto Route.
+
- Not B: Hold copy without a memo still leaves RBI PA exposure once real UTRs flow.
- Not C: Route sub-merchants abandon the intentional Path C architecture and delay go-live.
> 🎯 Locked: rec A stands — this is a legal/CA sign-off gate, not a code change.
-2. **What is the customer SLA when payment succeeds but booking confirmation lags (async webhook gap)?**
- - A) Confirm within N minutes via sweeper + status page
- - B) Poll client until SUCCEEDED or timeout with auto-refund
- - C) Accept ops tickets; document “eventual confirmation”
+2. **What is the customer SLA when payment succeeds but booking confirmation lags (async webhook gap)?**
+ - A) Confirm within N minutes via sweeper + status page
+ - B) Poll client until SUCCEEDED or timeout with auto-refund
+ - C) Accept ops tickets; document “eventual confirmation”
**Recommendation: A.** Sweeper + status page matches the existing ACK-before-complete webhook design and keeps paid users informed without premature refunds.
+
- Not B: Client-timeout auto-refunds can claw back legitimate slow confirms and fight the sweeper.
- Not C: Ops-ticket-only acceptance erodes trust when payment already succeeded.
> 🎯 Locked: rec A — the sweeper + status-page design is already the shipped behaviour.
-3. **Who owns finance reconciliation when `LedgerReconciliationReport.ok=false`?**
- - A) On-call eng pages nightly
- - B) Finance ops dashboard with weekly review
- - C) Auto-open support ticket per finding
+3. **Who owns finance reconciliation when `LedgerReconciliationReport.ok=false`?**
+ - A) On-call eng pages nightly
+ - B) Finance ops dashboard with weekly review
+ - C) Auto-open support ticket per finding
**Recommendation: A.** Ledger `ok=false` is a money-correctness P0 and should page engineering the night it appears, not wait for a weekly ops glance.
+
- Not B: Weekly review is too slow when wallet/cache drift can compound under load.
- Not C: Support tickets do not fix journal/cache imbalance and create noise without owners.
@@ -74,9 +79,9 @@ Triaged 2026-07-12 against real code (3 verifier agents cross-checked every clai
## High concurrency / multi-device
-Checkout uses `clientIdempotencyKey`, Redis locks, Serializable transactions, and webhook `eventId` dedup. Same user on two devices double-tapping pay should replay via unique key; two *different* users racing a 1:1 slot may both pay — confirmation guard blocks the loser (see booking pack). Mobile: **web checkout only** today — no native Razorpay SDK.
+Checkout uses `clientIdempotencyKey`, Redis locks, Serializable transactions, and webhook `eventId` dedup. Same user on two devices double-tapping pay should replay via unique key; two _different_ users racing a 1:1 slot may both pay — confirmation guard blocks the loser (see booking pack). Mobile: **web checkout only** today — no native Razorpay SDK.
## Suggested directions
-1. Treat finances go-live as a checklist: live payouts sandbox UTR proof, Path C memo, TDS engine unification, IRP decision, amount-mismatch runbook.
+1. Treat finances go-live as a checklist: live payouts sandbox UTR proof, Path C memo, TDS engine unification, IRP decision, amount-mismatch runbook.
2. Read sibling files in this folder before changing money code.
diff --git a/bugs/finances/checkout-webhooks-idempotency.md b/bugs/finances/checkout-webhooks-idempotency.md
index d9a65eb17..a4e0b63fd 100644
--- a/bugs/finances/checkout-webhooks-idempotency.md
+++ b/bugs/finances/checkout-webhooks-idempotency.md
@@ -1,5 +1,7 @@
# Checkout, Webhooks & Idempotency
+> **Verdict pass 2026-09-03/04.** Every money claim in this file was re-checked against `dev@e1766fa2d` and the live database as part of the 2026-09-03 finance-subsystem verification. Of 8 claims, 3 are still true today, 4 have been addressed since this dossier was written, and 1 are stale. See [`docs/payments/audits/2026-09-03-finance-verdicts.md`](../../docs/payments/audits/2026-09-03-finance-verdicts.md) for the per-item disposition.
+
## Context
`POST /api/checkout` → `handleCheckout()` creates a PENDING `Payment` plus tentative slots under Redis + Serializable guards. Gateway order/session is minted; user pays via Razorpay.js (or Stripe). Razorpay webhooks verify HMAC, dedup via `WebhookEvent`, return 200 fast, and process in `after()`. Success confirms slots; failure deletes tentatives. Client HMAC verify exists as defense-in-depth only — webhook remains authoritative.
@@ -10,57 +12,60 @@ Key paths: `lib/payments/operations/checkout.ts`, `app/api/webhooks/razorpay/`,
Triaged 2026-07-12 against real code (3 verifier agents cross-checked every claim); fix wave PRs #981–#994 shipped. This dossier's claims map as follows:
-| Claim (short) | Verdict |
-|---|---|
-| `after()` ACK-before-complete gap | 🔵 by-design + `sweep-stuck-webhook-events` cron backstop |
-| Refund-before-capture `DeferSignal` race | 🔵 handled (#855) |
-| Amount parity failure leaves funds captured, booking blocked | ✅ FIXED-BY #990 (auto-refund + Sentry) |
-| Stripe sync vs Razorpay async asymmetry | 🎯 Stripe KEPT by decision; asymmetry accepted (ADR recommended removal, user retains Stripe) |
-| `allocationIdempotencyKey` schema-only | ✅ FIXED-BY #988 (#837, wired via Idempotency-Key header) |
+| Claim (short) | Verdict |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| `after()` ACK-before-complete gap | 🔵 by-design + `sweep-stuck-webhook-events` cron backstop |
+| Refund-before-capture `DeferSignal` race | 🔵 handled (#855) |
+| Amount parity failure leaves funds captured, booking blocked | ✅ FIXED-BY #990 (auto-refund + Sentry) |
+| Stripe sync vs Razorpay async asymmetry | 🎯 Stripe KEPT by decision; asymmetry accepted (ADR recommended removal, user retains Stripe) |
+| `allocationIdempotencyKey` schema-only | ✅ FIXED-BY #988 (#837, wired via Idempotency-Key header) |
## Known gaps / bugs
- Async `after()` processing means ACK-before-complete; stuck events rely on `sweep-stuck-webhook-events` cron (minutes-level gap).
- Refund-before-capture race uses `DeferSignal` — correct but easy to mis-ops if sweeper cadence slips.
-- Amount parity failure can leave funds captured while booking blocked (`REQUIRES_MANUAL_RECOVERY`).
-- Stripe path processes sync (no `after()`) — asymmetric timeout/retry behavior vs Razorpay.
-- `allocationIdempotencyKey` on appointments is schema-only (#837) — allocate double-submit not fully covered by payment idempotency.
+- Amount parity failure leaving funds captured while booking is blocked — the 2026-09-03 verdict pass confirmed this FIXED-BY #990 (auto-refund + Sentry paging).
+- Stripe path processes sync (no `after()`) — asymmetric timeout/retry behavior vs Razorpay; kept by decision, the asymmetry is accepted rather than removed.
+- `allocationIdempotencyKey` on appointments — the 2026-09-03 verdict pass confirmed this FIXED-BY #988 (#837): it is now wired via the `Idempotency-Key` header on the allocate routes, not schema-only.
## Unhappy paths & user psychology
-- Double-click / back-button / second tab: user thinks first pay failed and tries again — mitigated by `clientIdempotencyKey` if the client remints carefully; remounting checkout can mint a *new* key.
+- Double-click / back-button / second tab: user thinks first pay failed and tries again — mitigated by `clientIdempotencyKey` if the client remints carefully; remounting checkout can mint a _new_ key.
- Payment app switches to UPI on phone while checkout started on desktop — browser session may expire while Razorpay still captures.
- User closes modal after bank OTP; webhook still succeeds — they see no UI confirmation until refresh.
- Org wallet checkout: balance looks enough on screen A; screen B spends wallet first; screen A fails mid-flow with confusing error.
## Questions (handled?)
-1. **After amount mismatch (gateway ≠ Payment.amount), auto-refund or manual confirm?**
- - A) Always auto-refund + Sentry P0
- - B) Manual ops with 24h SLA (current leaning)
- - C) Partial capture / adjust booking price only with admin approval
+1. **After amount mismatch (gateway ≠ Payment.amount), auto-refund or manual confirm?**
+ - A) Always auto-refund + Sentry P0
+ - B) Manual ops with 24h SLA (current leaning)
+ - C) Partial capture / adjust booking price only with admin approval
**Recommendation: A.** Auto-refund amount mismatches and page Sentry P0 — captured funds with a blocked booking must not wait on a 24h ops SLA.
+
- Not B: Manual recovery leaves consultees charged while `REQUIRES_MANUAL_RECOVERY` sits.
- Not C: Partial capture / price adjust invents a second money path instead of returning the wrong capture.
> 🎯 Locked: rec A — #990 ships auto-refund + Sentry P0 on amount mismatch, with manual recovery only as fallback.
-2. **Should checkout remount reuse the same `clientIdempotencyKey` for a given cart fingerprint?**
- - A) Persist key in sessionStorage keyed by plan+slots
- - B) Mint fresh each mount; rely on paymentIntent uniqueness
- - C) Server-side “open PENDING payment for this user+plan” reuse
+2. **Should checkout remount reuse the same `clientIdempotencyKey` for a given cart fingerprint?**
+ - A) Persist key in sessionStorage keyed by plan+slots
+ - B) Mint fresh each mount; rely on paymentIntent uniqueness
+ - C) Server-side “open PENDING payment for this user+plan” reuse
**Recommendation: C.** Reuse an open PENDING payment server-side for the same user+plan so remounts, tabs, and WebViews cannot mint parallel charges.
+
- Not A: sessionStorage helps one browser only and fails across phone/desktop checkout.
- Not B: Fresh keys on every mount are exactly how double-pay unhappy paths start.
-3. **Is asymmetric Razorpay-async vs Stripe-sync acceptable long-term?**
- - A) Unify both on async + sweeper
- - B) Delete Stripe per gateway evaluation
- - C) Keep Stripe sync for test-only
+3. **Is asymmetric Razorpay-async vs Stripe-sync acceptable long-term?**
+ - A) Unify both on async + sweeper
+ - B) Delete Stripe per gateway evaluation
+ - C) Keep Stripe sync for test-only
**Recommendation: B.** Delete unused Stripe per the gateway evaluation so Razorpay-async + sweeper is the only production money path.
+
- Not A: Unifying Stripe onto async invests in a dual-rail we intend to exit.
- Not C: Test-only Stripe still leaves asymmetric timeout/retry behavior in the codebase.
diff --git a/bugs/finances/high-concurrency-and-spikes.md b/bugs/finances/high-concurrency-and-spikes.md
index 5364ccfd9..4b07b93df 100644
--- a/bugs/finances/high-concurrency-and-spikes.md
+++ b/bugs/finances/high-concurrency-and-spikes.md
@@ -1,5 +1,7 @@
# High Concurrency & Traffic Spikes
+> **Verdict pass 2026-09-03/04.** Every money claim in this file was re-checked against `dev@e1766fa2d` and the live database as part of the 2026-09-03 finance-subsystem verification. Of 9 claims, 4 are still true today, 5 have been addressed since this dossier was written, and 0 are stale. See [`docs/payments/audits/2026-09-03-finance-verdicts.md`](../../docs/payments/audits/2026-09-03-finance-verdicts.md) for the per-item disposition.
+
## Context
Money paths already assume concurrency: Redis checkout locks, Serializable isolation, wallet conditional updates, webhook dedup, payout idempotency keys, ledger sorted locks. GitHub Actions crons backstop orphans, stuck webhooks, earnings sync, refund cascade, and ledger drift. Race tests exist under `tests/typescript/race-conditions/` (webhook storms, cancel-vs-webhook).
@@ -8,12 +10,12 @@ Money paths already assume concurrency: Redis checkout locks, Serializable isola
Triaged 2026-07-12 against real code (3 verifier agents cross-checked every claim); fix wave PRs #981–#994 shipped. This dossier's claims map as follows:
-| Claim (short) | Verdict |
-|---|---|
-| Prisma pool exhaustion under long Serializable txs | 🔵 TRACKED #368 (CLOSED — pooler fix landed) |
-| Event checkout fail-closed on Redis outage | 🔵 by-design (seat safety over conversion) |
-| Consultation path leans on DB GiST if Redis fails | 🔵 handled (#440 exclusion constraint live) |
-| Cron jitter delays sweeper/cleanup | 🔵 TRACKED #866 (cron→QStash plan) |
+| Claim (short) | Verdict |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Prisma pool exhaustion under long Serializable txs | 🔵 TRACKED #368 (CLOSED — pooler fix landed) |
+| Event checkout fail-closed on Redis outage | 🔵 by-design (seat safety over conversion) |
+| Consultation path leans on DB GiST if Redis fails | 🔵 handled (#440 exclusion constraint live) |
+| Cron jitter delays sweeper/cleanup | 🔵 TRACKED #866 (cron→QStash plan) |
| Hot consultant auto-allocate lock serializes consultant | ✅ FIXED-BY #988 (#860 sharded locks; auto-allocate keeps consultant key by design, GiST backstop) |
## Known gaps / bugs
@@ -22,7 +24,7 @@ Triaged 2026-07-12 against real code (3 verifier agents cross-checked every clai
- Event checkout fail-closed on Redis outage (503) — correct for seats, harsh for conversion at peak.
- Consultation path relies more on DB GiST if Redis fails — asymmetric.
- Cron jitter (Actions) means tentative cleanup / sweeper delay under load.
-- Hot consultant auto-allocate lock serializes an entire consultant — bottleneck during flash sales.
+- Hot consultant auto-allocate lock serializing an entire consultant — the 2026-09-03 verdict pass confirmed this FIXED-BY #988 (#860 sharded locks); auto-allocate keeps the consultant key by design, with the GiST constraint as a backstop.
## Unhappy paths & user psychology
@@ -32,32 +34,35 @@ Triaged 2026-07-12 against real code (3 verifier agents cross-checked every clai
## Questions (handled?)
-1. **Load-test target for checkout QPS and webhook burst before marketing spikes?**
- - A) Formal k6/Gatling gate in CI monthly
- - B) One-off pre-launch test only
- - C) Rely on race unit suite
+1. **Load-test target for checkout QPS and webhook burst before marketing spikes?**
+ - A) Formal k6/Gatling gate in CI monthly
+ - B) One-off pre-launch test only
+ - C) Rely on race unit suite
**Recommendation: A.** Formal checkout/webhook load gates catch pool exhaustion (#368) and lock bottlenecks before marketing spikes create real chargebacks.
+
- Not B: A single pre-launch run goes stale as checkout and cron paths change.
- Not C: Race unit tests prove correctness under contention, not QPS or Prisma pool headroom.
-2. **Redis down during peak — fail closed everywhere or degrade 1:1 to DB-only?**
- - A) Fail closed all paid checkout
- - B) Events fail closed; 1:1 continue on GiST
- - C) Queue checkout intents for later processing
+2. **Redis down during peak — fail closed everywhere or degrade 1:1 to DB-only?**
+ - A) Fail closed all paid checkout
+ - B) Events fail closed; 1:1 continue on GiST
+ - C) Queue checkout intents for later processing
**Recommendation: B.** Keep event capacity fail-closed on Redis outage while 1:1 can rely on GiST as the confirmed-slot backstop.
+
- Not A: Blocking all paid checkout when GiST still protects 1:1 over-punishes consultations during a Redis blip.
- Not C: Queued intents defer money state and create worse “paid later / seat gone” psychology at peak.
> 🎯 Locked: rec B matches shipped behaviour — events fail closed on Redis, 1:1 continues on the GiST backstop.
-3. **Move booking/money crons from Actions to a real queue (#866)?**
- - A) Inngest/BullMQ near-term
- - B) Keep Actions until scale pain
- - C) Hybrid: critical sweepers on always-on worker
+3. **Move booking/money crons from Actions to a real queue (#866)?**
+ - A) Inngest/BullMQ near-term
+ - B) Keep Actions until scale pain
+ - C) Hybrid: critical sweepers on always-on worker
**Recommendation: C.** Put money-critical sweepers (webhooks, refunds, tentative cleanup) on an always-on worker while leaving lower-urgency jobs on Actions.
+
- Not A: A full near-term queue migration is speculative ops redesign ahead of fixing known refund/idempotency bugs.
- Not B: Actions jitter already delays confirmation/refund healing under load — waiting for “scale pain” risks paid users.
diff --git a/bugs/finances/incomplete-gated-stubs.md b/bugs/finances/incomplete-gated-stubs.md
index c772542a0..674f84161 100644
--- a/bugs/finances/incomplete-gated-stubs.md
+++ b/bugs/finances/incomplete-gated-stubs.md
@@ -1,5 +1,7 @@
# Incomplete, Gated & Stubbed Finance Paths
+> **Verdict pass 2026-09-03/04.** Every money claim in this file was re-checked against `dev@e1766fa2d` and the live database as part of the 2026-09-03 finance-subsystem verification. Of 13 claims, 6 are still true today, 5 have been addressed since this dossier was written, and 2 are stale. See [`docs/payments/audits/2026-09-03-finance-verdicts.md`](../../docs/payments/audits/2026-09-03-finance-verdicts.md) for the per-item disposition.
+
## Context
Much of the finance surface is schema-complete and code-complete but **gated**, **stubbed**, or **doc-only**. Shipping without knowing which gates are intentional creates false confidence.
@@ -8,38 +10,38 @@ Much of the finance surface is schema-complete and code-complete but **gated**,
Triaged 2026-07-12 against real code (3 verifier agents cross-checked every claim); fix wave PRs #981–#994 shipped. The gate/stub table below maps as follows:
-| Claim (short) | Verdict |
-|---|---|
-| `ENABLE_LIVE_PAYOUTS` off | 🔵 by-design gate |
-| `ENABLE_IRP_UPLOADER` off | 🔵 TRACKED #713 (ClearTax) |
-| Lemon Squeezy / XFlow dead routes | ✅ FIXED-BY #984 (removed) |
-| Multi-currency ledger not built | 🔵 TRACKED #783 |
-| Section 195 / non-resident blocked | 🟡 LEGIT-DEFERRED (accurate guard, by-design) |
-| Overage #715 paths partial | 🔵 TRACKED #715 (CLOSED) |
-| GST TCS collection schema-only | 🟡 LEGIT-DEFERRED (GSTR-8 batching deferred) |
-| Day-pass product doc-only | ✅ FIXED-BY #984 (mentions removed) |
-| Paid trial checkout "partial schema" | ❌ OVERSTATED — `trialPriceInPaise` is wired through checkout |
-| Org Stripe Connect deferred | 🟡 LEGIT-DEFERRED |
+| Claim (short) | Verdict |
+| ----------------------------------------------- | --------------------------------------------------------------- |
+| `ENABLE_LIVE_PAYOUTS` off | 🔵 by-design gate |
+| `ENABLE_IRP_UPLOADER` off | 🔵 TRACKED #713 (ClearTax) |
+| Lemon Squeezy / XFlow dead routes | ✅ FIXED-BY #984 (removed) |
+| Multi-currency ledger not built | 🔵 TRACKED #783 |
+| Section 195 / non-resident blocked | 🟡 LEGIT-DEFERRED (accurate guard, by-design) |
+| Overage #715 paths partial | 🔵 TRACKED #715 (CLOSED) |
+| GST TCS collection schema-only | 🟡 LEGIT-DEFERRED (GSTR-8 batching deferred) |
+| Day-pass product doc-only | ✅ FIXED-BY #984 (mentions removed) |
+| Paid trial checkout "partial schema" | ❌ OVERSTATED — `trialPriceInPaise` is wired through checkout |
+| Org Stripe Connect deferred | 🟡 LEGIT-DEFERRED |
| Payment cancellation helper warn-only → orphans | ❌ OVERSTATED — `reconcile-orphaned-confirmations` backstops it |
-| Export tax evidence (FIRC/LUT) TODO | 🟡 LEGIT-DEFERRED |
-| Dec 2025 P0 checkout task reads "Awaiting Fix" | ✅ code fixes landed; the task file was stale doc drift |
+| Export tax evidence (FIRC/LUT) TODO | 🟡 LEGIT-DEFERRED |
+| Dec 2025 P0 checkout task reads "Awaiting Fix" | ✅ code fixes landed; the task file was stale doc drift |
## Known gaps / bugs
-| Item | State | Risk if ignored |
-|------|--------|-----------------|
-| `ENABLE_LIVE_PAYOUTS` | Off by default | Consultants unpaid |
-| `ENABLE_IRP_UPLOADER` | Off / needs ClearTax | Non-compliant e-invoice at scale |
-| Lemon Squeezy / XFlow | `NOT_IMPLEMENTED` + webhook routes | Dead routes / secret surface |
-| Multi-currency ledger #783 | Deferred | Blocks true intl settlement |
-| Section 195 / non-resident | Blocked | Intl consultants cannot cash out |
-| Overage #715 paths | Partial | Some refunds/reversals refuse |
-| GST TCS collection | Schema only | GSTR-8 gap |
-| Day pass product | Skills/docs only | Product confusion |
-| Paid trial checkout | Partial schema | Trial→pay funnel broken |
-| Org Stripe Connect | Deferred | Dual-rail complexity |
-| Payment cancellation helper | Warn-only for unknown IDs | Orphan intents |
-| Export tax evidence (FIRC/LUT) | TODO in tax-engine | Audit weakness |
+| Item | State | Risk if ignored |
+| ------------------------------ | --------------------------------------------------------------- | -------------------------------- |
+| `ENABLE_LIVE_PAYOUTS` | Off by default | Consultants unpaid |
+| `ENABLE_IRP_UPLOADER` | Off / needs ClearTax | Non-compliant e-invoice at scale |
+| Lemon Squeezy / XFlow | ✅ FIXED-BY #984 (hard-removed) | n/a |
+| Multi-currency ledger #783 | Deferred | Blocks true intl settlement |
+| Section 195 / non-resident | Blocked | Intl consultants cannot cash out |
+| Overage #715 paths | Partial | Some refunds/reversals refuse |
+| GST TCS collection | Schema only | GSTR-8 gap |
+| Day pass product | ✅ FIXED-BY #984 (doc mentions removed) | n/a |
+| Paid trial checkout | ❌ overstated — `trialPriceInPaise` is wired through checkout | n/a |
+| Org Stripe Connect | Deferred | Dual-rail complexity |
+| Payment cancellation helper | ❌ overstated — `reconcile-orphaned-confirmations` backstops it | n/a |
+| Export tax evidence (FIRC/LUT) | TODO in tax-engine | Audit weakness |
Dec 2025 P0 checkout bugs appear fixed in code — the tracking file `tasks/payment-workflow-critical-bugs.md` was retired with the `tasks/` folder (commit e9471aea), closing that drift.
@@ -51,32 +53,35 @@ Dec 2025 P0 checkout bugs appear fixed in code — the tracking file `tasks/paym
## Questions (handled?)
-1. **Delete vs quarantine Stripe/Lemon/XFlow code?**
- - A) Delete unused gateways per Mar 2026 evaluation
- - B) Quarantine behind `DEPRECATED_GATEWAYS`
- - C) Keep Stripe test-only
+1. **Delete vs quarantine Stripe/Lemon/XFlow code?**
+ - A) Delete unused gateways per Mar 2026 evaluation
+ - B) Quarantine behind `DEPRECATED_GATEWAYS`
+ - C) Keep Stripe test-only
+
+**Historical recommendation (2026-07-12): B.** Quarantine unused gateways behind a deprecation flag to shrink secret/webhook surface without a risky big-bang delete of shared types.
-**Recommendation: B.** Quarantine unused gateways behind a deprecation flag to shrink secret/webhook surface without a risky big-bang delete of shared types.
- Not A: Hard delete can break residual imports and webhook routes before the evaluation cleanup is complete.
- Not C: Leaving Stripe “test-only” still keeps dual-rail complexity and asymmetric sync behavior in prod codepaths.
-> 🎯 Locked: Lemon/XFlow were hard-removed (#984); Stripe is KEPT as a live rail (not quarantined); Dodo Payments is the sanctioned post-MVP second gateway.
+> 🎯 Locked: this superseded the recommendation above — Lemon/XFlow were hard-removed (#984), not quarantined; Stripe is KEPT as a live rail; Dodo Payments is the sanctioned post-MVP second gateway.
-2. **Single source of truth for “finance ready for prod” checklist?**
- - A) This bugs pack + shipping checklist sign-off slots
- - B) Notion/Linear only
- - C) Feature-flag dashboard as checklist
+2. **Single source of truth for “finance ready for prod” checklist?**
+ - A) This bugs pack + shipping checklist sign-off slots
+ - B) Notion/Linear only
+ - C) Feature-flag dashboard as checklist
**Recommendation: A.** Keep the go-live checklist next to the audited gaps in-repo so eng and finance sign the same artifacts.
+
- Not B: Notion/Linear drift from code (as already seen on payment-workflow task status).
- Not C: Flags show what is on, not whether Path C, TDS, and IRP are actually signed off.
-3. **Are day passes on the roadmap or should skill/docs mentions be removed?**
- - A) Build schema + grant path
- - B) Remove mentions to reduce confusion
- - C) Keep as future marketing only
+3. **Are day passes on the roadmap or should skill/docs mentions be removed?**
+ - A) Build schema + grant path
+ - B) Remove mentions to reduce confusion
+ - C) Keep as future marketing only
**Recommendation: B.** Day passes are doc-only with no Prisma model — remove mentions so sales and eng stop treating them as shippable.
+
- Not A: Building a new product surface before payouts/TDS/refund P0s is growth ahead of money safety.
- Not C: “Future marketing only” still creates false confidence and support confusion.
diff --git a/bugs/finances/multi-currency-and-ledger.md b/bugs/finances/multi-currency-and-ledger.md
index 5404dd6a4..76267b68a 100644
--- a/bugs/finances/multi-currency-and-ledger.md
+++ b/bugs/finances/multi-currency-and-ledger.md
@@ -1,5 +1,7 @@
# Multi-Currency & Ledger
+> **Verdict pass 2026-09-03/04.** Every money claim in this file was re-checked against `dev@e1766fa2d` and the live database as part of the 2026-09-03 finance-subsystem verification. Of 7 claims, 3 are still true today, 4 have been addressed since this dossier was written, and 0 are stale. See [`docs/payments/audits/2026-09-03-finance-verdicts.md`](../../docs/payments/audits/2026-09-03-finance-verdicts.md) for the per-item disposition.
+
## Context
Money is modeled as integer paise with double-entry postings via `postLedgerTxn()`: deterministic ledger account IDs, sorted balance-cache updates (deadlock avoidance), COMMIT-time balance triggers, nightly `reconcile-ledgers`. Chart includes CASH, WALLET, PLATFORM_FEE, CONSULTANT_PAYABLE, ORG_PAYABLE/RECEIVABLE, TDS/GST payables, etc. Currency enum includes INR/USD/EUR/GBP, but settlement and ledger postings are **INR-only** today. International buyers may see `displayCurrencyAtCheckout` + `exchangeRateAtCheckout` as audit labels while Razorpay IBT still settles INR.
@@ -10,12 +12,12 @@ Key paths: `lib/payments/ledger/post.ts`, `lib/payments/validation/currency-guar
Triaged 2026-07-12 against real code (3 verifier agents cross-checked every claim); fix wave PRs #981–#994 shipped. This dossier's claims map as follows:
-| Claim (short) | Verdict |
-|---|---|
-| True multi-currency ledger not built | 🔵 TRACKED #783 |
+| Claim (short) | Verdict |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| True multi-currency ledger not built | 🔵 TRACKED #783 |
| Wallet cache drift possible until nightly reconcile | ✅ FIXED-BY #990 (freeze + page when reconcile `ok=false`; nightly reconcile remains) |
-| Display FX not used in refund math | 🟡 by-design (gateway settles INR) |
-| Stripe/legacy paths add mental load | 🎯 Stripe KEPT by decision |
+| Display FX not used in refund math | 🟡 by-design (gateway settles INR) |
+| Stripe/legacy paths add mental load | 🎯 Stripe KEPT by decision |
## Known gaps / bugs
@@ -32,34 +34,37 @@ Triaged 2026-07-12 against real code (3 verifier agents cross-checked every clai
## Questions (handled?)
-1. **Is INR settlement + local FX acceptable until meaningful US/EU consultant supply?**
- - A) Yes — document clearly in checkout UI
- - B) No — block non-INR buyers until #783
- - C) Dual books: display FX wallet separate from INR ledger
+1. **Is INR settlement + local FX acceptable until meaningful US/EU consultant supply?**
+ - A) Yes — document clearly in checkout UI
+ - B) No — block non-INR buyers until #783
+ - C) Dual books: display FX wallet separate from INR ledger
**Recommendation: A.** Stay INR settlement with clear checkout copy until real US/EU supply justifies #783 — matches the India-first money model already in code.
+
- Not B: Blocking all non-INR buyers cuts international consultees without fixing consultant payout reality.
- Not C: Dual display-FX books before a true multi-currency ledger invites reconcile bugs and support disputes.
> 🎯 Locked: rec A — INR settlement retained; true multi-currency stays tracked under #783.
-2. **On wallet drift detection, auto-heal from journal or page humans?**
- - A) Auto-correct cache from ledger balance
- - B) Freeze wallet + ops alert
- - C) Log only until N paise threshold
+2. **On wallet drift detection, auto-heal from journal or page humans?**
+ - A) Auto-correct cache from ledger balance
+ - B) Freeze wallet + ops alert
+ - C) Log only until N paise threshold
**Recommendation: B.** Freeze the wallet and page ops when cache drifts from the journal so further bookings cannot spend a wrong balance.
+
- Not A: Silent auto-heal can mask a posting bug and keep moving bad money.
- Not C: Log-only lets orgs keep booking against a lying denormalized balance.
> 🎯 Locked: rec B — #990 freezes the wallet and pages Sentry (P0) on reconcile `ok=false`; no silent auto-heal.
-3. **Should refunds always return gateway-settled INR, ignoring display currency?**
- - A) Yes (gateway truth)
- - B) Attempt display-currency refund where gateway supports
- - C) Credit wallet in INR equivalent only
+3. **Should refunds always return gateway-settled INR, ignoring display currency?**
+ - A) Yes (gateway truth)
+ - B) Attempt display-currency refund where gateway supports
+ - C) Credit wallet in INR equivalent only
**Recommendation: A.** Refund the gateway-settled INR amount — that is what Razorpay captured and what the ledger posted.
+
- Not B: Display-currency refunds fight IBT settlement and create amount-mismatch recovery loops.
- Not C: Wallet credit instead of gateway refund leaves the card/UPI customer unpaid.
diff --git a/bugs/finances/payouts-and-earnings.md b/bugs/finances/payouts-and-earnings.md
index ec533012c..09c815cc6 100644
--- a/bugs/finances/payouts-and-earnings.md
+++ b/bugs/finances/payouts-and-earnings.md
@@ -1,5 +1,7 @@
# Payouts & Earnings
+> **Verdict pass 2026-09-03/04.** Every money claim in this file was re-checked against `dev@e1766fa2d` and the live database as part of the 2026-09-03 finance-subsystem verification. Of 9 claims, 5 are still true today, 4 have been addressed since this dossier was written, and 0 are stale. See [`docs/payments/audits/2026-09-03-finance-verdicts.md`](../../docs/payments/audits/2026-09-03-finance-verdicts.md) for the per-item disposition.
+
## Context
Successful payments create `ConsultantEarnings` / `OrganizationEarnings` (platform fee share, hold period, refund clawback fields). Weekly crons batch READY earnings into `ConsultantPayout` / `OrganizationPayout` with unique idempotency keys, then submit via RazorpayX or Stripe Connect when `ENABLE_LIVE_PAYOUTS=true`. TDS (194-O) and MSME `mustPayByDate` attach at payout time. Path C intentionally avoids Route sub-merchant splits.
@@ -10,14 +12,14 @@ Key paths: `lib/payments/payouts/`, jobs under `.github/workflows/*payout*`.
Triaged 2026-07-12 against real code (3 verifier agents cross-checked every claim); fix wave PRs #981–#994 shipped. This dossier's claims map as follows:
-| Claim (short) | Verdict |
-|---|---|
-| Live gateway submission gated → PROCESSING/PENDING freeze | 🔵 by-design gate + CAS terminal guards |
-| Non-resident consultants blocked (Sec 195) | 🟡 LEGIT-DEFERRED (accurate guard) |
-| Org clawback after COMPLETED payout is manual | 🟡 LEGIT-DEFERRED (post-payout netting not in this wave) |
-| GST TCS fields exist, collection deferred (cites #780) | 🟡 LEGIT-DEFERRED — note #780 is misattributed (it is the BigInt money migration, not GST TCS) |
-| Form 26Q / TRACES schema-only (cites #738) | 🔵 TRACKED #737 — code cites #737, audit said #738 |
-| INVOICE earnings park in `PENDING_TRUST` "forever" | ✅/🔵 #991 rescopes the park to the sponsor and extends the #687 release valve to consultant rows; dunning-suspend is 🔵 #779 |
+| Claim (short) | Verdict |
+| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| Live gateway submission gated → PROCESSING/PENDING freeze | 🔵 by-design gate + CAS terminal guards |
+| Non-resident consultants blocked (Sec 195) | 🟡 LEGIT-DEFERRED (accurate guard) |
+| Org clawback after COMPLETED payout is manual | 🟡 LEGIT-DEFERRED (post-payout netting not in this wave) |
+| GST TCS fields exist, collection deferred (cites #780) | 🟡 LEGIT-DEFERRED — note #780 is misattributed (it is the BigInt money migration, not GST TCS) |
+| Form 26Q / TRACES schema-only (cites #738) | 🔵 TRACKED #737 — code cites #737, audit said #738 |
+| INVOICE earnings park in `PENDING_TRUST` "forever" | ✅/🔵 #991 rescopes the park to the sponsor and extends the #687 release valve to consultant rows; dunning-suspend is 🔵 #779 |
## Known gaps / bugs
@@ -37,34 +39,37 @@ Triaged 2026-07-12 against real code (3 verifier agents cross-checked every clai
## Questions (handled?)
-1. **Go-live plan for `ENABLE_LIVE_PAYOUTS`?**
- - A) Sandbox UTR reconcile → limited cohort → full prod with kill switch
- - B) Keep manual bank transfers until GMV threshold
- - C) Switch architecture to Route splits before enabling FAA
+1. **Go-live plan for `ENABLE_LIVE_PAYOUTS`?**
+ - A) Sandbox UTR reconcile → limited cohort → full prod with kill switch
+ - B) Keep manual bank transfers until GMV threshold
+ - C) Switch architecture to Route splits before enabling FAA
**Recommendation: A.** Prove sandbox UTRs, then design-partner cohort, then full prod with a kill switch — the only safe way to flip `ENABLE_LIVE_PAYOUTS`.
+
- Not B: Manual bank transfers do not exercise idempotent RazorpayX batching and hide production failure modes.
- Not C: Redesigning onto Route before FAA delays payouts and abandons Path C without a CA-driven reason.
> 🎯 Locked: rec A stands; batch earnings now move to a BATCHED status (#993) so nothing reads PAID before a UTR exists, and the flag stays the go-live gate.
-2. **What happens when INVOICE org never pays — force clawback, write-off, or suspend booking?**
- - A) Auto-suspend org after dunning stage 3 (`ENABLE_DUNNING_SUSPEND`)
- - B) Earnings stay PENDING_TRUST indefinitely (ops review)
- - C) Platform absorbs and invoices org legally
+2. **What happens when INVOICE org never pays — force clawback, write-off, or suspend booking?**
+ - A) Auto-suspend org after dunning stage 3 (`ENABLE_DUNNING_SUSPEND`)
+ - B) Earnings stay PENDING_TRUST indefinitely (ops review)
+ - C) Platform absorbs and invoices org legally
**Recommendation: A.** After dunning stage 3, auto-suspend the org so unpaid invoice funding cannot keep creating `PENDING_TRUST` earnings forever.
+
- Not B: Indefinite PENDING_TRUST strands consultants and never forces org payment.
- Not C: Platform absorption turns Familiarise into the bad-debt party for unpaid B2B bookings.
> 🎯 Locked: rec A direction — #991 rescopes the park to the sponsor (not the consultant) and dunning→suspend is tracked under #779.
-3. **Non-resident / Section 195 timeline before international consultants?**
- - A) Block non-resident until Form 15CA/CB live
- - B) Manual CA process outside product
- - C) Only allow INR-resident consultants at launch
+3. **Non-resident / Section 195 timeline before international consultants?**
+ - A) Block non-resident until Form 15CA/CB live
+ - B) Manual CA process outside product
+ - C) Only allow INR-resident consultants at launch
**Recommendation: C.** Launch with INR-resident consultants only until Section 195 / Form 15CA/CB is productized — India settlement first.
+
- Not A: “Block until 15CA/CB” still invites half-built intl onboarding UI and support exceptions.
- Not B: Manual CA outside product does not scale and will be bypassed under sales pressure.
diff --git a/bugs/finances/refunds-and-disputes.md b/bugs/finances/refunds-and-disputes.md
index ec6ae0c5a..b7f8d9891 100644
--- a/bugs/finances/refunds-and-disputes.md
+++ b/bugs/finances/refunds-and-disputes.md
@@ -1,5 +1,7 @@
# Refunds & Disputes
+> **Verdict pass 2026-09-03/04.** Every money claim in this file was re-checked against `dev@e1766fa2d` and the live database as part of the 2026-09-03 finance-subsystem verification. Of 8 claims, 2 are still true today, 5 have been addressed since this dossier was written, and 1 are stale. See [`docs/payments/audits/2026-09-03-finance-verdicts.md`](../../docs/payments/audits/2026-09-03-finance-verdicts.md) for the per-item disposition.
+
## Context
Canonical refund path is `refundPayment()` + `applyRefundCascade()` in a Serializable transaction: Refund row, reverse payment legs (wallet, invoice accrual, referral credit), reverse booking utilization, proportional earnings clawback, ledger `REFUND` posting, GST credit note minting, TDS reversal, stamp `cascadedAt`. Disputes use a legal transition guard (`dispute-status.ts`); LOST triggers earnings reversal and chargeback accounting. Razorpay disputes are webhook-only (no list API).
@@ -10,20 +12,20 @@ Key paths: `lib/payments/operations/refund.ts`, `docs/payments/refunds-disputes/
Triaged 2026-07-12 against real code (3 verifier agents cross-checked every claim); fix wave PRs #981–#994 shipped. This dossier's claims map as follows:
-| Claim (short) | Verdict |
-|---|---|
-| Tax adjustment rows incompletely wired from refund | ❌ OVERSTATED — `recordTdsReversal` (refund.ts:593) and `gstTcsAdjustment.create` (refund.ts:723) are both wired; only the `GstTcsBatch` monthly collection is deferred |
-| Overage credit-back refuses non-invoice reversals | 🔵 TRACKED #715 |
-| Org payout COMPLETED → clawback manual | 🟡 LEGIT-DEFERRED |
-| Double-booking loser holds SUCCEEDED, manual refund | ✅ FIXED-BY #990 |
-| Chargeback evidence SLA timers in admin UI | 🟡 UNVERIFIED (alert cron exists; the UI timer was not confirmed) |
+| Claim (short) | Verdict |
+| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tax adjustment rows incompletely wired from refund | ❌ OVERSTATED — `recordTdsReversal` (refund.ts:593) and `gstTcsAdjustment.create` (refund.ts:723) are both wired; only the `GstTcsBatch` monthly collection is deferred |
+| Overage credit-back refuses non-invoice reversals | 🔵 TRACKED #715 |
+| Org payout COMPLETED → clawback manual | 🟡 LEGIT-DEFERRED |
+| Double-booking loser holds SUCCEEDED, manual refund | ✅ FIXED-BY #990 |
+| Chargeback evidence SLA timers in admin UI | 🟡 UNVERIFIED (alert cron exists; the UI timer was not confirmed) |
## Known gaps / bugs
-- Cascade is strong, but some tax adjustment rows (`TdsAdjustment` / `GstTcsAdjustment`) are documented as incompletely wired from refund in compliance shipping checklist.
+- Cascade is strong; the tax adjustment rows (`TdsAdjustment` / `GstTcsAdjustment`) were documented elsewhere as incompletely wired from refund, but the 2026-09-03 verdict pass found this overstated — both are wired from `refund.ts` (`recordTdsReversal` at refund.ts:593, `gstTcsAdjustment.create` at refund.ts:723); only the monthly `GstTcsBatch` collection is deferred.
- Overage member credit-back (#715) refuses some non-invoice reversals — certain refunds may block.
- Org payout already COMPLETED → clawback is not auto-recovered from consultant/org bank.
-- Double-booking loser may hold a SUCCEEDED payment with tentative slot — refund may be ops-manual (#830).
+- Double-booking loser holding a SUCCEEDED payment with a tentative slot — the 2026-09-03 verdict pass confirmed this FIXED-BY #990.
- Chargeback evidence SLAs (documented ~7 days) may not be operationalized in admin UI timers.
## Unhappy paths & user psychology
@@ -35,32 +37,35 @@ Triaged 2026-07-12 against real code (3 verifier agents cross-checked every clai
## Questions (handled?)
-1. **Should consultant no-show auto-trigger full refund?**
- - A) Auto from MeetingAttendance / UNVERIFIED after SLA
- - B) Support-only with scripted playbook
- - C) Partial credit note + mandatory reschedule
+1. **Should consultant no-show auto-trigger full refund?**
+ - A) Auto from MeetingAttendance / UNVERIFIED after SLA
+ - B) Support-only with scripted playbook
+ - C) Partial credit note + mandatory reschedule
**Recommendation: A.** Policy already promises full refund on consultant no-show — automate from MeetingAttendance / UNVERIFIED after SLA (#471) instead of hoping support catches it.
+
- Not B: Support-only leaves paid consultees waiting and contradicts published refund copy.
- Not C: Partial credit plus forced reschedule underpays the customer relative to the promised full refund.
> 🎯 Locked: rec A — no-show refunds are automated in #992 (#471) for consultations; subscriptions remain a deferred TODO#471.
-2. **Refund vs dispute race — which wins as product policy?**
- - A) Dispute freezes refund UI; finance owns
- - B) Refund completes; dispute maps to already-refunded
- - C) Always escalate to human before either terminal state
+2. **Refund vs dispute race — which wins as product policy?**
+ - A) Dispute freezes refund UI; finance owns
+ - B) Refund completes; dispute maps to already-refunded
+ - C) Always escalate to human before either terminal state
**Recommendation: A.** Freeze in-product refunds when a dispute opens so finance owns one recovery path and two devices cannot fight each other.
+
- Not B: Completing refunds while a dispute is open risks double recovery and confused chargeback evidence.
- Not C: Human-gating every terminal state recreates ticket latency on an already Serializable money path.
-3. **Post-payout clawback — auto debit next earnings or legal invoice?**
- - A) Net against next ConsultantPayout batch
- - B) Manual collection only (current v1 leaning)
- - C) Hold future bookings until clawback cleared
+3. **Post-payout clawback — auto debit next earnings or legal invoice?**
+ - A) Net against next ConsultantPayout batch
+ - B) Manual collection only (current v1 leaning)
+ - C) Hold future bookings until clawback cleared
**Recommendation: A.** Net clawbacks against the next payout batch so refunded sessions do not permanently strand platform receivables after COMPLETED payouts.
+
- Not B: Manual collection does not scale and leaves `clawbackAmount` growing with no recovery path.
- Not C: Holding future bookings punishes consultees and consultants for a finance recovery problem.
diff --git a/bugs/finances/tax-gst-tds-invoicing.md b/bugs/finances/tax-gst-tds-invoicing.md
index 0c3308690..efe77890f 100644
--- a/bugs/finances/tax-gst-tds-invoicing.md
+++ b/bugs/finances/tax-gst-tds-invoicing.md
@@ -1,5 +1,7 @@
# Tax, GST, TDS & Invoicing
+> **Verdict pass 2026-09-03/04.** Every money claim in this file was re-checked against `dev@e1766fa2d` and the live database as part of the 2026-09-03 finance-subsystem verification. Of 11 claims, 8 are still true today, 1 have been addressed since this dossier was written, and 2 are stale. See [`docs/payments/audits/2026-09-03-finance-verdicts.md`](../../docs/payments/audits/2026-09-03-finance-verdicts.md) for the per-item disposition.
+
## Context
B2B enterprise tax is relatively mature: GST breakdown (`lib/compliance/gst.ts`), org invoices with sequential numbering, credit notes, MSME 43B(h) dates, TDS derivation for org payouts, IRP uploader gated by `ENABLE_IRP_UPLOADER`. B2C marketplace tax is weaker: wrong/legacy TDS path risk, GST TCS Sec 52 schema-only, place-of-supply state not captured at consumer checkout, legal docs still have placeholders elsewhere.
@@ -10,21 +12,21 @@ Key paths: `lib/compliance/`, `lib/payments/tax/`, `docs/compliance/15-india-com
Triaged 2026-07-12 against real code (3 verifier agents cross-checked every claim); fix wave PRs #981–#994 shipped. This dossier's claims map as follows:
-| Claim (short) | Verdict |
-|---|---|
-| B2C consultant TDS still on 194J (P0) | ❌ STALE — 194-O is live via `computeTdsForPayout` (payout-service.ts:592-607) |
-| GST TCS / GSTR-8 batching not wired (`GstTcsBatch`) | 🟡 LEGIT-DEFERRED |
-| Refund tax cascade incomplete | ❌ OVERSTATED — `TdsAdjustment` (reversal) and `GstTcsAdjustment` are both wired from `refund.ts` |
-| Form 15CA/CB stub returns nulls | 🟡 LEGIT-DEFERRED (explicit stub in `form15.ts`) |
-| IRN filing gated (ClearTax) | 🔵 TRACKED #713 |
-| HSN defaults static | 🟡 LEGIT-DEFERRED |
-| Consultant GSTIN format-only, no registry check | 🟡 LEGIT-DEFERRED |
+| Claim (short) | Verdict |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| B2C consultant TDS still on 194J (P0) | ❌ STALE — 194-O is live via `computeTdsForPayout` (payout-service.ts:592-607) |
+| GST TCS / GSTR-8 batching not wired (`GstTcsBatch`) | 🟡 LEGIT-DEFERRED |
+| Refund tax cascade incomplete | ❌ OVERSTATED — `TdsAdjustment` (reversal) and `GstTcsAdjustment` are both wired from `refund.ts` |
+| Form 15CA/CB stub returns nulls | 🟡 LEGIT-DEFERRED (explicit stub in `form15.ts`) |
+| IRN filing gated (ClearTax) | 🔵 TRACKED #713 |
+| HSN defaults static | 🟡 LEGIT-DEFERRED |
+| Consultant GSTIN format-only, no registry check | 🟡 LEGIT-DEFERRED |
## Known gaps / bugs
-- **P0:** B2C consultant TDS may still use deprecated 194J@10% path vs required 194-O@0.1% for e-commerce operator style flows.
+- B2C consultant TDS on the deprecated 194J@10% path — the 2026-09-03 verdict pass marked this stale: 194-O is already live via `computeTdsForPayout` (payout-service.ts:592-607).
- GST TCS / GSTR-8 batching not wired (`GstTcsBatch` schema-only).
-- Refund tax cascade incomplete for some adjustment models.
+- Refund tax cascade incomplete for some adjustment models — the 2026-09-03 verdict pass marked this overstated: `TdsAdjustment` and `GstTcsAdjustment` are both wired from `refund.ts`.
- Form 15CA/CB stub returns nulls — cross-border payouts blocked/deferred.
- IRN filing gated; ClearTax credentials required.
- HSN defaults static; webinar/class may need different codes.
@@ -39,34 +41,37 @@ Triaged 2026-07-12 against real code (3 verifier agents cross-checked every clai
## Questions (handled?)
-1. **Consolidate TDS engines before any B2C live payout?**
- - A) Hard cutover to `lib/compliance/tds.ts` only, CA-signed rates
- - B) Keep dual until B2C GMV threshold
- - C) Outsource all TDS calc to CA spreadsheet
+1. **Consolidate TDS engines before any B2C live payout?**
+ - A) Hard cutover to `lib/compliance/tds.ts` only, CA-signed rates
+ - B) Keep dual until B2C GMV threshold
+ - C) Outsource all TDS calc to CA spreadsheet
**Recommendation: A.** Wrong 194J vs 194-O rates on live B2C payouts is a P0 expert-trust and compliance failure — cut over to one CA-signed engine first.
+
- Not B: Dual engines until a GMV threshold guarantees some consultants are under-withheld or over-withheld in prod.
- Not C: Spreadsheet TDS cannot stay consistent with ledger clawbacks and concurrent payout batches.
> 🎯 Locked: the premise is ❌ STALE — the consultant payout path already withholds at 194-O via `computeTdsForPayout`, so no cutover is required.
-2. **When does GSTR-8 / TCS become launch-blocking?**
- - A) Before first B2C payout
- - B) After N consultants registered
- - C) Defer with CA retainer filing manually
+2. **When does GSTR-8 / TCS become launch-blocking?**
+ - A) Before first B2C payout
+ - B) After N consultants registered
+ - C) Defer with CA retainer filing manually
**Recommendation: C.** After TDS unification, design-partner GSTR-8 can be filed via CA retainer until collection volume justifies productized TCS batches.
+
- Not A: Blocking every B2C payout on schema-only `GstTcsBatch` stalls Path C after the higher-priority TDS fix.
- Not B: Consultant headcount is a weak proxy for TCS liability and still leaves early GMV unfiled.
> 🎯 Locked: rec C — GST TCS / GSTR-8 batching is LEGIT-DEFERRED; file via CA retainer until volume justifies productised TCS.
-3. **IRP — enable for all orgs or only above AATO?**
- - A) Flag on for everyone with ClearTax
- - B) PENDING IRN below threshold
- - C) PDF-only until first audit
+3. **IRP — enable for all orgs or only above AATO?**
+ - A) Flag on for everyone with ClearTax
+ - B) PENDING IRN below threshold
+ - C) PDF-only until first audit
**Recommendation: B.** Keep IRN pending below AATO and enable ClearTax IRP where the threshold actually requires it.
+
- Not A: Forcing IRP for every org adds ClearTax cost/ops before legal necessity.
- Not C: PDF-only past the threshold is non-compliant once e-invoicing applies.
diff --git a/components/Navbar.tsx b/components/Navbar.tsx
index 1f9837e8a..b0ef57efa 100644
--- a/components/Navbar.tsx
+++ b/components/Navbar.tsx
@@ -44,6 +44,7 @@ import {
AccordionTrigger,
} from "@/components/ui/accordion";
import { useCurrency, SUPPORTED_CURRENCIES } from "@/hooks/useCurrency";
+import { RATE_PROVIDER_NAME, RATE_PROVIDER_URL } from "@/lib/currency-codes";
import { resolveAuthView, useRememberedAuth } from "@/hooks/useRememberedAuth";
import { hasDarkHero, isChromeHidden } from "@/lib/navigation/public-chrome";
import { useAnnouncementBar } from "@/providers/AnnouncementBarProvider";
@@ -369,13 +370,7 @@ function DesktopDropdownPanel({
: undefined
}
>
-
+
{group.columns.map((column) => (
{isMega && (
@@ -533,7 +528,7 @@ const Navbar = () => {
const isAuthedView = authView.mode === "authed";
const [isOpen, setIsOpen] = useState(false);
const [isScrolled, setIsScrolled] = useState(false);
- const { currency, symbol, setCurrency } = useCurrency();
+ const { currency, symbol, setCurrency, isEstimate } = useCurrency();
const { isVisible: isAnnouncementVisible } = useAnnouncementBar();
// Route lists live in lib/navigation/public-chrome.ts — they were duplicated
@@ -681,6 +676,27 @@ const Navbar = () => {
+ {/* #1396 — ExchangeRate-API's Open Access licence requires this
+ attribution wherever its rates are shown, and the switcher is
+ where a visitor turns those rates on. Rendered only while the
+ prices really are converted: `isEstimate` is false for INR and
+ false during the no-rate degrade, when nothing on the page is
+ the provider's work. */}
+ {isEstimate && (
+
+ Rates by {RATE_PROVIDER_NAME}
+
+ )}
+
{authView.mode === "unknown" ? (
@@ -736,206 +752,217 @@ const Navbar = () => {
{/* Mobile Drawer — CSS transitions only; framer-motion was pulled into
- every public page via the root navbar for enter/exit polish. */}
+ every public page via the root navbar for enter/exit polish.
+ #1414 — both entrances are motion-safe: gated; with reduced motion
+ requested they render in their final position, unanimated. */}
{isOpen && (
- <>
- {/* Backdrop — native button so keyboard/AT get a real interactive
+ <>
+ {/* Backdrop — native button so keyboard/AT get a real interactive
control (Sonar typescript:S6848 / S1082). */}
-
+
+
+ {/* Drawer */}
+
+ {/* Drawer Header */}
+
- {/* Drawer */}
+ {/* Navigation — Accordion Sections */}
- {/* Drawer Header */}
-
+
Dashboard
+
+ )}
- {/* Navigation — Accordion Sections */}
-
- {isAuthedView && (
-
+ {NAV_GROUPS.map((group) => (
+
- Dashboard
-
- )}
-
-
- {NAV_GROUPS.map((group) => (
-
-
- {group.label}
-
-
-
- {group.columns.map((column) => (
-
- {/* Column headings only earn their space when
+
+ {group.label}
+
+
+
+ {group.columns.map((column) => (
+
+ {/* Column headings only earn their space when
there's more than one column to separate. */}
- {group.columns.length > 1 && (
-
- {column.heading}
-
- )}
- {column.items.map((item) => (
-
-
- {item.label}
- {item.disabled && (
-
- Soon
-
- )}
-
-
- {item.description}
-
-
- ))}
-
- ))}
-
- {/* Category chips on mobile */}
- {group.categoryChips &&
- group.categoryChips.length > 0 && (
-
-
- By Category
-
-
- {group.categoryChips.map((chip) => (
-
- {chip.label}
-
- ))}
-
-
+ {group.columns.length > 1 && (
+
+ {column.heading}
+
)}
-
-
- ))}
-
+ {column.items.map((item) => (
+
+
+ {item.label}
+ {item.disabled && (
+
+ Soon
+
+ )}
+
+
+ {item.description}
+
+
+ ))}
+
+ ))}
+
+ {/* Category chips on mobile */}
+ {group.categoryChips &&
+ group.categoryChips.length > 0 && (
+
+
+ By Category
+
+
+ {group.categoryChips.map((chip) => (
+
+ {chip.label}
+
+ ))}
+
+
+ )}
+
-
- Currency
-
-
- {SUPPORTED_CURRENCIES.map((c) => (
-
- ))}
-
+ {/* Mobile Currency Selector */}
+
+
+ Currency
+
+
+ {SUPPORTED_CURRENCIES.map((c) => (
+
+ ))}
+ {/* Same licence term as the desktop switcher above. */}
+ {isEstimate && (
+
+ Rates by {RATE_PROVIDER_NAME}
+
+ )}
+
- {authView.mode === "unknown" ? (
+ {/* User Section */}
+
+ {authView.mode === "unknown" ? (
+
+
+
+
+ ) : isAuthedView ? (
+
-
-
-
- ) : isAuthedView ? (
-
-
-
-
-
- {authView.name?.charAt(0) ?? "U"}
-
-
-
- {authView.name}
-
-
-
+
+
+
+ {authView.name?.charAt(0) ?? "U"}
+
+
+
+ {authView.name}
+
- ) : (
- /* Mirrors the desktop bar: no marketing CTAs, sign in only. */
- )}
-
+
+ ) : (
+ /* Mirrors the desktop bar: no marketing CTAs, sign in only. */
+
+ )}
+
+ )}
);
};
diff --git a/components/appointments/HeldSlotBadge.tsx b/components/appointments/HeldSlotBadge.tsx
new file mode 100644
index 000000000..cb04e2bf5
--- /dev/null
+++ b/components/appointments/HeldSlotBadge.tsx
@@ -0,0 +1,62 @@
+"use client";
+
+import { format } from "date-fns";
+import { useHoldCountdown } from "@/hooks/useHoldCountdown";
+import { cn } from "@/utils/tailwind";
+
+interface HeldSlotBadgeProps {
+ /** Payment.expiresAt for the pending payment holding this slot. */
+ deadline: Date | null;
+ className?: string;
+}
+
+/**
+ * #1428 — a tentative slot with no visible deadline reads as "the platform
+ * lost my booking." This names the state and ticks down against it via the
+ * shared `useHoldCountdown` hook, so SessionTimeline's held row and any
+ * future held-slot surface agree on when a hold has actually lapsed.
+ */
+export function HeldSlotBadge({ deadline, className }: HeldSlotBadgeProps) {
+ const { minutesLeft, isExpired } = useHoldCountdown(deadline);
+
+ if (!deadline) {
+ return (
+
+ Held
+
+ );
+ }
+
+ if (isExpired) {
+ return (
+
+ Hold expired
+
+ );
+ }
+
+ return (
+
+ Held until {format(deadline, "h:mm a")} ·{" "}
+ {/* minutesLeft floors, so 0 is the live final minute, not a lapsed
+ hold — "0m left" next to an active CTA reads as broken. */}
+ {minutesLeft === 0 ? "under a minute left" : `${minutesLeft}m left`}
+
+ );
+}
diff --git a/components/appointments/SessionTimeline.tsx b/components/appointments/SessionTimeline.tsx
index 4a2d7252c..1cc2f3b18 100644
--- a/components/appointments/SessionTimeline.tsx
+++ b/components/appointments/SessionTimeline.tsx
@@ -2,7 +2,7 @@
import { useEffect, useMemo, useState } from "react";
import { format } from "date-fns";
-import { Video, Loader2, ChevronDown } from "lucide-react";
+import { Video, Loader2, ChevronDown, CreditCard } from "lucide-react";
import { cn } from "@/utils/tailwind";
import {
CONSULTEE_JOIN_WINDOW_MS,
@@ -12,6 +12,7 @@ import {
} from "@/lib/appointments/slots";
import type { SessionVM } from "@/lib/appointments/view-model";
import { CountdownBadge } from "./CountdownBadge";
+import { HeldSlotBadge } from "./HeldSlotBadge";
/**
* Per-session timeline for multi-session (and one-off) appointments.
@@ -40,6 +41,17 @@ interface SessionTimelineProps {
* Defaults to true so multi-session plans show the full list.
*/
defaultExpanded?: boolean;
+ /**
+ * #1428 — opt-in: render tentative (held-pending-payment) sessions instead
+ * of silently dropping them. Off by default so AppointmentSheet and
+ * RequestSlotAllocationTab, which never learned a hold deadline, keep
+ * their existing tentative-is-invisible behaviour.
+ */
+ showHeld?: boolean;
+ /** Payment.expiresAt for the hold backing the tentative session(s). */
+ holdDeadline?: Date | null;
+ /** Absent ⇒ held rows show "awaiting payment" with no action (consultant view). */
+ onCompletePayment?: () => void;
}
interface SessionGroup {
@@ -136,6 +148,9 @@ export function SessionTimeline({
joinWindowMs = CONSULTEE_JOIN_WINDOW_MS,
className,
defaultExpanded = true,
+ showHeld = false,
+ holdDeadline = null,
+ onCompletePayment,
}: SessionTimelineProps) {
const [expanded, setExpanded] = useState(defaultExpanded);
useEffect(() => {
@@ -146,7 +161,16 @@ export function SessionTimeline({
() => sessions.filter((s) => !s.isTentative),
[sessions],
);
+ // #1428 — tentative sessions used to be dropped outright here, so a
+ // consultee holding reserved slots with a live payment deadline saw
+ // nothing at all. Kept as its own list (never mixed into `groups`) so the
+ // held row's countdown/CTA styling doesn't leak into the confirmed rules.
+ const tentative = useMemo(
+ () => (showHeld ? sessions.filter((s) => s.isTentative) : []),
+ [sessions, showHeld],
+ );
const groups = useMemo(() => toSessionGroups(nonTentative), [nonTentative]);
+ const heldGroups = useMemo(() => toSessionGroups(tentative), [tentative]);
const showExpand = groups.length > 1;
const groupStatuses = useMemo(
@@ -178,7 +202,7 @@ export function SessionTimeline({
return upcoming ?? groups[groups.length - 1];
}, [groups, groupStatuses]);
- if (groups.length === 0) return null;
+ if (groups.length === 0 && heldGroups.length === 0) return null;
const visibleGroups =
showExpand && !expanded && focusGroup ? [focusGroup] : groups;
@@ -195,6 +219,54 @@ export function SessionTimeline({
return (
+ {heldGroups.map((group) => (
+
.
+ >
+
+ ⏳
+
+
+
+
+ {format(group.startTime, "MMM d")}
+
+
+ {format(group.startTime, "h:mm a")}
+ {" - "}
+ {format(group.endTime, "h:mm a")}
+
+
+
+
+
+ {onCompletePayment ? (
+
+ ) : (
+
+ Awaiting payment
+
+ )}
+
+
+ ))}
+
{showExpand && !expanded && (
{collapsedCaption}
diff --git a/components/appointments/detail/AppointmentDetailClient.tsx b/components/appointments/detail/AppointmentDetailClient.tsx
index a67e94fd4..1d6d68564 100644
--- a/components/appointments/detail/AppointmentDetailClient.tsx
+++ b/components/appointments/detail/AppointmentDetailClient.tsx
@@ -34,6 +34,7 @@ import {
type PaymentDisplayStatus,
} from "@/lib/labels/session-labels";
import { useSession } from "@/lib/auth-client";
+import { useHoldCountdown } from "@/hooks/useHoldCountdown";
import { formatCurrencyAmount } from "@/utils/formatting";
import { CountdownBadge } from "../CountdownBadge";
import { KIND_LABEL } from "../AppointmentRow";
@@ -47,6 +48,35 @@ import { SessionReviewCard } from "@/components/reviews/SessionReviewCard";
const PARTICIPANTS_PREVIEW = 5;
+/**
+ * #1428 — the single answer to "what may the payer do about this tentative
+ * hold right now", so the timeline row and the payment card cannot drift.
+ *
+ * Past `Payment.expiresAt` the hold is already DEAD for availability
+ * (`buildDeadHoldFilter`, utils/slotAllocation/occupancyPolicy.ts counts a
+ * PENDING payment with a lapsed window as free), so another buyer can take
+ * the slot before any sweep runs. Checkout also refuses to resume a stale
+ * order (`findReusablePendingOrderPayment` matches only `expiresAt > now`)
+ * and mints a fresh one instead. Paying the old link would therefore capture
+ * onto a released slot and land in the #1439 terminal-race refund — so the
+ * lapsed state offers a new checkout, not the dead "Pay now".
+ */
+type TentativeHoldCta = "PAY" | "REBOOK" | "NONE";
+
+function tentativeHoldCta(args: {
+ isConsultee: boolean;
+ holdDeadline: Date | null;
+ holdExpired: boolean;
+ pendingPaymentUrl: string | null;
+}): TentativeHoldCta {
+ // The consultant sees held slots read-only; only the payer gets an action.
+ if (!args.isConsultee) return "NONE";
+ // No deadline at all is not a lapse — useHoldCountdown reports a null
+ // deadline as expired, which would otherwise mis-read as "released".
+ if (args.holdDeadline !== null && args.holdExpired) return "REBOOK";
+ return args.pendingPaymentUrl ? "PAY" : "NONE";
+}
+
function initials(name: string): string {
return name
.split(/\s+/)
@@ -56,13 +86,7 @@ function initials(name: string): string {
.join("");
}
-function Section({
- title,
- children,
-}: {
- title: string;
- children: ReactNode;
-}) {
+function Section({ title, children }: { title: string; children: ReactNode }) {
return (
@@ -133,6 +157,24 @@ export function AppointmentDetailClient({
const mapped = detail ? mapAppointmentDetail(detail, role) : null;
useSetBreadcrumbLabel(mapped?.vm.title);
+ const payments = detail?.appointment.payment ?? [];
+ // #1428 — the tentative-hold deadline: the soonest still-pending payment
+ // guarding a held slot on this booking. Derived ABOVE the loading/error
+ // returns because useHoldCountdown below it is a hook and may not sit
+ // behind a conditional return.
+ const holdDeadline =
+ payments
+ .filter((p) => p.paymentStatus === "PENDING" && p.expiresAt)
+ .map((p) => new Date(p.expiresAt!))
+ .sort((a, b) => a.getTime() - b.getTime())[0] ?? null;
+ const { isExpired: holdExpired } = useHoldCountdown(holdDeadline);
+ const tentativeCta = tentativeHoldCta({
+ isConsultee: role === "consultee",
+ holdDeadline,
+ holdExpired,
+ pendingPaymentUrl: mapped?.vm.pendingPaymentUrl ?? null,
+ });
+
if (isLoading && !detail) {
return (
@@ -168,7 +210,6 @@ export function AppointmentDetailClient({
.overflowItems(vm)
.filter((item) => item.key !== "reschedule-proposal");
const badge = eventUnionStatusBadge(vm.status);
- const payments = detail.appointment.payment ?? [];
const orgName =
detail.appointment.organization?.name ??
resolveSponsoringOrgName(
@@ -192,6 +233,12 @@ export function AppointmentDetailClient({
? vm.sessions.find((s) => s.startsAt.getTime() === vm.nextAt?.getTime())
: undefined;
const hasConfirmedSessions = vm.sessions.some((s) => !s.isTentative);
+ const hasTentativeSessions = vm.sessions.some((s) => s.isTentative);
+ const openPendingPayment = () => {
+ if (vm.pendingPaymentUrl && /^https?:\/\//.test(vm.pendingPaymentUrl)) {
+ window.open(vm.pendingPaymentUrl, "_blank", "noopener,noreferrer");
+ }
+ };
// #1163 — the read narrows to open statuses and takes one, so [0] is THE
// live proposal; the card is the answer surface "Awaiting schedule
// confirmation" never offered.
@@ -347,7 +394,7 @@ export function AppointmentDetailClient({
)}
- {hasConfirmedSessions ? (
+ {hasConfirmedSessions || hasTentativeSessions ? (
action.onClick!()
: undefined
}
+ showHeld
+ holdDeadline={holdDeadline}
+ // #1428 — consultee sees the CTA while the window is live;
+ // the consultant, and anyone once the hold has lapsed, sees
+ // the same held row read-only ("awaiting payment").
+ onCompletePayment={
+ tentativeCta === "PAY" ? openPendingPayment : undefined
+ }
/>
) : (
- {vm.sessions.length > 0
- ? "Awaiting schedule confirmation."
- : "No sessions scheduled yet."}
+ No sessions scheduled yet.
)}
@@ -405,24 +458,60 @@ export function AppointmentDetailClient({
This booking is sponsored by
{orgName}.
)}
- {vm.needsActionReason === "PAY_NOW" &&
- vm.pendingPaymentUrl && (
-
+ {/* #1428 — TENTATIVE (held pending payment) reaches this
+ branch too now, gated by the same `tentativeHoldCta`
+ the timeline row uses; PAY_NOW's existing (role-agnostic)
+ behaviour is unchanged. */}
+ {((vm.needsActionReason === "PAY_NOW" &&
+ vm.pendingPaymentUrl) ||
+ (vm.needsActionReason === "TENTATIVE" &&
+ tentativeCta === "PAY")) && (
+
+ )}
+ {vm.needsActionReason === "TENTATIVE" &&
+ tentativeCta === "REBOOK" && (
+
+
+ The payment window for this hold closed, so the slot
+ is released unless you book it again.
+
+ {/* Back to the consultant's profile rather than a
+ deep link to the old slot: that time may already
+ be taken, and the picker is where a live one is
+ chosen. */}
+
+
)}
)}
diff --git a/components/billing/BillingBlockBanner.tsx b/components/billing/BillingBlockBanner.tsx
new file mode 100644
index 000000000..2da4df6cf
--- /dev/null
+++ b/components/billing/BillingBlockBanner.tsx
@@ -0,0 +1,46 @@
+import Link from "next/link";
+import { Lock } from "lucide-react";
+
+interface BillingBlockBannerProps {
+ walletFrozen: boolean;
+ walletFrozenReason?: string | null;
+ dunningSuspended: boolean;
+ /** Support deep-link — kept a prop rather than hardcoded so callers on
+ * different surfaces (billing page vs. org home) can each point at
+ * whatever support entry point they already render. */
+ supportHref: string;
+}
+
+/**
+ * #1427/#1430 — one banner for both silent-block states so the two never
+ * drift into slightly different copy/styling (Sonar's 3% new-code
+ * duplication gate would also just fail a second near-identical component).
+ * Freeze takes priority when both are somehow true at once — it is the more
+ * severe state (ops has to reconcile a balance, not just collect a payment).
+ */
+export function BillingBlockBanner({
+ walletFrozen,
+ walletFrozenReason,
+ dunningSuspended,
+ supportHref,
+}: BillingBlockBannerProps) {
+ if (!walletFrozen && !dunningSuspended) return null;
+
+ const message = walletFrozen
+ ? (walletFrozenReason ??
+ "Wallet spend is paused pending a balance-reconciliation review.")
+ : "Bookings are paused until the overdue invoice is settled.";
+
+ return (
+
+
+
+ {message}{" "}
+
+ Contact support
+ {" "}
+ for help resolving this.
+
+
+ );
+}
diff --git a/components/dashboard/shared/PaymentDetailPage.tsx b/components/dashboard/shared/PaymentDetailPage.tsx
index 822d5a205..31bcc031f 100644
--- a/components/dashboard/shared/PaymentDetailPage.tsx
+++ b/components/dashboard/shared/PaymentDetailPage.tsx
@@ -18,6 +18,19 @@ import type {
// read-only: operators can see refund history that the system wrote from
// automated paths (gateway-originated refunds, dispute resolutions).
+/**
+ * Dispute states with a verdict behind them. Everything else is a proceeding
+ * still in motion, and the gateway can advance it at any moment without the
+ * operator doing anything — which is what the poll below is for.
+ */
+const TERMINAL_DISPUTE_STATUSES = new Set([
+ "WON",
+ "LOST",
+ "CHARGE_REFUNDED",
+ "CLOSED",
+ "WARNING_CLOSED",
+]);
+
async function fetchPaymentDetails(paymentId: string): Promise
{
const response = await fetch(`/api/admin/payments/${paymentId}`);
if (!response.ok) {
@@ -47,6 +60,18 @@ export function PaymentDetailPage({
queryKey: ["admin-payment", resolvedParams.paymentId],
queryFn: () => fetchPaymentDetails(resolvedParams.paymentId),
staleTime: 30 * 1000,
+ // #1352 — a live dispute moves on the gateway's clock, not ours: the
+ // webhook advances the row while the operator is sitting on this page
+ // deciding whether to refund, and a 30-second stale window with no refetch
+ // meant they could act on a status the platform had already superseded.
+ // Poll only while a verdict is still outstanding; a resolved dispute never
+ // changes again, so it goes back to costing nothing.
+ refetchInterval: (query) =>
+ query.state.data?.disputes?.some(
+ (dispute) => !TERMINAL_DISPUTE_STATUSES.has(dispute.status),
+ )
+ ? 15 * 1000
+ : false,
});
if (error) {
@@ -172,6 +197,26 @@ export function PaymentDetailPage({
)}
+ {/* #1365 — the statutory B2C tax invoice. Absent for org-funded
+ payments, which are invoiced to the organization instead. */}
+
+
+ {payment.consumerInvoice ? (
+
+
+ {payment.consumerInvoice.invoiceNumber}
+
+
+ Download
+
+
+ ) : (
+
Not issued
+ )}
+
diff --git a/components/dashboard/shared/PaymentsPage.tsx b/components/dashboard/shared/PaymentsPage.tsx
index b160c2a6b..5408443ed 100644
--- a/components/dashboard/shared/PaymentsPage.tsx
+++ b/components/dashboard/shared/PaymentsPage.tsx
@@ -60,6 +60,26 @@ export interface PaymentsPageProps {
basePath: string;
}
+/**
+ * #1365 — the B2C tax invoice for a payment. Defined at module scope, not
+ * inside the page, so it is never re-created on a render (S6478). An empty
+ * cell means the payment was org-funded and is invoiced to the organization
+ * instead, which is the correct answer rather than a gap to chase.
+ */
+function renderInvoiceCell(payment: Payment) {
+ if (!payment.consumerInvoice) {
+ return
—;
+ }
+ return (
+
+ {payment.consumerInvoice.invoiceNumber}
+
+ );
+}
+
export function PaymentsPage({ basePath }: PaymentsPageProps) {
const [page, setPage] = useState(1);
const [status, setStatus] = useState
();
@@ -157,6 +177,11 @@ export function PaymentsPage({ basePath }: PaymentsPageProps) {
—
),
},
+ {
+ key: "invoice",
+ header: "Invoice",
+ cell: renderInvoiceCell,
+ },
{
key: "date",
header: "Date",
diff --git a/components/dashboard/shared/RefundsPage.tsx b/components/dashboard/shared/RefundsPage.tsx
index 23dcd4173..b571716d8 100644
--- a/components/dashboard/shared/RefundsPage.tsx
+++ b/components/dashboard/shared/RefundsPage.tsx
@@ -2,10 +2,10 @@
import { useState, useEffect } from "react";
import { useQuery } from "@tanstack/react-query";
-// `formatCurrencyAmount`, not `formatCurrencyFromMajorUnit`: refunds carry
-// paise. The old call had both halves wrong — a field the payload has never
-// contained, passed to the rupees formatter — so it rendered ₹NaN rather than
-// a number that was merely 100× too large.
+// `formatCurrencyAmount`, not the old major-unit formatter (deleted in #1396):
+// refunds carry paise. The old call had both halves wrong — a field the payload
+// has never contained, passed to the rupees formatter — so it rendered ₹NaN
+// rather than a number that was merely 100× too large.
import { formatCurrencyAmount } from "@/utils/formatting";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { Badge } from "@/components/ui/badge";
diff --git a/docs/booking/00-architecture-decisions.md b/docs/booking/00-architecture-decisions.md
index a5a8d2c5b..092213a22 100644
--- a/docs/booking/00-architecture-decisions.md
+++ b/docs/booking/00-architecture-decisions.md
@@ -112,4 +112,6 @@ A `version` column with compare-and-set on write exists on four enterprise model
Every guarded transition in `lib/booking/transitions.ts` appends one row to `BookingStatusHistory` in the same transaction as the state change, carrying the entity kind, the entity id, the from and to statuses, and optional actor, reason and organisation attribution. This is the audit trail that reschedule and cancel disputes needed and that support and staff views read. It is written by the helpers rather than by a database trigger because the helpers already receive the transaction and the actor, and because the seven lifecycles share three different status enums, which is why `fromStatus` and `toStatus` are strings and `entityId` is polymorphic.
+Two amendments landed in wave 6 (#1333), both about making the trail resolvable. The first is that the pre-image read below also fetches the row's owning appointment, so `appointmentId` is stamped without the caller supplying it; before that amendment the column existed and no caller ever filled it, which left the timeline resolving everything through the polymorphic entity keys. It stays null in the two cases where there is genuinely no single appointment to name — a subscription or class that owns several live appointments, and a trial that has not been scheduled yet — so the entity arms of the reader's query remain load-bearing rather than transitional. The second is that creation now writes a row of its own through `appendCreationHistory`, in the same transaction as the create, because creation is not a transition and a freshly created booking therefore had no history at all. Its from-status is the literal `"CREATED"` rather than the `"UNKNOWN"` sentinel described below, which would have told an operator that a race occurred.
+
The from-status is read with a `findUnique` immediately before the compare-and-set update, because an `updateMany` cannot return the row's previous value. A second legal transition committing between that read and the update can therefore log a stale from-status. That imprecision is accepted: it can only affect an append-only audit row, never the state change itself, and the alternative of narrowing the compare-and-set to the observed value would have turned legitimate concurrent moves into spurious conflicts across roughly forty call sites. There is no outbox or dispatcher on this table; notifications keep their existing paths, and a drainer is only worth adding once the platform has a queue that is not the throttled GitHub Actions cron fleet.
diff --git a/docs/booking/05-troubleshooting-and-changelog.md b/docs/booking/05-troubleshooting-and-changelog.md
index 98c0851f3..1bd03feb5 100644
--- a/docs/booking/05-troubleshooting-and-changelog.md
+++ b/docs/booking/05-troubleshooting-and-changelog.md
@@ -87,6 +87,9 @@ flowchart TD
## Changelog: 2026-09-03 — wave 6
+Wave 6 finishes the doctrine cleanups that waves 1-5 started. Each PR appends its own subsection here.
+Wave 6 picks up the follow-ups that wave 5 left marked in the code. Each PR appends its own subsection here.
+
### PR 0 — the gateway loads at call time, and test keys on production need an explicit opt-out (`fix/gateway-lazy-import-and-test-key-optout`)
- **Cancel, cancel preview, reject and checkout returned a bare 500 page on production.** The post-release verification on 2026-09-03 found every one of them dying before its handler ran. The Netlify function logs named the cause: the production context carries a Razorpay TEST key, and the #1219 guard in `lib/payments/core/razorpay.ts` throws at module load when it sees one under the production posture. That guard has shipped in every release since 2026-08-26, so checkout, gateway refunds and Razorpay webhooks had been dead on production for a week, hidden behind the signup outage (#1298). Wave 5 widened the blast radius: the cancel preview route started importing `booking-refund`, which imports `refund.ts`, which imported the gateway barrel as a value, so a request that needed no gateway at all still evaluated the core and tripped the guard.
@@ -94,6 +97,48 @@ flowchart TD
- **A documented opt-out for the pre-launch window.** With `RAZORPAY_ALLOW_TEST_KEYS_IN_PRODUCTION=true` the guard logs a loud error and lets the module boot, because the production site legitimately runs on test keys while signup is closed and checkout is exercised with test cards. The variable is declared in the required-secrets reference with the rule that it is deleted, and LIVE keys set, before signup opens. The owner chose this posture on 2026-09-03 over switching to live keys immediately.
- Two pins in the existing guard suite: the opt-out boots with the warning, and the refund modules load under the production posture with a test key while the core still throws.
+### PR A — top-up allocation places only the missing sessions (`feat/allocation-top-up-mode`, #1206)
+
+- **`autoAllocate` gains a `topUp` mode that never deletes anything.** A partial allocation confirms some of a plan's sessions and leaves the rest unplaced, and until now the only way to recover them was to re-run the ordinary auto path, which deletes every confirmed appointment and re-plans the whole event from scratch. That is correct for a reschedule and destructive for an event whose earlier sessions are already booked and paid, so the recovery was left to the consultant. With `topUp: true` the allocator skips `deleteExistingAppointments` entirely, treats every confirmed appointment as fixed, and asks the search only for the plan's total minus the sessions that already exist.
+- **The fixed sessions keep blocking the search and keep counting toward the caps.** A top-up excludes no appointment from the occupancy scan, so the confirmed sessions' intervals stay in the booked set, and their weeks and days seed the per-week and per-day counters exactly as the validator will re-count them. That is the whole difference between a top-up and a re-plan expressed in one list: the ordinary path excludes the event's own appointments because it is about to delete them.
+- **The "already fully scheduled" guard answers instead of throwing.** For a top-up, an event that is already complete, and an event whose consultant still has no room, both return a success carrying `noChange: true` rather than a 409 or a `SLOT_SHORTAGE`. A sweep that runs every hour over every incomplete event cannot treat "nothing to do" as an error. A top-up asked for _without_ `allowPartial` still gets the typed `SLOT_SHORTAGE` back, so the consultant's dialog can keep offering to place what fits.
+- **Nothing is notified on a run that changed nothing.** `allocate()` suppresses the allocation-time notice when `noChange` is set, which is the precondition the deferred sweep was waiting on: without it the consultee would be told about their booking once an hour, forever, until their consultant happened to publish more availability. When at least one session is placed, the existing complete or partial notice fires once, and its counts are reported against the plan rather than against the run, so a consultee reads "three of four scheduled" rather than "one of four".
+- **The hourly `reconcile-slot-availability` job now runs the pass the code had a comment where.** The cohort is recurring events — APPROVED subscriptions and SCHEDULED or IN_PROGRESS classes — whose scheduling window is still open, which carry at least one confirmed session, which carry no tentative slot (a reschedule or a live checkout hold must not be topped up underneath), and whose confirmed session count is short of what the plan requires. Each candidate is attempted only when its consultant's `SlotOfAvailabilityWeekly` or `SlotOfAvailabilityCustom` rows have been touched since the event's own `updatedAt`, because re-searching an unchanged calendar can only reach the same answer. No column was added for that timestamp: a successful top-up re-stamps the request or the class through its transition helper, so `updatedAt` already means "when this event was last attempted".
+- **The pass is bounded so the fleet's heaviest cron does not grow a second unbounded tail.** The candidate read is capped, at most twenty-five events are attempted per run, and the loop stops after a minute of wall clock; whatever is skipped is picked up the following hour, ordered so that the consultants who most recently opened up time are served first. One event's failure never ends the sweep, and top-up failures are counted and logged rather than folded into the job's error list, because a calendar with no room is an ordinary outcome and a red cron trains people to ignore it.
+- **Review round: a top-up that cannot apply is refused, and the sweep rotates.** `topUp` on a single-session event, on an event with tentative rows, or on an event with nothing confirmed is now a 400 `VALIDATION_ERROR` instead of a silent downgrade to the ordinary delete-and-re-plan path; a whole plan reports `partial: false`. The sweep excludes soft-deleted appointments, reads only the ids of confirmed appointments (the count is the session count), scans in `updatedAt` order across up to three pages, and bumps the event's `updatedAt` on every outcome, including no-change and failure, so the same rows no longer head the list every hour.
+- **The four allocate routes accept `topUp` in their shared Zod input** and honour it only for the event's consultant or a privileged caller, on the same footing as `allowPartial` — a consultee may not decide how someone else's calendar is re-planned. The success responses now carry `noChange` so a caller can tell "sessions were added" from "already complete, or still no room".
+
+### PR B — the last tentative-slot hard deletes become soft cancels (`fix/tentative-slots-soft-cancel`)
+
+- **Review round: every slot-status write and its history rows share a transaction, and the sweep's guards ride the write.** The three sweeps and the auto-complete pass now run `transitionSlotCompletion` inside `prisma.$transaction`, so a slot can never be moved without the audit row that says why. `cleanup-tentative-slots` repeats its cohort's parent-status predicates in the CAS WHERE, so a request that went back under review, or an event that went live, between the scan and the write keeps its hold. The forbidden-delete pin tolerates whitespace and bracket access and matches allowlisted files exactly, and the cancel-vs-webhook chaos scenario asserts the tombstone state after a cancel win.
+- **Review round 2: sweep transactions are bounded.** The helper writes one history row per moved slot, so a whole cohort in one transaction (up to 5,000 rows for the tentative cleanup) would outlive Prisma's default timeout and roll back to zero. `lib/booking/slot-release.ts` now moves cohorts in chunks of 200, each in its own 30-second transaction; the stale-RESCHEDULED release and the three auto-complete passes read a bounded, oldest-first cohort first. The PENDING-consultation expiry commits the EXPIRED transition and the release of its holds in one transaction per consultation, so a failed release can never leave an expired request holding the calendar.
+- **The four remaining tentative-hold deletes now free the slot by status.** Doctrine rule 2 says a slot is released by its `completionStatus`, never by a `DELETE`, but four sites still called `slotOfAppointment.deleteMany` on tentative rows: the PENDING-consultation expiry and the stale-RESCHEDULED release in `scripts/appointments/expire-stale-requests.ts`, the stale-hold sweep in `scripts/appointments/cleanup-tentative-slots.ts`, the direct-booking arm of `releaseSlots` in `lib/payments/operations/cancel-pending.ts`, and the failed-payment cleanup in `lib/payments/webhooks/handlers.ts`. All five call sites now route through `transitionSlotCompletion` to `CANCELLED` with a `deletedAt` tombstone, so the hold is released for availability while the row survives for support, disputes and refunds. Every guard that made each site correct — `isTentative: true`, the no-SUCCEEDED-payment predicate, the re-checked parent status — is carried into the compare-and-set WHERE clause verbatim, so a booking that was approved or captured between the cohort read and the write still matches zero rows. The allocator's own re-planning delete in `utils/slotAllocation/SlotAllocationService.ts` remains the one sanctioned exception, because it releases never-paid rows under a `payment: { none: {} }` guard.
+- **The stale-RESCHEDULED sweep moves its status scope out of the WHERE and into the from-set.** `transitionSlotCompletion` spreads the caller's WHERE and then overwrites `completionStatus` with its own allowed-from list, so leaving `completionStatus: "RESCHEDULED"` in the WHERE would have silently widened that sweep to SCHEDULED rows it must never touch. The scope is now expressed as `fromIn: ["RESCHEDULED"]`, which the helper bakes into the same statement.
+- **Every follow-up read that counts remaining slots now filters the tombstones out.** A soft-cancelled row stays in the table, so the failed-payment cleanup's `remainingSlots` count and the tentative sweep's own cohort read would otherwise never reach zero again: the EXPIRED transition that the count gates would stop firing, and the sweep would refill its per-run cap with its own dead rows on every pass. The orphaned-confirmation reconciler's "still blocked" check is filtered for the same reason, so a successful re-drive is no longer reported as a conflict. Occupancy needed no change, because `buildOccupiedAppointmentFilter`, the grid route and `SlotValidationService` already require `deletedAt: null` on both the slot and its appointment.
+- **The lapsed pay-link arm of the expiry sweep stops writing status bare.** `expirePaymentPendingRequests` moved `APPROVED_PENDING_PAYMENT` to `EXPIRED` with a bulk `updateMany` that carried neither the compare-and-set from-set nor the money predicate, which made it the standing counter-example to doctrine rule 1 rather than an instance of it. Because `reconcile-payment-status` flips a recovered capture to SUCCEEDED without touching the request, a booking the buyer had paid for could be expired in the window between the scan and the write, and no `BookingStatusHistory` row was written to show it had happened. Each request now moves through `transitionConsultationRequest` or `transitionSubscriptionRequest` in its own transaction with `fromIn: ["APPROVED_PENDING_PAYMENT"]` and the unpaid predicate repeated in the WHERE, so a raced capture matches zero rows and is counted as skipped instead of expired.
+- **Auto-complete's slot-level pass stops stamping holds it should not reach.** The three statements in `completeIndividualSlots` wrote `completionStatus` with a bare `updateMany`, which made them the last uncovered writers of that column and gave them no audit row. Worse, the WHERE clause filtered on nothing but the status and the end time, so an unpaid tentative hold on a slot whose time had passed was marked UNVERIFIED an hour later, and a slot that a sweep had already released was re-stamped from its tombstone. Marking a hold UNVERIFIED is not cosmetic: it moves the row out of the from-set that the release sweeps reach through, so the hold survives every subsequent pass and keeps blocking the consultant's calendar. All three passes now go through `transitionSlotCompletion` with `fromIn: ["SCHEDULED"]`, which is narrower than the map's default so an hourly fallback can never lift a slot a human parked for review, and both `isTentative: false` and `deletedAt: null` ride the same compare-and-set WHERE. The job's counts and log line are unchanged.
+- **Two smaller corrections ride along.** The maintenance preflight check counted upcoming sessions without excluding tombstones, so it warned the operator about cancelled sessions that were never going to happen. The lapsed pay-link arm gains a `MAX_REQUESTS_PER_RUN` cap of 500 per cohort, oldest first, matching the cap the tentative sweep already carries: now that each request expires in its own transaction rather than one bulk statement, an unbounded backlog would exhaust the function before it finished, and a capped run logs a warning so the next scheduled run is known to be continuing.
+- **The forbidden-delete pin is now a repo-wide rule rather than a list of named files.** `__tests__/payments/appointment-delete-forbidden.test.ts` previously asserted that three specific sweeps were free of `slotOfAppointment.delete`, which is exactly why four other sites kept the shape for months. It now walks `scripts/`, `jobs/`, `lib/`, `app/` and `utils/` — 1,563 source files — against an allowlist of exactly the allocator plus seed and reset scripts under `prisma/` and `scripts/db/`, so a new delete site fails the moment it is written.
+
+### PR C — every status history row carries its appointment id, and creation is a row
+
+- **The audit column was dead.** `BookingStatusHistory.appointmentId` has existed since wave 5 and `appendHistory` has always been willing to write it, but the value only ever arrived when a caller volunteered one, and no caller ever did. Every row in the table therefore carried NULL, and the staff timeline resolved a booking's trail entirely through the polymorphic `{ entity, entityId }` arms of its OR. Each of the seven helpers already reads a pre-image inside its transaction to learn the from-status, so the appointment id now rides that same read and is stamped automatically. A caller that knows better still wins, because the resolution only fills in what the caller left out.
+- **Two entities deliberately keep writing NULL.** A subscription and a class own `Appointment[]` rather than a single appointment, so their pre-image selects two live appointments and stamps the id only when exactly one came back. A multi-appointment aggregate has no single appointment to name, and guessing one would point the trail at an arbitrary member. A trial that has not been placed yet is the other case: its `appointmentId` is genuinely null until acceptance schedules the session. Both fall back to the entity arms, which is why those arms are load-bearing rather than a transitional fallback.
+- **The slot sweep takes the id from the rows it moved.** `transitionSlotCompletion` sweeps a full `WhereInput`, so its callers pass either one appointment id or an `in` list, and reading the id out of the caller's WHERE would have to branch on which. The `updateManyAndReturn` that already tells the helper which slots moved now returns each row's `appointmentId` alongside its id, so the stamp is exact in both shapes and needs no branch.
+- **Creation is now a history row.** A freshly created request had never transitioned, so it had no rows at all and the staff timeline answered "nothing has moved on this booking yet" for every new booking on production. A new `appendCreationHistory` helper writes one opening row in the same transaction as the create, from the literal `"CREATED"` to whatever status the row was born in. The literal matters: `appendHistory` renders a missing from-status as `"UNKNOWN"`, which on this surface means a concurrent writer moved the row between the pre-read and the update, and creation is emphatically not that.
+- **Three creation paths write it.** The direct-checkout consultation and subscription handlers already run inside the checkout transaction and simply append after the appointment exists. The request-for-approval route did not have a transaction at all — its nested create was atomic on its own — so the create and the audit row are now wrapped in one, budgeted well inside the sixty-second slot lock the route already holds. The capture webhook's own creators in `lib/payments/webhooks/handlers.ts` are deliberately out of scope for this PR. They are the legacy fallback that builds a booking when the payment carries no appointment because checkout never made one, so a booking born that way still opens with no creation row and its timeline starts at its first real transition.
+
+### PR D — scoped rate cards reach settlement, behind a flag that defaults off (`feat/rate-card-scoped-settlement`)
+
+- **A rate card scoped to a contract or a plan could be created and never chosen.** `resolveEffectiveRateCard` ranks eight tiers, from the per-expert membership override down to the hardcoded 10/10/80, but its only settlement caller passed just the org, the membership override and the effective instant. Tiers 2 through 6 — contract-scoped and plan-scoped cards — were therefore unreachable, so an org that configured a negotiated split through `POST /organizations/{orgId}/rate-cards` watched every booking settle on the org default instead, with no error anywhere to say so. `resolveOrgSplit` (`lib/payments/payouts/earnings-service.ts`) now forwards the booking's `contractId`, `planType` and `planId` as well.
+- **The forwarding is gated on `RATE_CARD_SCOPED_RESOLUTION`, which is on only when the value is exactly `on`.** Flipping it changes which card pays live money: any scoped card an org created while the tiers were dark would begin settling at a different split the moment it became selectable, so an org has to be able to audit its cards first and flip second. The gate is `isScopedRateCardResolutionEnabled()` in `lib/api/organizations/rate-card.ts`, read from `process.env` per call rather than at module load so the flip is a deployment variable rather than a value baked into whichever bundle imported the module first. With the flag off the resolver call is the pre-#1335 one verbatim, and the scoped tiers are not even queried.
+- **The effective instant is unchanged.** Settlement still resolves at `payment.createdAt`, because a hold can be days long and a retroactive rate bump must not rewrite what a consultant was owed for work already delivered.
+- **The contract is forwarded only when it belongs to the settling org.** The one link a settling payment has to a `Contract` is the org-funded chain `BookingUtilization` → `ProgramAssignment` → `Program` → `Contract`, and `Contract.organizationId` is the **sponsoring** org while `resolveOrgSplit` resolves the expert's **host** org. Because a contract-scoped card is created with the contract checked against its own org, and the resolver then matches `ownerContractId` without re-asserting the org, forwarding a sponsor's contract unguarded would settle one tenant's booking on another tenant's negotiated split. Contract scope is consequently reachable only where the sponsor and the host are the same organization, which is the HYBRID case the tier was designed for. Marketplace and self-funded bookings have no contract at all, and a subscription meters its utilization at slot-allocation time, so it has none yet at settlement; both resolve null and fall through to org scope.
+- **Consultation and subscription bookings resolve at plan-type granularity, not plan granularity.** `planType` is derived from the settlement's own `AppointmentType` through an exhaustive record, so all four kinds reach tiers 4 and 5, but only webinar and class carry a plan id into settlement, so only they reach tiers 2 and 3. A card scoped to a specific consultation or subscription plan is still never selected; closing that means widening the payment projection at the three `createEarningsFromPayment` call sites.
+- **The collaborator leg forwards no scope under either flag state.** ADR 18 makes collaborations org-blind — a collaborator on someone else's org-owned plan is not that org's expert — so the seller's contract and plan must not select a card owned by the collaborator's own org.
+- **`sync-payment-earnings` reads the flag too.** The earnings healer accrues through the same `createEarningsFromPayment` the capture webhook uses, so the workflow now carries `RATE_CARD_SCOPED_RESOLUTION` in its environment. Set on Netlify alone, the same booking would have settled on the scoped card when the webhook caught it and on the org default when the healer did.
+- **Pin:** `__tests__/payments/rate-card-scoped-settlement.test.ts` drives the real resolver end to end and asserts the bps that land on the earnings rows — the plan-scoped card's split with the flag on, the org default's with it off, and no contract query at all when the sponsoring contract belongs to another org.
+
## Changelog: 2026-09-02 — wave 5
The wave-5 train (#1319) reconciles the original booking and maintenance audit briefs against everything that shipped in waves 1–4 and closes the residuals that survived. Each PR appends its own bullets here.
@@ -177,7 +222,7 @@ Part of #1319. This PR makes an abandoned checkout release its slot by definitio
**The pay-link mint is its own guarded atom.** The approval-payment mint used a private `lock:approval_payment:` key through the single-shot `lib/redis` `acquireLock`, where a breaker-open Redis and a held lock were indistinguishable. Review of this PR caught that the approval routes mint while they still hold `consultation-approval:` / `subscription-approval:`, so folding the mint into those keys would have made every approval contend with itself. The mint now takes `approval-payment-mint::` through the guarded path, keyed by the validated `appointmentType`, nested under the approval lock (order: approval → mint). The approval routes also re-grant their lock at the top of every Serializable attempt (`renewApprovalLock`); a lapsed grant is a 409 `APPROVAL_LOCK_LOST`, never a concurrent second mint. The two crud-with-plan delete routes and the org payout writer retry once, not three times, so their per-attempt budgets stay under the function ceiling and the 60-second payout grant.
-**A dead approval intent is re-minted in place, never handed back or duplicated.** The reuse branch of `createApprovalPaymentIntent` treated every PENDING payment as live, so a row the hold rule already calls dead — marked EXPIRED, or still PENDING past its own `expiresAt` — was returned as the checkout URL. That link points at a slot `buildDeadHoldFilter` has just released, so the payer either pays for a slot somebody else now holds or pays into an order the sweep is about to void. Minting a second row is not the way out either, because `Payment` is unique on `[userId, appointmentId]` and the insert dies on P2002. The mint now creates a fresh gateway order and writes it back into the same Payment row, which keeps its id, its owner and its appointment while taking the new intent, PENDING status, a new forty-eight-hour window and the figures the gateway was actually asked for; the CARD leg is re-pointed with it so `sum(legs) = amount` still holds. When the sweep has already moved the request on — a REJECTED consultation or subscription, a trial that is no longer AWAITING_PAYMENT — there is nothing left to re-mint against, so the mint raises `ApprovalWindowLapsedError` and both approval routes answer 409 telling the consultee to submit the request again. A FAILED row is untouched by this rule: a gateway rejection is retried from scratch.
+**A dead approval intent is re-minted in place, never handed back or duplicated.** The reuse branch of `createApprovalPaymentIntent` treated every PENDING payment as live, so a row the hold rule already calls dead — marked EXPIRED, or still PENDING past its own `expiresAt` — was returned as the checkout URL. That link points at a slot `buildDeadHoldFilter` has just released, so the payer either pays for a slot somebody else now holds or pays into an order the sweep is about to void. Minting a second row is not the way out either, because `Payment` is unique on `[userId, appointmentId]` and the insert dies on P2002. The mint now creates a fresh gateway order and writes it back into the same Payment row, which keeps its id, its owner and its appointment while taking the new intent, PENDING status, a new forty-eight-hour window and the figures the gateway was actually asked for; the CARD leg is re-pointed with it so the funding legs still sum to `amount`. When the sweep has already moved the request on — a REJECTED consultation or subscription, a trial that is no longer AWAITING_PAYMENT — there is nothing left to re-mint against, so the mint raises `ApprovalWindowLapsedError` and both approval routes answer 409 telling the consultee to submit the request again. A FAILED row is untouched by this rule: a gateway rejection is retried from scratch.
**Checkout renews its slot grant on every retry attempt.** One renewal before the Serializable loop could not cover four 25-second attempts against a 60-second CONSULTATION grant, so the lock lapsed mid-payment on a retried checkout. The grant is now renewed at the top of every `withSerializableRetry` attempt with a TTL sized to one attempt plus slack (the larger of the type's TTL and 35 seconds). Lost ownership aborts the attempt with the existing "already in progress" error, which the route maps to 409. An exhausted P2034 retry budget in `app/api/checkout/route.ts` is a 409 `SERIALIZATION_CONFLICT` that tells the customer the card was not charged.
diff --git a/docs/booking/06-dependency-graphs.md b/docs/booking/06-dependency-graphs.md
index 7231a3cfd..2fddf3d84 100644
--- a/docs/booking/06-dependency-graphs.md
+++ b/docs/booking/06-dependency-graphs.md
@@ -304,7 +304,7 @@ erDiagram
ClassEvent ||--o{ Appointment : "M appointments"
Appointment ||--|{ SlotOfAppointment : "N slots per session"
- Appointment ||--o{ BookingStatusHistory : "one row per CAS transition"
+ Appointment ||--o{ BookingStatusHistory : "one row per creation and CAS transition"
SlotOfAppointment ||--o| MeetingSession : "video call"
```
diff --git a/docs/booking/README.md b/docs/booking/README.md
index f9577ca1c..d90f013f5 100644
--- a/docs/booking/README.md
+++ b/docs/booking/README.md
@@ -39,7 +39,7 @@ graph TD
## Reading the audit trail
-Every guarded status transition appends one `BookingStatusHistory` row inside the same transaction as the state change, and the reschedule proposals raised against a booking are kept as `RescheduleRequest` rows. Those two tables together are the booking's audit trail, and the way to read them is `getBookingTimeline` in [`lib/data/booking-history.ts`](../../lib/data/booking-history.ts), which merges both sources into a single newest-first list of status edges, actors and reasons. It resolves the trail through the polymorphic `entityId` column rather than through the nullable `appointmentId`, because no writer populates the latter today, and that is what makes the slot and reschedule rows visible. The surface over it is `GET /api/staff/appointments/[appointmentId]/timeline`, which renders in the operator appointment detail modal on the staff and admin appointments pages. Reading it requires ADMIN or STAFF: ADR 20 gives organization roles no per-session drill-in, so the read model's scope parameter accepts only the privileged `all` kind and refuses anything else.
+Every guarded status transition appends one `BookingStatusHistory` row inside the same transaction as the state change, creation appends one more from the literal `"CREATED"` so a booking that has not moved yet still has a timeline, and the reschedule proposals raised against a booking are kept as `RescheduleRequest` rows. Those two tables together are the booking's audit trail, and the way to read them is `getBookingTimeline` in [`lib/data/booking-history.ts`](../../lib/data/booking-history.ts), which merges both sources into a single newest-first list of status edges, actors and reasons. It resolves the trail through both the nullable `appointmentId`, which the transition helpers now fill from each row's own pre-image, and the polymorphic `entityId` column, which is what still makes the rows visible where no single appointment can be named — a subscription or class owning several live appointments, a trial not yet scheduled, and every row written before #1333. The surface over it is `GET /api/staff/appointments/[appointmentId]/timeline`, which renders in the operator appointment detail modal on the staff and admin appointments pages. Reading it requires ADMIN or STAFF: ADR 20 gives organization roles no per-session drill-in, so the read model's scope parameter accepts only the privileged `all` kind and refuses anything else.
## Source Code Map
diff --git a/docs/compliance/01-tds-overview.md b/docs/compliance/01-tds-overview.md
index 3116ccc6f..b7ebd4371 100644
--- a/docs/compliance/01-tds-overview.md
+++ b/docs/compliance/01-tds-overview.md
@@ -1,6 +1,6 @@
# 01 — TDS overview (sections, rates, thresholds)
-> **Status:** 🔴 production bug on B2C side (wrong section + rate). B2B side is closer to correct but still needs wiring. 🔴 **NEW (2026-06-05): the Income-tax Act, 2025 took effect 1-Apr-2026 — the old §194O/194J/194C/195 section *numbers* no longer exist for returns on transactions on/after that date. See "Income-tax Act 2025 renumbering" below; code still emits the old labels.**
+> **Status:** 🔴 production bug on B2C side (wrong section + rate). B2B side is closer to correct but still needs wiring. 🔴 **NEW (2026-06-05): the Income-tax Act, 2025 took effect 1-Apr-2026 — the old §194O/194J/194C/195 section _numbers_ no longer exist for returns on transactions on/after that date. See "Income-tax Act 2025 renumbering" below; code still emits the old labels.**
> **Audience:** anyone working on payouts (`lib/payments/payouts/`), tax helpers (`lib/payments/tax/`, `lib/compliance/`).
> **Last reviewed:** 2026-06-05 (regulatory facts web-verified as of 2026-06-05; prior review 2026-05-02)
> **Linked issues:** [#737](https://github.com/Practitionist/games/familiarise_web/issues/737), [#738](https://github.com/Practitionist/familiarise_web/issues/738) (Item F).
@@ -11,43 +11,44 @@ Tax Deducted at Source — the income-tax withholding that a payer (us) takes of
Section numbers below are given as **§1961-Act, now §2025-Act / payment-code** (see the renumbering note immediately after the table). Rates and thresholds are **unchanged** by the 2025 Act — only the citation/form taxonomy changed.
-| Section (1961 → 2025 Act) | Applies to | Rate (FY 2026-27) | Threshold | No-PAN fallback |
-|---|---|---|---|---|
-| **194O → §393(1) Table Sl.8(v), code 1035** | E-commerce operator pays e-commerce participant | **0.10%** (cut from 1% w.e.f. 1 Oct 2024 by Finance (No. 2) Act 2024) | ₹5,00,000 / FY for resident *individuals/HUF* with valid PAN/Aadhaar; **no threshold** for partnerships / companies / LLPs / non-residents | **5%** (special carve-out for 194O — not the usual 20% under old 206AA, now §397(2)) |
-| **194J → §393(1) Table Sl.6(iii)** | Professional / technical services billed directly | **10% professional** (codes 1027/1028) / **2% technical** (code 1026) — *the rates have been distinct since FY 2020-21; the 2025 Act gives them separate payment codes* | **₹50,000 / FY** (raised from ₹30,000 w.e.f. FY 2026-27; computed *per payment-type* — professional, technical, royalty each have their own ₹50K) | 20% |
-| **194C → §393(1) Table Sl.6(i)** | Contract works / vendor services | 1% (individual/HUF, code 1023) or 2% (others, code 1024) | ₹30,000 single / ₹1,00,000 aggregate | 20% |
-| **195 → §393(2) Table Sl.17, code 1057** | Any payment to a non-resident | 20% (or DTAA rate if Form 10F + TRC + lower-rate cert produced) | None | DTAA cap or 20% |
+| Section (1961 → 2025 Act) | Applies to | Rate (FY 2026-27) | Threshold | No-PAN fallback |
+| ------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| **194O → §393(1) Table Sl.8(v), code 1035** | E-commerce operator pays e-commerce participant | **0.10%** (cut from 1% w.e.f. 1 Oct 2024 by Finance (No. 2) Act 2024) | ₹5,00,000 / FY for resident _individuals/HUF_ with valid PAN/Aadhaar; **no threshold** for partnerships / companies / LLPs / non-residents | **5%** (special carve-out for 194O — not the usual 20% under old 206AA, now §397(2)) |
+| **194J → §393(1) Table Sl.6(iii)** | Professional / technical services billed directly | **10% professional** (codes 1027/1028) / **2% technical** (code 1026) — _the rates have been distinct since FY 2020-21; the 2025 Act gives them separate payment codes_ | **₹50,000 / FY** (raised from ₹30,000 w.e.f. FY 2026-27; computed _per payment-type_ — professional, technical, royalty each have their own ₹50K) | 20% |
+| **194C → §393(1) Table Sl.6(i)** | Contract works / vendor services | 1% (individual/HUF, code 1023) or 2% (others, code 1024) | ₹30,000 single / ₹1,00,000 aggregate | 20% |
+| **195 → §393(2) Table Sl.17, code 1057** | Any payment to a non-resident | 20% (or DTAA rate if Form 10F + TRC + lower-rate cert produced) | None | DTAA cap or 20% |
**Removed and gone (do not implement):**
+
- Section 206C(1H) — TCS on sale of goods > ₹50L. Omitted by Finance Act 2025 w.e.f. 1 Apr 2025. ✅ verified 2026-06-05.
- Section 206AB / 206CCA — higher TDS / TCS for non-filers. Omitted w.e.f. 1 Apr 2025. ✅ verified 2026-06-05.
### Income-tax Act 2025 renumbering — verified as of 2026-06-05
-The **Income-tax Act, 2025 (Act 30 of 2025)** received Presidential assent 21 Aug 2025 and **came into force 1 Apr 2026** — operationalised by the Income-tax Rules, 2026 (G.S.R. 198(E), 20 Mar 2026); the 1961 Act stood repealed 31 Mar 2026. **Every TDS provision outside salary is consolidated into a single Section 393** (salary TDS → §392; TCS → §394; higher-rate-for-no-PAN, old 206AA/206CC → **§397(2)**, retaining the 20% rate). The old alphanumeric section numbers (194O, 194J, 194C, 195, 206AA…) **cease to exist as filing citations** for any transaction on/after 1 Apr 2026 and are replaced by **numeric payment codes (the 10xx series — publishers cite 1001–1067)** keyed to table serials inside §393. (Exact code endpoints differ across early concordances; treat any single code below as the *publisher-asserted* mapping pending the final CBDT challan/RPU schema — see follow-up note.)
+The **Income-tax Act, 2025 (Act 30 of 2025)** received Presidential assent 21 Aug 2025 and **came into force 1 Apr 2026** — operationalised by the Income-tax Rules, 2026 (G.S.R. 198(E), 20 Mar 2026); the 1961 Act stood repealed 31 Mar 2026. **Every TDS provision outside salary is consolidated into a single Section 393** (salary TDS → §392; TCS → §394; higher-rate-for-no-PAN, old 206AA/206CC → **§397(2)**, retaining the 20% rate). The old alphanumeric section numbers (194O, 194J, 194C, 195, 206AA…) **cease to exist as filing citations** for any transaction on/after 1 Apr 2026 and are replaced by **numeric payment codes (the 10xx series — publishers cite 1001–1067)** keyed to table serials inside §393. (Exact code endpoints differ across early concordances; treat any single code below as the _publisher-asserted_ mapping pending the final CBDT challan/RPU schema — see follow-up note.)
Verified old→new mapping (sources: Finpracto / Tax2win / Jurishour concordances, Mar–May 2026):
-| 1961 Act | 2025 Act | Payment code | Rate |
-|---|---|---|---|
-| 194O | §393(1) Table Sl.8(v) | **1035** | 0.10% |
-| 194J (technical) | §393(1) Table Sl.6(iii) | **1026** | 2% |
-| 194J (professional / director) | §393(1) Table Sl.6(iii) | **1027 / 1028** | 10% |
-| 194C (individual/HUF) | §393(1) Table Sl.6(i) | **1023** | 1% |
-| 194C (others) | §393(1) Table Sl.6(i) | **1024** | 2% |
-| 195 | §393(2) Table Sl.17 | **1057** | rates-in-force / DTAA |
-| 206AA / 206CC (no-PAN) | **§397(2)** | — | 20% (retained) |
+| 1961 Act | 2025 Act | Payment code | Rate |
+| ------------------------------ | ----------------------- | --------------- | --------------------- |
+| 194O | §393(1) Table Sl.8(v) | **1035** | 0.10% |
+| 194J (technical) | §393(1) Table Sl.6(iii) | **1026** | 2% |
+| 194J (professional / director) | §393(1) Table Sl.6(iii) | **1027 / 1028** | 10% |
+| 194C (individual/HUF) | §393(1) Table Sl.6(i) | **1023** | 1% |
+| 194C (others) | §393(1) Table Sl.6(i) | **1024** | 2% |
+| 195 | §393(2) Table Sl.17 | **1057** | rates-in-force / DTAA |
+| 206AA / 206CC (no-PAN) | **§397(2)** | — | 20% (retained) |
**Filing impact (verified):** for Q4 FY 2025-26 (up to 31 Mar 2026) returns still use the old section numbers + old form names. For Tax Year 2026-27 onward, a return filed with an old section number (e.g. "194O") **triggers a system-level validation error at upload**. Form names also change — see [doc 04](./04-tds-quarterly-filings.md) (26Q → Form 140, 27Q → Form 144, 16A → Form 131).
-🟡 **Code-vs-law divergence (verified 2026-06-05):** the code still stores and emits the **old labels** — `lib/compliance/tds.ts` `TDS_SECTION_DEFAULTS` keys (`"194O"`, `"194J"`, `"194C"`), `TDSRecord.tdsSection`, and `OrganizationPayout.tdsSectionApplied` all carry `"194O"`/`"194J"`/`"194C"`. These are correct for *internal classification* but **must be translated to §393 payment codes before any return upload for FY 2026-27** or the FVU/portal upload will reject. This is a filing-export concern, not a withholding-math concern (the *rates* are unchanged). Tracked as an engineering follow-up; the FVU generator (doc 04) is the right place to map label → code.
+🟡 **Code-vs-law divergence (verified 2026-06-05):** the code still stores and emits the **old labels** — `lib/compliance/tds.ts` `TDS_SECTION_DEFAULTS` keys (`"194O"`, `"194J"`, `"194C"`), `TDSRecord.tdsSection`, and `OrganizationPayout.tdsSectionApplied` all carry `"194O"`/`"194J"`/`"194C"`. These are correct for _internal classification_ but **must be translated to §393 payment codes before any return upload for FY 2026-27** or the FVU/portal upload will reject. This is a filing-export concern, not a withholding-math concern (the _rates_ are unchanged). Tracked as an engineering follow-up; the FVU generator (doc 04) is the right place to map label → code.
## When it applies
### B2C (consumer marketplace)
- A consumer pays the platform via card. Platform is the **e-commerce operator** under Sec 194O Explanation(a). Consultant is the **e-commerce participant** under Explanation(b).
-- The right section is **194O at 0.10%**. Threshold of ₹5L applies only to *resident individuals/HUF* with valid PAN/Aadhaar. For everyone else, withhold from rupee 1.
+- The right section is **194O at 0.10%**. Threshold of ₹5L applies only to _resident individuals/HUF_ with valid PAN/Aadhaar. For everyone else, withhold from rupee 1.
- For non-resident consultants, **194O does not apply** — pivot to **Sec 195 + DTAA**.
### B2B (org-sponsored)
@@ -65,31 +66,38 @@ Verified old→new mapping (sources: Finpracto / Tax2win / Jurishour concordance
Two TDS files, two contracts, partial overlap (re-verified against code 2026-06-05):
-| File | Section | Rate | Threshold | No-PAN | Notes |
-|---|---|---|---|---|---|
-| `lib/payments/tax/tds-service.ts` (consultant path, **`@deprecated`**) | 194J | 10% | ₹50,000 | 20% | Header still says "Section 194J flat 10%". Slated for deprecation in favour of the canonical lib once CA signs off on 194-O precedence for consultant payouts (#778 §E). Still live as the conservative default. |
-| `lib/compliance/tds.ts` (canonical / org path) | 194O default ✅ | **0.10% ✅** (`"194O": 0.001`) | none for orgs ✅ | **5% ✅** (`NO_PAN_RATE_194O = 0.05`) | **Fixed since the original audit** (#771 P0-1 / #737 / #738) — rate is now 0.001, and 194-O carries its own 5% no-PAN rate distinct from the 206AA/§397(2) 20%. 206AA fallback, §197 cert, and DTAA lookup all implemented. |
+| File | Section | Rate | Threshold | No-PAN | Notes |
+| ---------------------------------------------------------------------- | --------------- | ------------------------------ | ---------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `lib/payments/tax/tds-service.ts` (consultant path, **`@deprecated`**) | 194J | 10% | ₹50,000 | 20% | Header still says "Section 194J flat 10%". Slated for deprecation in favour of the canonical lib once CA signs off on 194-O precedence for consultant payouts (#778 §E). Still live as the conservative default. |
+| `lib/compliance/tds.ts` (canonical / org path) | 194O default ✅ | **0.10% ✅** (`"194O": 0.001`) | none for orgs ✅ | **5% ✅** (`NO_PAN_RATE_194O = 0.05`) | **Fixed since the original audit** (#771 P0-1 / #737 / #738) — rate is now 0.001, and 194-O carries its own 5% no-PAN rate distinct from the 206AA/§397(2) 20%. 206AA fallback, §197 cert, and DTAA lookup all implemented. |
🟡 **Two residual code-vs-law nuances (verified 2026-06-05), both in `lib/compliance/tds.ts`:**
+
- `TDS_SECTION_DEFAULTS["194J"] = 0.1` is a **flat 10%**. Current law (and the 1961 Act since FY 2020-21) distinguishes **technical services at 2%** (code 1026) from **professional/director fees at 10%** (codes 1027/1028). The flat-10% path over-withholds on technical-service consultants. Low blast radius today because 194-O is the platform default, but the residual 194J override path is wrong for technical services.
- Section **labels** (`"194O"`, `"194J"`, `"194C"`) are emitted as-is into `TDSRecord.tdsSection` / `OrganizationPayout.tdsSectionApplied`; these need label→§393-payment-code translation before any FY 2026-27 return upload (see renumbering note above).
-The deprecated `tds-service.ts` consultant path historically *skipped* deduction for non-residents (should pivot to §195/§393(2) + DTAA, not skip). The canonical `lib/compliance/tds.ts` handles NON_RESIDENT via the DTAA-lookup branch; the gap is only on the deprecated path, which is why consolidation onto the canonical lib (#778 §E) is the fix.
+The deprecated `tds-service.ts` consultant path historically _skipped_ deduction for non-residents (should pivot to §195/§393(2) + DTAA, not skip). The canonical `lib/compliance/tds.ts` handles NON_RESIDENT via the DTAA-lookup branch; the gap is only on the deprecated path, which is why consolidation onto the canonical lib (#778 §E) is the fix.
+
+### Both rails now write `TDSRecord` (#1354)
+
+`TDSRecord` was a consultant-only table, which meant that host-organisation withholding was computed, deducted from the disbursement and posted to `TDS_PAYABLE` without ever producing a filing row. Organisation payouts now write the same audit row that consultant payouts do, at the moment the payout reaches `COMPLETED` and never earlier, so the quarterly draft covers every deduction the platform actually made.
+
+The table carries both rails at once. `consultantProfileId` and `organizationId` are each nullable and exactly one is set on any row, which `tds_record_deductee_xor` enforces in the database; a second constraint, `tds_record_payout_rail_matches`, prevents a row from citing the payout of the rail it does not belong to. The org rail has its own unique key over `(organizationId, financialYear, quarter, orgPayoutId, isReversal)` rather than sharing the consultant one, because Postgres treats NULLs as distinct and a shared key would silently dedupe nothing. `TdsAdjustment` is widened the same way, so a reversal on either rail produces the revised-statement line the return generator exports.
## Gap
Re-verified against code 2026-06-05. Several rows from the original audit are now **fixed** (struck) because the canonical lib was corrected under #771/#737/#738; the live gaps are the consultant-path consolidation, the 194J split, and the §393 code mapping.
-| Gap | Where | Severity |
-|---|---|---|
-| ~~Wrong rate (1% → 0.10%)~~ **FIXED** — `"194O": 0.001` | `lib/compliance/tds.ts` | ✅ |
-| ~~Wrong no-PAN fallback (20% → 5% for 194O)~~ **FIXED** — `NO_PAN_RATE_194O = 0.05` | `lib/compliance/tds.ts` | ✅ |
-| Consultant path still 194J/₹50K (deprecated, not yet consolidated onto canonical lib) | `lib/payments/tax/tds-service.ts` | 🔴 (blocked on CA signoff, #778 §E) |
-| 194J modelled as flat 10% — no technical-2% (code 1026) vs professional-10% (1027/1028) split | `lib/compliance/tds.ts` `TDS_SECTION_DEFAULTS` | 🟡 |
-| Section labels not mapped to §393 payment codes for FY 2026-27 return upload | `lib/compliance/tds.ts`, `TDSRecord.tdsSection`, FVU export (doc 04) | 🔴 (filing-blocking from 1-Apr-2026) |
-| No threshold differentiation by entity type on the deprecated path (companies/LLPs get no threshold under 194-O) | `tds-service.ts` | 🟠 (canonical lib treats org payouts as no-threshold; `TaxEntityType` enum now exists in schema) |
-| Non-resident path *skips* deduction on the **deprecated** path (should pivot to §195/§393(2)+DTAA) | `tds-service.ts` | 🔴 |
-| ~~`ConsultantProfile.taxEntityType` field doesn't exist~~ **ADDED** — `enum TaxEntityType` now in schema (#778 §D) | `prisma/schema.prisma` | ✅ |
+| Gap | Where | Severity |
+| ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| ~~Wrong rate (1% → 0.10%)~~ **FIXED** — `"194O": 0.001` | `lib/compliance/tds.ts` | ✅ |
+| ~~Wrong no-PAN fallback (20% → 5% for 194O)~~ **FIXED** — `NO_PAN_RATE_194O = 0.05` | `lib/compliance/tds.ts` | ✅ |
+| Consultant path still 194J/₹50K (deprecated, not yet consolidated onto canonical lib) | `lib/payments/tax/tds-service.ts` | 🔴 (blocked on CA signoff, #778 §E) |
+| 194J modelled as flat 10% — no technical-2% (code 1026) vs professional-10% (1027/1028) split | `lib/compliance/tds.ts` `TDS_SECTION_DEFAULTS` | 🟡 |
+| Section labels not mapped to §393 payment codes for FY 2026-27 return upload | `lib/compliance/tds.ts`, `TDSRecord.tdsSection`, FVU export (doc 04) | 🔴 (filing-blocking from 1-Apr-2026) |
+| No threshold differentiation by entity type on the deprecated path (companies/LLPs get no threshold under 194-O) | `tds-service.ts` | 🟠 (canonical lib treats org payouts as no-threshold; `TaxEntityType` enum now exists in schema) |
+| Non-resident path _skips_ deduction on the **deprecated** path (should pivot to §195/§393(2)+DTAA) | `tds-service.ts` | 🔴 |
+| ~~`ConsultantProfile.taxEntityType` field doesn't exist~~ **ADDED** — `enum TaxEntityType` now in schema (#778 §D) | `prisma/schema.prisma` | ✅ |
## Required
@@ -113,13 +121,13 @@ In commit order:
## References
-- [Income-tax Act 2025 in force 1-Apr-2026 — press release (incometaxindia.gov.in)](https://www.incometaxindia.gov.in/documents/d/guest/press-release-income-tax-act-2025-comes-into-force-from-01-april-2026-pdf) — *verified 2026-06-05*
+- [Income-tax Act 2025 in force 1-Apr-2026 — press release (incometaxindia.gov.in)](https://www.incometaxindia.gov.in/documents/d/guest/press-release-income-tax-act-2025-comes-into-force-from-01-april-2026-pdf) — _verified 2026-06-05_
- [Income-tax Act 2025 effective 1-Apr-2026 (PIB PRID 2221416)](https://www.pib.gov.in/PressReleasePage.aspx?PRID=2221416®=3&lang=1)
-- [TDS/TCS section mapping 1961 → 2025 Act (Finpracto)](https://www.finpracto.com/tds-tcs-section-mapping-from-the-1961-act-to-the-2025-act-your-complete-reference-guide/) — *194O→§393(1) Sl.8(v) code 1035; 194J→Sl.6(iii) 1026/1027/1028; 195→§393(2) Sl.17 code 1057*
+- [TDS/TCS section mapping 1961 → 2025 Act (Finpracto)](https://www.finpracto.com/tds-tcs-section-mapping-from-the-1961-act-to-the-2025-act-your-complete-reference-guide/) — _194O→§393(1) Sl.8(v) code 1035; 194J→Sl.6(iii) 1026/1027/1028; 195→§393(2) Sl.17 code 1057_
- [Old vs new TDS section mapping FY 2026-27 (Jurishour)](https://www.jurishour.in/columns/old-new-tds-sections-mapping-income-tax-act-2025/)
- [206AA/206CC merged into §397(2) (TDSMan, May 2026)](https://blog.tdsman.com/2026/05/higher-rate-of-tds-for-non-furnishing-of-pan-section-3972-206aa-206cc/)
-- [Section 194O 0.10% rate + ₹5L threshold (TDSMan)](https://blog.tdsman.com/2025/09/section-194o-tds-on-payments-by-e-commerce-operators-to-participants/) — *0.10% confirmed unchanged for FY 2026-27*
-- [TDS Rate Chart FY 2026-27 (TaxGarden)](https://taxgarden.in/blog/tds-rate-chart-2026-to-2027) — *194O 0.1%; 194J 10% prof / 2% technical; §393 payment codes*
-- [§194J threshold raised ₹30K → ₹50K w.e.f. FY 2026-27 (Tax2win)](https://tax2win.in/guide/section-194j-under-income-tax-act) — *verified 2026-06-05; ₹50K is per payment-type*
-- [Income-tax Rules 2026 G.S.R. 198(E) — new forms 26Q→140 / 27Q→144 / 16A→131 (TDSMan, Mar 2026)](https://blog.tdsman.com/2026/03/new-tds-tcs-forms-it-act-2025-mapping-with-old-forms/) — *verified 2026-06-05*
+- [Section 194O 0.10% rate + ₹5L threshold (TDSMan)](https://blog.tdsman.com/2025/09/section-194o-tds-on-payments-by-e-commerce-operators-to-participants/) — _0.10% confirmed unchanged for FY 2026-27_
+- [TDS Rate Chart FY 2026-27 (TaxGarden)](https://taxgarden.in/blog/tds-rate-chart-2026-to-2027) — _194O 0.1%; 194J 10% prof / 2% technical; §393 payment codes_
+- [§194J threshold raised ₹30K → ₹50K w.e.f. FY 2026-27 (Tax2win)](https://tax2win.in/guide/section-194j-under-income-tax-act) — _verified 2026-06-05; ₹50K is per payment-type_
+- [Income-tax Rules 2026 G.S.R. 198(E) — new forms 26Q→140 / 27Q→144 / 16A→131 (TDSMan, Mar 2026)](https://blog.tdsman.com/2026/03/new-tds-tcs-forms-it-act-2025-mapping-with-old-forms/) — _verified 2026-06-05_
- See also: [02-gst-overview.md](./02-gst-overview.md) (GST TCS Sec 52 is the GST analogue), [04-tds-quarterly-filings.md](./04-tds-quarterly-filings.md) (Form 26Q→140 / 27Q→144), [07-cross-border-flows.md](./07-cross-border-flows.md) (Sec 195 → §393(2)).
diff --git a/docs/compliance/02-gst-overview.md b/docs/compliance/02-gst-overview.md
index 6b717f1cc..f120375d6 100644
--- a/docs/compliance/02-gst-overview.md
+++ b/docs/compliance/02-gst-overview.md
@@ -5,19 +5,23 @@
> **Last reviewed:** 2026-06-05 (regulatory facts web-verified as of 2026-06-05; prior review 2026-05-02)
> **Linked issues:** [#737 §2,§5,§11](https://github.com/Practitionist/familiarise_web/issues/737), [#738 §A,§F](https://github.com/Practitionist/familiarise_web/issues/738).
+## Model decision (2026-09-03)
+
+The platform bills as **Principal supplier for GST**, decided in [ADR 26](../enterprise/70-design-decisions/26-gst-principal-model.md) and superseding the facilitator framing this document was originally written around. GST stays at 18% on the full discounted price exactly as today, and the platform will issue its own numbered **B2C tax invoice** for every consumer supply (`ConsumerInvoice`) rather than relying on a consultant-issued invoice; this is the design intent recorded in ADR 26, not yet shipped — the model lands with PR-E (`feat/finance-b2c-tax-invoice`, in flight). Place of supply for a consumer defaults to the **supplier's home state under Section 12(2)(b) of the IGST Act** whenever no buyer address is on record, which makes the fallback supply intra-state (CGST + SGST) — the opposite of the B2B derivation's IGST fallback, which stays as an audit signal for org invoices only. **GST-TCS under Section 52 does not apply under this model and is not collected**; the dormant schema (`Payment.gstTcsCollectedPaise`, `GstTcsBatch`, the GSTR-8 draft builder) stays in the tree, correctly annotated at 0.5%, and is only wired if a chartered accountant overturns this decision. See ADR 26 for the full CA question list, including whether a platform-funded referral credit should reduce the taxable value under Section 15(3)(a).
+
## What it is
GST has four interlocking obligations for an e-commerce operator (us):
1. **GST registration (Sec 24(x))** — mandatory for the platform regardless of turnover.
-2. **Tax invoice (Rule 46)** — must be issued for every taxable supply; specific format + HSN/SAC + place-of-supply rules. *(Rate context, verified 2026-06-05: the GST 2.0 rationalization — 56th GST Council, 3-Sep-2025, effective 22-Sep-2025 — collapsed the four-slab structure into two main slabs **5% + 18%** (plus 40% sin/luxury); the 12% and 28% slabs were removed. **Professional / consulting / commercial-training services stay at 18%** — so the CGST 9% + SGST 9% / IGST 18% derivation below is unchanged.)*
-3. **TCS Section 52** — the platform must collect **0.5% (0.25% CGST + 0.25% SGST, or 0.5% IGST)** on the **net taxable value** of supplies of registered consultants and file **GSTR-8** monthly. *(Halved from 1% by Notification 15/2024-Central Tax + the parallel IGST/UTGST notifications, w.e.f. 10 Jul 2024 — verified 2026-06-05.)*
-4. **E-invoicing (Notif 10/2023)** — mandatory for any registered person with aggregate annual turnover (AATO) ≥ ₹5 cr (threshold unchanged as of 2026-06-05); voluntary B2C pilot launched Sep 2024. *(Separate 30-day IRP-reporting cut-off applies at AATO ≥ ₹10 cr since 1-Apr-2025.)*
+2. **Tax invoice (Rule 46)** — must be issued for every taxable supply; specific format + HSN/SAC + place-of-supply rules. _(Rate context, verified 2026-06-05: the GST 2.0 rationalization — 56th GST Council, 3-Sep-2025, effective 22-Sep-2025 — collapsed the four-slab structure into two main slabs **5% + 18%** (plus 40% sin/luxury); the 12% and 28% slabs were removed. **Professional / consulting / commercial-training services stay at 18%** — so the CGST 9% + SGST 9% / IGST 18% derivation below is unchanged.)_
+3. **TCS Section 52 (facilitator-model reference only, not a current obligation)** — under the e-commerce-operator/facilitator framing, the platform would collect **0.5% (0.25% CGST + 0.25% SGST, or 0.5% IGST)** on the **net taxable value** of supplies of registered consultants and file **GSTR-8** monthly. Under the principal-supplier model this document now uses (ADR 26, #1360), the platform is the supplier of record, so Section 52 TCS does not apply and is not collected; this obligation is CA-gated and only becomes live if a chartered accountant overturns the principal-supplier decision. _(Rate context if reversed: halved from 1% by Notification 15/2024-Central Tax + the parallel IGST/UTGST notifications, w.e.f. 10 Jul 2024 — verified 2026-06-05.)_
+4. **E-invoicing (Notif 10/2023)** — mandatory for any registered person with aggregate annual turnover (AATO) ≥ ₹5 cr (threshold unchanged as of 2026-06-05); voluntary B2C pilot launched Sep 2024. _(Separate 30-day IRP-reporting cut-off applies at AATO ≥ ₹10 cr since 1-Apr-2025.)_
Plus the orthogonal obligations:
- **Place of supply** (IGST Sec 12 / 13) — determines IGST vs CGST+SGST.
-- **HSN/SAC codes** — mandatory on invoice; B2C reporting in GSTR-1 Table 12 is optional below ₹5 cr AATO. ⚠️ **SAC correction (verified 2026-06-05): `999293` is *commercial training & coaching* (an education code under group 9992), NOT consulting. Management consulting is `998311`. All of 998311 / 999293 / 999294 / 999299 carry 18% GST, so the *rate* is unaffected — but the doc's old "999293 (consulting)" labelling and the code's 999293 catch-all are a classification (ITC-trail) inaccuracy, not a tax-amount error.**
+- **HSN/SAC codes** — mandatory on invoice; B2C reporting in GSTR-1 Table 12 is optional below ₹5 cr AATO. ⚠️ **SAC correction (verified 2026-06-05): `999293` is _commercial training & coaching_ (an education code under group 9992), NOT consulting. Management consulting is `998311`. All of 998311 / 999293 / 999294 / 999299 carry 18% GST, so the _rate_ is unaffected — but the doc's old "999293 (consulting)" labelling and the code's 999293 catch-all are a classification (ITC-trail) inaccuracy, not a tax-amount error.**
- **LUT (Letter of Undertaking)** — for zero-rated exports without IGST payment.
- **Reverse charge (RCM)** — for imports of services and notified categories.
- **GST credit note (Sec 34)** — required on refund / cancellation / discount post-invoice. See [doc 05](./05-refund-and-chargeback-tax-adjustments.md).
@@ -44,22 +48,22 @@ Plus the orthogonal obligations:
## Current code
-| File | What it does | State |
-|---|---|---|
-| `lib/compliance/gst.ts:68–128` | `deriveGstBreakdown` — zero-rated export, intra-state CGST 9%+SGST 9%, inter-state IGST 18%, HSN defaulting | ✅ live |
-| `lib/compliance/irp.ts` | `generateIrn` — env-gated ClearTax connector | ✅ live |
-| `jobs/compliance/irp-uploader.ts` | Daily cron — eligible invoices → `generateIrn` → persist IRN | ✅ wired (Round 2, daily 02:30 UTC) |
-| `lib/pdf/invoice-renderer.tsx` | `ConsumerInvoiceDocument` + `OrganizationInvoiceDocument` PDF | ✅ live |
-| `OrganizationInvoice` (schema) | igstPaise / cgstPaise / sgstPaise / placeOfSupply / lutNumber / irn / ackNumber / signedQrPayload / irpStatus / retry telemetry | ✅ schema-final |
-| `Invoice` (schema, B2C) | Has HSN / GST split fields | ✅ schema-final |
-| `Payment.consumerStateCode` | **Missing** | 🔴 |
-| `Payment.gstTcsCollectedPaise` + `ConsultantEarnings.gstTcsAccruedPaise` | **Missing** | 🔴 |
-| GSTR-8 monthly export | **Missing** | 🔴 |
-| GSTIN registry verification (live API) | Format-only (`isValidGstin`) | 🔴 |
-| Reverse charge routing | Schema field exists; no routing | 🔴 |
-| LUT enforcement | Schema field exists; no enforcement | 🔴 |
-| Credit note on refund | **Missing** entirely | 🔴 |
-| HSN selection per appointment type | Static default (999293 catch-all) in PDF — should be 998311 consulting / 999293 training | 🟡 |
+| File | What it does | State |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `lib/compliance/gst.ts:68–128` | `deriveGstBreakdown` — zero-rated export, intra-state CGST 9%+SGST 9%, inter-state IGST 18%, HSN defaulting | ✅ live |
+| `lib/compliance/irp.ts` | `generateIrn` — env-gated ClearTax connector | ✅ live |
+| `jobs/compliance/irp-uploader.ts` | Daily cron — eligible invoices → `generateIrn` → persist IRN | ✅ wired (Round 2, daily 02:30 UTC) |
+| `lib/pdf/invoice-renderer.tsx` | `ConsumerInvoiceDocument` + `OrganizationInvoiceDocument` PDF | ✅ live |
+| `OrganizationInvoice` (schema) | igstPaise / cgstPaise / sgstPaise / placeOfSupply / lutNumber / irn / ackNumber / signedQrPayload / irpStatus / retry telemetry | ✅ schema-final |
+| `Invoice` (schema, B2C) | Has HSN / GST split fields | ✅ schema-final |
+| `Payment.consumerStateCode` | **Missing** | 🔴 |
+| `Payment.gstTcsCollectedPaise` + `ConsultantEarnings.gstTcsAccruedPaise` | **Missing** | 🔴 |
+| GSTR-8 monthly export | **Missing** | 🔴 |
+| GSTIN registry verification (live API) | Format-only (`isValidGstin`) | 🔴 |
+| Reverse charge routing | Schema field exists; no routing | 🔴 |
+| LUT enforcement | Schema field exists; no enforcement | 🔴 |
+| Credit note on refund | **Missing** entirely | 🔴 |
+| HSN selection per appointment type | Static default (999293 catch-all) in PDF — should be 998311 consulting / 999293 training | 🟡 |
## Gap
@@ -67,7 +71,7 @@ Plus the orthogonal obligations:
2. **Place-of-supply state capture missing on B2C checkout** (CBIC Notification 02/2023-IT mandates it).
3. **GST credit notes on refunds missing** (handled in [doc 05](./05-refund-and-chargeback-tax-adjustments.md)).
4. **GSTIN live registry verification missing** — only format check today.
-5. **HSN selection static** — should pick **998311** (management consulting, group 9983) for CONSULTATION; **999293** (commercial training & coaching, group 9992) for WEBINAR / CLASS / SUBSCRIPTION on educational content. *(See header SAC correction — 999293 is training, NOT consulting; both 18%, so this is a classification/ITC-trail fix, not a rate fix.)*
+5. **HSN selection static** — should pick **998311** (management consulting, group 9983) for CONSULTATION; **999293** (commercial training & coaching, group 9992) for WEBINAR / CLASS / SUBSCRIPTION on educational content. _(See header SAC correction — 999293 is training, NOT consulting; both 18%, so this is a classification/ITC-trail fix, not a rate fix.)_
6. **LUT enforcement** — invoice generator doesn't gate on `lutNumber` for non-resident purchases.
7. **RCM routing** — schema field present; no logic.
@@ -75,13 +79,13 @@ Plus the orthogonal obligations:
This is the largest discrete gap. What it requires:
-| Item | Detail |
-|---|---|
-| **Rate** | **0.5% total — 0.25% CGST + 0.25% SGST (intra-state) or 0.5% IGST (inter-state)**. Halved from 1% by Notif 15/2024-CT (+ parallel IGST 02/2024-IT / UTGST) w.e.f. 10-Jul-2024 (verified 2026-06-05). **No TCS rate constant is wired anywhere in `lib/` or `jobs/` (verified 2026-06-05 — `GstTcsBatch` stores `netSupplyPaise` / `tcsCollectedPaise` only, with no rate literal or stale "1%" comment); collection is stubbed pending CA signoff, so there is no incorrect *computation* in production.** When collection is wired, hardcode 0.5%, not 1%. |
-| **Base** | Net taxable value of supplies through ECO = gross supplies − returns/refunds (Sec 52(3) + Rule 67(1)) |
-| **Frequency** | Monthly. **GSTR-8 due 10th of following month.** |
-| **Liability** | Platform deposits to govt; consultant claims credit in GSTR-2B. |
-| **Penalty** | Equal to TCS not collected (Sec 122(1)(viii)) + 18% p.a. interest (Sec 50(3)) |
+| Item | Detail |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Rate** | **0.5% total — 0.25% CGST + 0.25% SGST (intra-state) or 0.5% IGST (inter-state)**. Halved from 1% by Notif 15/2024-CT (+ parallel IGST 02/2024-IT / UTGST) w.e.f. 10-Jul-2024 (verified 2026-06-05). **No TCS rate constant is wired anywhere in `lib/` or `jobs/` (verified 2026-06-05 — `GstTcsBatch` stores `netSupplyPaise` / `tcsCollectedPaise` only, with no rate literal or stale "1%" comment); collection is stubbed pending CA signoff, so there is no incorrect _computation_ in production.** When collection is wired, hardcode 0.5%, not 1%. |
+| **Base** | Net taxable value of supplies through ECO = gross supplies − returns/refunds (Sec 52(3) + Rule 67(1)) |
+| **Frequency** | Monthly. **GSTR-8 due 10th of following month.** |
+| **Liability** | Platform deposits to govt; consultant claims credit in GSTR-2B. |
+| **Penalty** | Equal to TCS not collected (Sec 122(1)(viii)) + 18% p.a. interest (Sec 50(3)) |
Implementation:
@@ -115,17 +119,16 @@ Phased — TCS first because it has a deadline (monthly):
- A B2C purchase by a Karnataka consumer of a Karnataka-registered consultant: invoice shows CGST 9% + SGST 9%, place of supply = KA.
- Same purchase by a Tamil Nadu consumer: invoice shows IGST 18%, place of supply = TN.
- Same purchase by a US consumer: invoice shows zero GST, "Zero-rated export under IGST Sec 16", LUT number on the invoice.
-- A purchase by any consumer of a GST-registered consultant emits `Payment.gstTcsCollectedPaise` = **0.5%** of net (0.25% CGST + 0.25% SGST intra-state, or 0.5% IGST inter-state).
-- Monthly cron writes a `GstTcsBatch` per consultant; GSTR-8 export passes GSTN sandbox validation.
+- **CA-gated, not applicable today:** if a chartered accountant overturns the principal-supplier model (ADR 26), a purchase by any consumer of a GST-registered consultant would emit `Payment.gstTcsCollectedPaise` = **0.5%** of net (0.25% CGST + 0.25% SGST intra-state, or 0.5% IGST inter-state), and a monthly cron would write a `GstTcsBatch` per consultant whose GSTR-8 export passes GSTN sandbox validation. Under the current principal-supplier model neither field is populated and no GSTR-8 is filed.
- A refund post-invoice issues a GST credit note (see doc 05).
## Don't build
-| Don't build | Reason |
-|---|---|
-| Internal IRP integration | Use a licensed GSP connector (ClearTax / IRIS / Masters India). Already integrated. |
-| B2C IRN today | Voluntary pilot only. Wait for mandatory rollout. |
-| Self-managed GSTN portal session | GSP partners provide stable APIs; don't reverse the portal. |
+| Don't build | Reason |
+| -------------------------------- | ----------------------------------------------------------------------------------- |
+| Internal IRP integration | Use a licensed GSP connector (ClearTax / IRIS / Masters India). Already integrated. |
+| B2C IRN today | Voluntary pilot only. Wait for mandatory rollout. |
+| Self-managed GSTN portal session | GSP partners provide stable APIs; don't reverse the portal. |
## References
@@ -133,9 +136,9 @@ Phased — TCS first because it has a deadline (monthly):
- [GSTR-8 (ClearTax)](https://cleartax.in/s/gstr-8)
- [HSN/SAC requirement clarification (A2Z Taxcorp)](https://a2ztaxcorp.net/cbic-issued-clarification-on-gstns-tweet-hsn-code-requirement-in-gstr-1-mandatory-for-b2b-optional-for-b2c-below-%E2%82%B95-crore-turnover/)
- [Place of supply for online services (VJM Global)](https://www.vjmglobal.com/blog/clarification-on-place-supply-online-services-supplied-by-suppliers-services-to-unregistered-recipients)
-- [GST Sec 9(5) — when ECO is deemed supplier (ClearTax)](https://cleartax.in/s/gst-on-notified-services-ecommerce-operators-95) — *not applicable to consulting/education; we're a facilitator, not deemed supplier*
-- [GST 2.0 two-slab rationalization (5% + 18%), effective 22-Sep-2025 — PIB](https://static.pib.gov.in/WriteReadData/specificdocs/documents/2025/sep/doc202594628401.pdf) — *verified 2026-06-05; professional services remain 18%*
-- [SAC 998311 = management consulting; 999293 = commercial training & coaching, both 18% (ClearTax SAC 9983)](https://cleartax.in/s/other-professional-services-gst-rates-sac-code-9983) — *verified 2026-06-05*
-- [GST TCS §52 halved 1% → 0.5% by Notif 15/2024-CT, w.e.f. 10-Jul-2024 (GST Safar)](https://gstsafar.com/tcs-rate-for-e-commerce-operator/) — *verified 2026-06-05*
-- [E-invoice AATO ≥ ₹5 cr unchanged; 30-day IRP reporting at ₹10 cr since 1-Apr-2025 (Tally)](https://tallysolutions.com/accounting/e-invoicing-rules-in-india/) — *verified 2026-06-05*
+- [GST Sec 9(5) — when ECO is deemed supplier (ClearTax)](https://cleartax.in/s/gst-on-notified-services-ecommerce-operators-95) — _not applicable to consulting/education; we're a facilitator, not deemed supplier_
+- [GST 2.0 two-slab rationalization (5% + 18%), effective 22-Sep-2025 — PIB](https://static.pib.gov.in/WriteReadData/specificdocs/documents/2025/sep/doc202594628401.pdf) — _verified 2026-06-05; professional services remain 18%_
+- [SAC 998311 = management consulting; 999293 = commercial training & coaching, both 18% (ClearTax SAC 9983)](https://cleartax.in/s/other-professional-services-gst-rates-sac-code-9983) — _verified 2026-06-05_
+- [GST TCS §52 halved 1% → 0.5% by Notif 15/2024-CT, w.e.f. 10-Jul-2024 (GST Safar)](https://gstsafar.com/tcs-rate-for-e-commerce-operator/) — _verified 2026-06-05_
+- [E-invoice AATO ≥ ₹5 cr unchanged; 30-day IRP reporting at ₹10 cr since 1-Apr-2025 (Tally)](https://tallysolutions.com/accounting/e-invoicing-rules-in-india/) — _verified 2026-06-05_
- See also: [05](./05-refund-and-chargeback-tax-adjustments.md) (credit notes), [07](./07-cross-border-flows.md) (LUT, RCM, IGST Sec 16).
diff --git a/docs/compliance/04-tds-quarterly-filings.md b/docs/compliance/04-tds-quarterly-filings.md
index 404c7d2a3..247283df3 100644
--- a/docs/compliance/04-tds-quarterly-filings.md
+++ b/docs/compliance/04-tds-quarterly-filings.md
@@ -1,6 +1,6 @@
# 04 — Form 26Q / 27Q / 16A — quarterly TDS returns + consultant certificates
-> **Status:** schema-tracking is real (`TDSRecord.reportedInForm26Q` flag); FVU export + filing automation + Form 16A generation all missing. 🔴 **NEW (2026-06-05): the Income-tax Act, 2025 + Income-tax Rules, 2026 renamed every TDS form w.e.f. 1-Apr-2026 — 26Q→Form 140, 27Q→Form 144, 16A→Form 131. The `reportedInForm26Q` flag name is now a legacy label (the *concept* is unchanged; the form it maps to is Form 140 for FY 2026-27+).**
+> **Status:** schema-tracking is real (`TDSRecord.reportedInForm26Q` flag); FVU export + filing automation + Form 16A generation all missing. 🔴 **NEW (2026-06-05): the Income-tax Act, 2025 + Income-tax Rules, 2026 renamed every TDS form w.e.f. 1-Apr-2026 — 26Q→Form 140, 27Q→Form 144, 16A→Form 131. The `reportedInForm26Q` flag name is now a legacy label (the _concept_ is unchanged; the form it maps to is Form 140 for FY 2026-27+).**
> **Audience:** payout pipeline + admin tax-ops dashboard.
> **Last reviewed:** 2026-06-05 (regulatory facts web-verified as of 2026-06-05; prior review 2026-05-02)
> **Linked issues:** [#737 §6](https://github.com/Practitionist/familiarise_web/issues/737), [#738 Phase 2 PR 2.2](https://github.com/Practitionist/familiarise_web/issues/738).
@@ -9,39 +9,40 @@
Three related deliverables to the income-tax department after every quarter's TDS deductions. **Form names changed under the Income-tax Act, 2025 (Income-tax Rules, 2026, G.S.R. 198(E)) for any return covering a period on/after 1-Apr-2026** — verified 2026-06-05:
-| Deliverable | Form (1961 Act → 2025 Act) | Frequency | Audience |
-|---|---|---|---|
-| Quarterly TDS return (resident payees) | **26Q → Form 140** | Quarterly | Income Tax Dept (TRACES / NSDL) |
-| Quarterly TDS return (non-resident payees) | **27Q → Form 144** | Quarterly | Income Tax Dept |
-| Consultant TDS certificate (income other than salary, §195(4) wording) | **16A → Form 131** | Issued within 15 days of return due date | The consultant |
+| Deliverable | Form (1961 Act → 2025 Act) | Frequency | Audience |
+| ---------------------------------------------------------------------- | -------------------------- | ---------------------------------------- | ------------------------------- |
+| Quarterly TDS return (resident payees) | **26Q → Form 140** | Quarterly | Income Tax Dept (TRACES / NSDL) |
+| Quarterly TDS return (non-resident payees) | **27Q → Form 144** | Quarterly | Income Tax Dept |
+| Consultant TDS certificate (income other than salary, §195(4) wording) | **16A → Form 131** | Issued within 15 days of return due date | The consultant |
**Filing transition (verified):** Q4 FY 2025-26 (period up to 31-Mar-2026) returns are still filed under the **old** form names (26Q/27Q/16A) + old section numbers. From the Q1 FY 2026-27 return onward (Apr–Jun 2026, due ~31-Jul-2026), use the **new** form numbers (140/144/131) + §393 payment codes (the 10xx series — see [doc 01](./01-tds-overview.md)). Section codes inside the FVU change from `194O`/`194J`/`194C` strings to the numeric §393 payment codes. Related renumbering: 24Q→138, 16→130, 26AS→168, 15CA→145, 15CB→146.
**Cadence (unchanged for FY 2025-26 and FY 2026-27 — due dates were not altered by the 2025 Act; verified 2026-06-05):**
-| Quarter | Period | Return due |
-|---|---|---|
-| Q1 | Apr–Jun | 31 Jul |
-| Q2 | Jul–Sep | 31 Oct |
-| Q3 | Oct–Dec | 31 Jan |
-| Q4 | Jan–Mar | **31 May** |
+| Quarter | Period | Return due |
+| ------- | ------- | ---------- |
+| Q1 | Apr–Jun | 31 Jul |
+| Q2 | Jul–Sep | 31 Oct |
+| Q3 | Oct–Dec | 31 Jan |
+| Q4 | Jan–Mar | **31 May** |
**TDS deposit (separate from return):** by **7th of following month**; March deductions by 30 Apr.
**Threshold note (verified 2026-06-05):** the §194J professional/technical threshold rose ₹30,000 → **₹50,000/FY** from FY 2026-27 (per payment-type); §194O stays at ₹5,00,000/FY for resident individuals/HUF. See [doc 01](./01-tds-overview.md).
**Penalties (section numbers shown 1961-Act → 2025-Act equivalent; the ₹/day mechanics are unchanged):**
+
- Late filing: ₹200/day under **Sec 234E** (→ §427 of the 2025 Act), capped at the TDS amount.
- Non-filing > 1 year: ₹10,000–₹1,00,000 under **Sec 271H** (→ penalty provisions consolidated in the 2025 Act).
- Wrong PAN / mis-quoted: separate Sec 271H penalty.
-🟡 *The 271H/234E → 2025-Act mappings are penalty-provision equivalents; cite the 1961-Act numbers for any return/period up to 31-Mar-2026, and verify the exact 2025-Act penalty section before quoting it in a notice. The ₹-amounts are unchanged.*
+🟡 _The 271H/234E → 2025-Act mappings are penalty-provision equivalents; cite the 1961-Act numbers for any return/period up to 31-Mar-2026, and verify the exact 2025-Act penalty section before quoting it in a notice. The ₹-amounts are unchanged._
## When it applies
### B2B (org-sponsored)
-- **Applies** for org → consultant payouts where TDS was withheld. `OrganizationPayout.tdsAmountPaise` is the source of truth.
+- **Applies** for org → consultant payouts where TDS was withheld. `OrganizationPayout.tdsAmountPaise` records what was withheld from the disbursement, and since #1354 the payout also writes a `TDSRecord` when it completes, so the return is built from `TDSRecord` on both rails rather than from the payout tables.
- Resident consultant → 26Q. Non-resident → 27Q.
- Form 16A is issued by the **deductor** (the platform) to the consultant, even though the org "paid" via its wallet/invoice. The platform is the legal deductor because we run the payout.
@@ -56,16 +57,35 @@ Three related deliverables to the income-tax department after every quarter's TD
## Current code
-| File | What it does | State |
-|---|---|---|
-| `TDSRecord` (schema) | Per-payout TDS row with FY, quarter, cumulative, deducted, rate, `reportedInForm26Q` flag | ✅ schema-final |
-| `lib/payments/tax/tds-service.ts:268, 298–312` | `getUnreportedRecordsForQuarter`, `markAsReported` | ✅ basic CRUD |
-| `lib/payments/tax/pan-crypto.ts:53` | "Only needed for Form 26Q admin filing" comment — PAN encryption helper | ✅ |
-| FVU file generator | **Missing** | 🔴 |
-| 27Q file generator (non-resident) | **Missing** | 🔴 |
-| Form 16A PDF | **Missing** | 🔴 |
-| Quarterly cron / dashboard | **Missing** | 🔴 |
-| TRACES / NSDL e-filing integration | **Missing** | 🔴 |
+| File | What it does | State |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
+| `TDSRecord` (schema) | Per-payout TDS row with FY, quarter, cumulative, deducted, rate, `reportedInForm26Q` flag | ✅ schema-final |
+| `lib/payments/tax/tds-service.ts:268, 298–312` | `getUnreportedRecordsForQuarter`, `markAsReported` | ✅ basic CRUD |
+| `lib/payments/tax/pan-crypto.ts:53` | "Only needed for Form 26Q admin filing" comment — PAN encryption helper | ✅ |
+| FVU file generator | **Missing** | 🔴 |
+| 27Q file generator (non-resident) | **Missing** | 🔴 |
+| Form 16A PDF | **Missing** | 🔴 |
+| `jobs/compliance/tds-26q-draft-export.ts` | Quarterly draft builder: aggregates the quarter's `TDSRecord` rows on both rails, prints the masked draft, writes the full-PAN CSV to storage | ✅ |
+| `.github/workflows/tds-return-draft.yml` | Runs that job at 01:20 UTC on the 5th of January, April, July and October, and on manual dispatch | ✅ |
+| `app/api/admin/compliance/tds-return/route.ts` | ADMIN-only hop that exchanges an FY and quarter for a short-lived signed URL to the CSV | ✅ |
+| Quarterly dashboard | **Missing** | 🔴 |
+| TRACES / NSDL e-filing integration | **Missing** | 🔴 |
+
+## Running the quarterly draft
+
+The draft is produced by the **TDS quarterly return draft** workflow (`.github/workflows/tds-return-draft.yml`). It runs on its own schedule at 01:20 UTC on the fifth of January, April, July and October, which is 06:50 IST on the fifth day after each fiscal quarter closes, and it can also be dispatched by hand from the Actions tab. A manual dispatch takes two optional inputs, `financialYear` in the `2026-27` form and `quarter` as a digit from 1 to 4; leaving both blank builds the quarter that closed, which is what the scheduled run does and what filing means, so a run on the fifth of April builds the January-to-March quarter of the financial year that has just ended rather than the five days of the new one. To look at a quarter that is still open you have to name it explicitly. A malformed input fails the job rather than emitting a mislabelled compliance artifact.
+
+The job produces two things. The first is a **masked** draft, printed as JSON in the workflow log and safe to read, copy and quote: it carries each deductee's type, name, section, §393 payment code, credited amount and net TDS, together with the last four characters of their PAN and never more. The second is the **full-PAN CSV** the chartered accountant actually imports, written to the private Supabase bucket `org-invoices` at `compliance/tds/-Q.csv`. The job logs only that path. There is deliberately no Actions artifact upload, because an artifact is downloadable by anyone with repository read access and this file is the one place a decrypted PAN exists outside the database.
+
+That bucket provisions itself. Until September 2026 the `org-invoices` bucket had never actually been created on the live Supabase project, so the first end-to-end run of this job failed with `Bucket not found`, and the organization invoice PDF route shared the same latent fault because both write through the same helper. The upload path now calls `ensurePrivateFinanceBucket` in `lib/storage/private-finance-object.ts` before every write. That function asks Supabase for the bucket and creates it as a private bucket with a 25MB per-object limit only when it is genuinely absent, then remembers the answer for the rest of the process. No operator has to create anything by hand, and re-running the job against a fresh project is safe. Note that the separate `invoices` bucket visible in the Supabase dashboard is an unrelated March 2026 leftover that no current code path reads or writes, and it should not be confused with this one.
+
+To fetch the CSV, an admin calls `GET /api/admin/compliance/tds-return?financialYear=2026-27&quarter=2`. The route is ADMIN-only rather than merely privileged, because the object it hands out carries decrypted PANs and that is the same bar `/api/admin/tds?view=form26q` has always applied. Both query parameters are validated as a canonical April-to-March pair and a single digit from 1 to 4, so a malformed period is answered with a 400 rather than a redirect to some other quarter's file. The route answers 404 when no CSV exists for that quarter, which means the workflow has not been run for it yet, and otherwise redirects to a signed URL that expires after ten minutes. That short window is intentional: a URL left in a browser history or a chat message is dead long before anyone else finds it.
+
+The CSV has one row per deductee and section, with the columns `deductee_type`, `pan`, `deductee_name`, `section`, `payment_code`, `amount_credited_paise`, `tds_deducted_paise`, `quarter`, `financial_year` and `is_reversal`. A deductee whose withholding was reversed during the quarter gets a second row with `is_reversal` set to true, a zero credited amount and the negative reversal figure, because the portal treats a reversal as an adjustment against a previously reported credit rather than as a new credit of its own. Values are escaped against spreadsheet formula injection, but a cell that is a plain number is left alone, so the negative figures import as numbers rather than as text.
+
+**The FVU step is still a human one.** The CSV is an input to the official NSDL Return Preparation Utility, not a replacement for it: nothing in this pipeline generates or validates an FVU file, and nothing files anything with TRACES. The workflow also deliberately does not stamp `reportedInForm26Q`, so re-running it for the same quarter is safe and idempotent, and the flag continues to mean "a human filed this" rather than "a job exported this".
+
+Two warnings on the draft deserve attention before filing. A deductee with no PAN on file has to be withheld at the punitive rate under §397(2), so the draft names how many lines are affected and the withheld amount should be checked before the return goes out. From FY 2026-27 the draft also flags any section with no §393 payment code, which means no effective-dated `TdsRate` row covers that section as at the quarter end.
## Gap
@@ -102,17 +122,17 @@ In commit order:
## Don't build
-| Don't build | Reason |
-|---|---|
-| Internal NSDL portal scraper | TRACES requires DSC + 2FA; portal scraping breaks regularly. Use a GSP. |
+| Don't build | Reason |
+| -------------------------------- | ------------------------------------------------------------------------------------- |
+| Internal NSDL portal scraper | TRACES requires DSC + 2FA; portal scraping breaks regularly. Use a GSP. |
| Custom 16A template font-by-font | Standard PDF template ships with the income-tax dept's RPU. Use the canonical layout. |
## References
- [Form 26Q (ClearTax)](https://cleartax.in/s/tds-return-non-salary)
-- [TDS return due dates (SAG Infotech)](https://blog.saginfotech.com/due-date-filing-tds-tcs-return) — *quarterly due dates unchanged for FY 2026-27; verified 2026-06-05*
-- [New TDS/TCS forms under IT Act 2025 — 26Q→140, 27Q→144, 16A→131 (TDSMan, Mar 2026)](https://blog.tdsman.com/2026/03/new-tds-tcs-forms-it-act-2025-mapping-with-old-forms/) — *verified 2026-06-05*
-- [12 key tax forms changing from 1-Apr-2026 (Business Today)](https://www.businesstoday.in/personal-finance/tax/story/new-income-tax-act-2025-explained-12-key-tax-forms-changing-from-april-1-2026-530661-2026-05-10) — *verified 2026-06-05*
+- [TDS return due dates (SAG Infotech)](https://blog.saginfotech.com/due-date-filing-tds-tcs-return) — _quarterly due dates unchanged for FY 2026-27; verified 2026-06-05_
+- [New TDS/TCS forms under IT Act 2025 — 26Q→140, 27Q→144, 16A→131 (TDSMan, Mar 2026)](https://blog.tdsman.com/2026/03/new-tds-tcs-forms-it-act-2025-mapping-with-old-forms/) — _verified 2026-06-05_
+- [12 key tax forms changing from 1-Apr-2026 (Business Today)](https://www.businesstoday.in/personal-finance/tax/story/new-income-tax-act-2025-explained-12-key-tax-forms-changing-from-april-1-2026-530661-2026-05-10) — _verified 2026-06-05_
- [Income-tax e-filing portal](https://www.incometax.gov.in/iec/foportal/)
- [NSDL TRACES](https://contents.tdscpc.gov.in/)
- See also: [01](./01-tds-overview.md) (sections + rates + §393 codes), [07](./07-cross-border-flows.md) (27Q→144 for non-residents), [05](./05-refund-and-chargeback-tax-adjustments.md) (refund-of-quarter-already-filed handling).
diff --git a/docs/compliance/10-rbi-pa-and-payment-architecture.md b/docs/compliance/10-rbi-pa-and-payment-architecture.md
index 2a8a28874..ba49cdb8f 100644
--- a/docs/compliance/10-rbi-pa-and-payment-architecture.md
+++ b/docs/compliance/10-rbi-pa-and-payment-architecture.md
@@ -7,7 +7,7 @@
## What it is
-The **Reserve Bank of India (Regulation of Payment Aggregators) Directions, 2025** — reference **RBI/DPSS/2025-26/141**, dated **15 September 2025**. It consolidates and **repeals** the earlier PA guidelines (DPSS PA/PG guidelines of 17 Mar 2020 + 31 Mar 2021) and the PA-CB circular (31 Oct 2023), and for the first time formally categorises three PA types: **PA-Online (PA-O)**, **PA-Physical (PA-P)**, and **PA-Cross-Border (PA-CB)**. *(Title + reference number verified 2026-06-05 against rbi.org.in.)*
+The **Reserve Bank of India (Regulation of Payment Aggregators) Directions, 2025** — reference **RBI/DPSS/2025-26/141**, dated **15 September 2025**. It consolidates and **repeals** the earlier PA guidelines (DPSS PA/PG guidelines of 17 Mar 2020 + 31 Mar 2021) and the PA-CB circular (31 Oct 2023), and for the first time formally categorises three PA types: **PA-Online (PA-O)**, **PA-Physical (PA-P)**, and **PA-Cross-Border (PA-CB)**. _(Title + reference number verified 2026-06-05 against rbi.org.in.)_
The most-cited operative constraint for marketplaces:
@@ -17,15 +17,15 @@ This affects every marketplace that today receives consumer payments and pays ou
**Two paths the direction permits:**
-| Path | Mechanism | Onboarding burden | Settlement timing |
-|---|---|---|---|
-| **A — PA Sub-Merchant** (Razorpay Route) | Each consultant is a fully-KYC'd sub-merchant under Razorpay's PA license. Razorpay handles split settlement at payment time. | High — per-consultant V-CIP, PAN, Aadhaar, bank proof. | Tn+1 to consultant. |
-| **B — Escrow Account** | Marketplace (as an authorised PA) maintains the RBI-mandated escrow with a Scheduled Commercial Bank. Funds enter escrow; debits restricted to merchant payouts, refunds, commission per the Directions. | Low at consultant level; high at platform level (requires PA authorisation: ₹15 cr net worth + escrow governance). | Contractual, within the Directions' settlement norms. |
+| Path | Mechanism | Onboarding burden | Settlement timing |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
+| **A — PA Sub-Merchant** (Razorpay Route) | Each consultant is a fully-KYC'd sub-merchant under Razorpay's PA license. Razorpay handles split settlement at payment time. | High — per-consultant V-CIP, PAN, Aadhaar, bank proof. | Tn+1 to consultant. |
+| **B — Escrow Account** | Marketplace (as an authorised PA) maintains the RBI-mandated escrow with a Scheduled Commercial Bank. Funds enter escrow; debits restricted to merchant payouts, refunds, commission per the Directions. | Low at consultant level; high at platform level (requires PA authorisation: ₹15 cr net worth + escrow governance). | Contractual, within the Directions' settlement norms. |
**A third de facto path the direction does NOT explicitly forbid:**
-| Path | Mechanism | Notes |
-|---|---|---|
+| Path | Mechanism | Notes |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **C — Operating account + separate licensed payout** | Consumer → PA → platform's operating account (platform IS the merchant). Platform separately uses a licensed FAA (e.g. RazorpayX Bulk Payouts) to pay consultants from operating funds. | Two separate RBI-licensed flows. Consultant is NOT settled by the PA — they're paid by us via a different licensed product. |
## What architecture does Practitionist actually use?
@@ -39,9 +39,10 @@ Consumer → Razorpay PG (PA license) → Practitionist operating account (we ar
```
**This is Path C.** Specifically:
+
- We are NOT using Razorpay Route — `razorpayContactId` + `razorpayFundAccountId` are RazorpayX Bulk Payouts identifiers, NOT Route sub-merchant IDs.
- We are NOT using a nodal account — funds land in the platform's operating account.
-- We make a separate, licensed payout via RazorpayX (which has its own RBI authorisation as a Full-fledged Money Changers / Authorised Payment System Operator).
+- We make a separate, licensed payout via RazorpayX. Razorpay holds RBI payment-aggregator authorisation — final online PA authorisation was reported in December 2023, cross-border PA authorisation followed in December 2025, and the offline PA-P licence followed in January 2026 — and RazorpayX payouts are executed from the platform's own current account through Razorpay's partner banks, not from PA escrow.
## Why Path C is likely permitted
@@ -57,28 +58,28 @@ This is the same architecture used by every B2B SaaS marketplace, every freelanc
Even on Path C, the direction imposes:
-| # | Requirement | Status |
-|---|---|---|
-| 1 | **Marketplace declaration** to Razorpay | Done at PA onboarding; sign annual self-declaration |
-| 2 | **Refund SLA** to consumers (RBI-prescribed timelines) | Implementation pending — see [doc 09](./09-consumer-protection-and-grievance.md) |
-| 3 | **Prohibited categories monitoring** | Active — Razorpay flags + we add platform-level ToS |
-| 4 | **Data localisation** of payment data | Already enforced — RBI "Storage of Payment System Data" directive, 6 Apr 2018; Razorpay infra is India-based |
-| 5 | **PCI-DSS** — never store card numbers / CVV / etc. | Already compliant — we use Razorpay tokens |
-| 6 | **Chargeback handling** within 7-day evidence window | Implementation pending — see [doc 09](./09-consumer-protection-and-grievance.md) |
-| 7 | **PA-CB approval** for cross-border collections | Razorpay holds it; we enable cross-border settings — see [doc 07](./07-cross-border-flows.md) |
+| # | Requirement | Status |
+| --- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| 1 | **Marketplace declaration** to Razorpay | Done at PA onboarding; sign annual self-declaration |
+| 2 | **Refund SLA** to consumers (RBI-prescribed timelines) | Implementation pending — see [doc 09](./09-consumer-protection-and-grievance.md) |
+| 3 | **Prohibited categories monitoring** | Active — Razorpay flags + we add platform-level ToS |
+| 4 | **Data localisation** of payment data | Already enforced — RBI "Storage of Payment System Data" directive, 6 Apr 2018; Razorpay infra is India-based |
+| 5 | **PCI-DSS** — never store card numbers / CVV / etc. | Already compliant — we use Razorpay tokens |
+| 6 | **Chargeback handling** within 7-day evidence window | Implementation pending — see [doc 09](./09-consumer-protection-and-grievance.md) |
+| 7 | **PA-CB approval** for cross-border collections | Razorpay holds it; we enable cross-border settings — see [doc 07](./07-cross-border-flows.md) |
## Wallet auto-top-up and the e-mandate framework
-`OrgBillingAccount.autoTopUpMandateId` (a "gateway recurring-payment token") lets the wallet auto-recharge by `autoTopUpAmountPaise` when the balance drops below `minBalancePaise`. Recurring debits against a stored mandate are governed by the **RBI Digital Payments — E-mandate Framework, 2026** (issued **21 April 2026**, effective immediately), which consolidates all prior e-mandate / UPI-AutoPay circulars across cards, PPIs, and UPI. *(Verified 2026-06-05.)*
+`OrgBillingAccount.autoTopUpMandateId` (a "gateway recurring-payment token") lets the wallet auto-recharge by `autoTopUpAmountPaise` when the balance drops below `minBalancePaise`. Recurring debits against a stored mandate are governed by the **RBI Digital Payments — E-mandate Framework, 2026** (issued **21 April 2026**, effective immediately), which consolidates all prior e-mandate / UPI-AutoPay circulars across cards, PPIs, and UPI. _(Verified 2026-06-05.)_
Operative limits for the auto-top-up mandate:
-| # | Rule | Effect on auto-top-up |
-|---|---|---|
-| 1 | Mandate **registration** requires Additional Factor of Authentication (AFA) — a one-time auth when the org sets up the mandate. | The first mandate setup must go through full AFA at the gateway. |
-| 2 | Subsequent recurring debits run **without AFA up to ₹15,000 per transaction**; debits above that need AFA per transaction. | Keep `autoTopUpAmountPaise` ≤ ₹15,000 (1,500,000 paise) to stay in the no-AFA lane; larger top-ups will prompt per-debit AFA and can fail silently if unattended. |
-| 3 | **Pre-debit notification** to the payer **≥ 24h** before each debit, with opt-out. | The gateway issues this; ensure the mandate is registered with a reachable contact so notifications land. |
-| 4 | ₹1 lakh per-transaction no-AFA ceiling applies only to insurance / mutual-fund / credit-card-bill categories — **not** wallet top-ups. | Do not assume the ₹1 lakh ceiling for wallet recharges; the ₹15,000 cap governs. |
+| # | Rule | Effect on auto-top-up |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1 | Mandate **registration** requires Additional Factor of Authentication (AFA) — a one-time auth when the org sets up the mandate. | The first mandate setup must go through full AFA at the gateway. |
+| 2 | Subsequent recurring debits run **without AFA up to ₹15,000 per transaction**; debits above that need AFA per transaction. | Keep `autoTopUpAmountPaise` ≤ ₹15,000 (1,500,000 paise) to stay in the no-AFA lane; larger top-ups will prompt per-debit AFA and can fail silently if unattended. |
+| 3 | **Pre-debit notification** to the payer **≥ 24h** before each debit, with opt-out. | The gateway issues this; ensure the mandate is registered with a reachable contact so notifications land. |
+| 4 | ₹1 lakh per-transaction no-AFA ceiling applies only to insurance / mutual-fund / credit-card-bill categories — **not** wallet top-ups. | Do not assume the ₹1 lakh ceiling for wallet recharges; the ₹15,000 cap governs. |
This is a forward-looking note: the auto-top-up cron exists in schema, but live mandate registration must respect these limits at the gateway integration layer.
@@ -98,23 +99,32 @@ This is a forward-looking note: the auto-top-up cron exists in schema, but live
## Current code
-| Item | What it does | State |
-|---|---|---|
-| `lib/payments/payouts/razorpay-payouts.ts` | RazorpayX Bulk Payouts API client | ✅ live |
-| `lib/payments/payouts/stripe-connect.ts` | Stripe Connect for cross-border consultant payouts | ✅ live |
-| `lib/payments/payouts/payout-service.ts` (B2C) | Consultant payout pipeline | ✅ live |
-| `lib/payments/payouts/org-payout-service.ts` (B2B) | Org payout pipeline | ✅ live |
-| Razorpay PG checkout | ✅ live | |
-| Architecture memo | **Missing** — there's no doc explicitly stating "we are on Path C and here's why" | 🟡 |
+| Item | What it does | State |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------- |
+| `lib/payments/payouts/razorpay-payouts.ts` | RazorpayX Bulk Payouts API client | ✅ live |
+| `lib/payments/payouts/stripe-connect.ts` | Stripe Connect for cross-border consultant payouts | ✅ live |
+| `lib/payments/payouts/payout-service.ts` (B2C) | Consultant payout pipeline | ✅ live |
+| `lib/payments/payouts/org-payout-service.ts` (B2B) | Org payout pipeline | ✅ live |
+| Razorpay PG checkout | ✅ live | |
+| Architecture memo | **Written (2026-09-03)** — this document is the memo stating "we are on Path C and here's why" | ✅ |
## Gap
-| Gap | Severity |
-|---|---|
-| No memo at `docs/payments/` documenting the architecture vs the Sep 2025 direction | 🟡 |
-| No CA / RBI-compliance opinion validating Path C for our specific facts | 🟡 |
-| No annual Razorpay marketplace self-declaration captured + filed | 🟢 (assumed Razorpay does this; verify) |
-| No prohibited-categories monitoring at platform-ToS level (Razorpay flags only) | 🟢 |
+| Gap | Severity |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No memo at `docs/payments/` documenting the architecture vs the Sep 2025 direction | ✅ **Written (2026-09-03)** — this document (`docs/compliance/10-rbi-pa-and-payment-architecture.md`), together with `docs/enterprise/70-design-decisions/26-gst-principal-model.md` and `docs/payments/audits/2026-09-03-finance-verdicts.md`, is the architecture memo this row asked for; the fact-specific risk paragraph in §A above stays the operative text. |
+| No CA / RBI-compliance opinion validating Path C for our specific facts | 🟡 still open — see the CA action list below |
+| No annual Razorpay marketplace self-declaration captured + filed | 🟢 (assumed Razorpay does this; verify) |
+| No prohibited-categories monitoring at platform-ToS level (Razorpay flags only) | 🟢 |
+
+### CA action list (2026-09-03)
+
+The chartered accountant engagement this section calls for now has a concrete question list, gathered from the 2026-09-03 finance audit rather than left as an open-ended "review the memo" ask.
+
+1. Confirm Path C (Razorpay PG as the merchant of record, RazorpayX payouts as a separately licensed rail) is permitted for a consulting marketplace under the RBI PA Directions 2025, as this document's §B already asks.
+2. Answer the five questions in [ADR 26](./../enterprise/70-design-decisions/26-gst-principal-model.md#questions-for-the-chartered-accountant): whether Principal-for-GST paired with 194-O-operator-for-income-tax holds together, how a platform-funded referral credit should be treated for taxable value, the correct SAC code, whether the Section 12(2)(b) supplier-state default is acceptable, and whether Section 52 TCS registration is required at all under this model.
+3. Weigh in on #1388, the specific code-path question about referral credits being applied after tax at checkout (`deriveCheckoutAmount`), which nothing in the code changes until it is answered.
+4. Confirm which authorisation RazorpayX payouts operate under and whether any additional registration is needed for platform-initiated payouts to consultants.
## Required
@@ -131,6 +141,7 @@ Add `docs/payments/06-pa-master-direction-architecture.md` (or similar):
### B. CA / legal opinion (PR 2 — out-of-band)
Engage a CA + an RBI-specialised counsel:
+
- Review the architecture memo.
- Confirm Path C is permitted for our facts.
- Document the opinion with their UDIN / signature.
@@ -165,18 +176,18 @@ The migration cost (per-consultant V-CIP for Path A, or nodal-account governance
## Don't build
-| Don't build | Reason |
-|---|---|
-| Razorpay Route migration | Path A burden is high and not required given Path C is permitted. Wait for legal opinion. |
-| Self-custodied escrow | Requires ₹15 cr net worth + RBI approval. Not viable. |
-| Direct nodal-account integration with an SPD bank | Path B governance is heavy; only if a specific feature demands it. |
+| Don't build | Reason |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Razorpay Route migration | Path A burden is high and not required given Path C is permitted. Wait for legal opinion. |
+| Self-custodied escrow | Requires ₹15 cr net worth + RBI approval. Not viable. |
+| Direct nodal-account integration with an SPD bank | Path B governance is heavy; only if a specific feature demands it. |
## References
-- [RBI (Regulation of Payment Aggregators) Directions, 2025 — RBI/DPSS/2025-26/141, 15 Sep 2025 (RBI master-directions page)](https://www.rbi.org.in/Scripts/BS_ViewMasDirections.aspx?id=12896) *(title + ref no. verified 2026-06-05)*
+- [RBI (Regulation of Payment Aggregators) Directions, 2025 — RBI/DPSS/2025-26/141, 15 Sep 2025 (RBI master-directions page)](https://www.rbi.org.in/Scripts/BS_ViewMasDirections.aspx?id=12896) _(title + ref no. verified 2026-06-05)_
- [RBI PA Directions 2025 — full text (FIDC mirror)](https://www.fidcindia.org.in/wp-content/uploads/2025/09/RBI-PAYMENT-AGGREGATORS-DIRECTIONS-15-09-25.pdf)
- [PA Directions 2025 analysis (Khaitan & Co)](https://www.khaitanco.com/sites/default/files/2025-10/ERGO%20-%20PA%20Master%20Directions%20-%203%20Oct%202025_0.pdf)
-- [RBI Digital Payments — E-mandate Framework, 2026 (issued 21 Apr 2026) — coverage](https://www.businesstoday.in/personal-finance/news/story/rbi-caps-recurring-payments-at-rs15000-without-otp-under-new-e-mandate-framework-526759-2026-04-21) *(₹15,000 no-AFA cap verified 2026-06-05; replace with the RBI primary circular URL when indexed)*
+- [RBI Digital Payments — E-mandate Framework, 2026 (issued 21 Apr 2026) — coverage](https://www.businesstoday.in/personal-finance/news/story/rbi-caps-recurring-payments-at-rs15000-without-otp-under-new-e-mandate-framework-526759-2026-04-21) _(₹15,000 no-AFA cap verified 2026-06-05; replace with the RBI primary circular URL when indexed)_
- [Razorpay Payment Gateway Compliance 2026](https://razorpay.com/blog/payment-gateway-compliance/)
- [Razorpay KYC Onboarding Guide 2026](https://razorpay.com/blog/payment-gateway-kyc-onboarding-india)
- See also: [07](./07-cross-border-flows.md) (PA-CB), [09](./09-consumer-protection-and-grievance.md) (refund SLA, chargeback handling).
diff --git a/docs/compliance/15-india-compliance-shipping-checklist.md b/docs/compliance/15-india-compliance-shipping-checklist.md
index 0151a99c4..ac60c8234 100644
--- a/docs/compliance/15-india-compliance-shipping-checklist.md
+++ b/docs/compliance/15-india-compliance-shipping-checklist.md
@@ -10,75 +10,76 @@ the design-partner merge, **WHEN-ASKED** by the first enterprise buyer,
or **DEFER** indefinitely. Compliance is not over-engineered — every
MUST item is the actual law of the land in 2026.
-> **2026-06-05 regulatory deltas to mind (verified):** 194-O is **0.1%**, not 1% (§1.1 corrected). GST TCS §52 is **0.5%** since 10-Jul-2024. From **1-Apr-2026** the Income-tax Act, 2025 renames TDS forms (26Q→140, 27Q→144, 16A→131) and replaces section numbers with §393 payment codes — a **filing-export** concern, the withholding *math* is unchanged. GST 2.0 (22-Sep-2025) → two slabs 5%/18%; consulting stays 18%. MSME Udyam thresholds revised 1-Apr-2025 (Micro ₹2.5cr/₹10cr · Small ₹25cr/₹100cr · Medium ₹125cr/₹500cr).
+> **2026-06-05 regulatory deltas to mind (verified):** 194-O is **0.1%**, not 1% (§1.1 corrected). GST TCS §52 is **0.5%** since 10-Jul-2024. From **1-Apr-2026** the Income-tax Act, 2025 renames TDS forms (26Q→140, 27Q→144, 16A→131) and replaces section numbers with §393 payment codes — a **filing-export** concern, the withholding _math_ is unchanged. GST 2.0 (22-Sep-2025) → two slabs 5%/18%; consulting stays 18%. MSME Udyam thresholds revised 1-Apr-2025 (Micro ₹2.5cr/₹10cr · Small ₹25cr/₹100cr · Medium ₹125cr/₹500cr).
---
## §1 — MUST ship in this PR (legally mandatory before design-partner merge)
-| # | Item | Status | File:line evidence |
-|---|---|---|---|
-| 1.1 | **TDS withholding wired into org payouts** — Section 194-O default **0.1%** (`"194O": 0.001`, cut from 1% w.e.f. 1-Oct-2024 — verified 2026-06-05; **the old "1%" here was wrong**), **194-O no-PAN fallback 5%** (`NO_PAN_RATE_194O`) / 206AA 20% for 194J/194C. `tdsAmountPaise` deducted from gross before gateway dispatch; `tdsSectionApplied`, `dtaaRateApplied` persisted on `OrganizationPayout`. 🟡 *Section labels are still 1961-Act strings (`194O`/`194J`/`194C`); must map to §393 payment codes before any FY 2026-27 return upload (see [doc 01](./01-tds-overview.md)).* | ✅ This PR | `lib/payments/payouts/org-payout-service.ts` (createOrgPayoutBatch tx); `lib/compliance/tds.ts` (canonical lib) |
-| 1.2 | **MSME 43B(h) deadline tracking on org payouts** — `mustPayByDate` derived from `Organization.msmeStatus` + `msmeWrittenAgreementOnFile`, not a hardcoded `NONE` stub. | ✅ This PR | `lib/payments/payouts/org-payout-service.ts`; `lib/compliance/msme.ts`; schema `Organization.msmeStatus`/`msmeWrittenAgreementOnFile` |
-| 1.3 | **DPDP consent stamping at signup + Stream gate** — essential-purpose `ConsentArtifact` written in the BetterAuth `user.create.after` hook; `STREAM_DATA_PROCESSING` gate refuses Stream upsert when consent absent. | ✅ This PR | `lib/auth.ts` (user.create.after hook); `actions/stream/chat/user.action.ts` (`checkConsent` gate, single + batch) |
-| 1.4 | **GST place-of-supply state code is env-driven** — `SUPPLIER_STATE_CODE` env replaces hardcoded `"KA"`. Place-of-supply rules pick CGST+SGST vs IGST correctly when business address changes. | ✅ This PR | `.env.sample`; `jobs/billing/generate-subscription-invoices.ts`; `app/api/organizations/[orgId]/billing-account/invoices/route.ts` |
-| 1.5 | **Per-org sequential invoice numbering (CGST Rule 46)** — atomic counter table `org_invoice_counters`, `INSERT ON CONFLICT DO UPDATE RETURNING`, format `--`, unbroken sequence per (org, fiscal year). | ✅ This PR | `lib/payments/billing/invoice-numbering.ts`; schema `OrgInvoiceCounter`, `OrganizationInvoice.fiscalYear`, `@@unique([organizationId, invoiceNumber])` |
-| 1.6 | **IRP / IRN upload cron live + flag/creds-gated** — daily 02:30 UTC; behind `ENABLE_IRP_UPLOADER` (verified in `lib/feature-flags.ts`) + ClearTax creds; scoped to `OrganizationInvoice` `irpStatus=PENDING`, `issuedAt within 30d` (CBIC cut-off); sub-₹5cr orgs accept `FAILED`/`PENDING` until they cross AATO ≥ ₹5 cr (threshold unchanged 2026-06-05). | ✅ Already shipped (Round 2) | `jobs/compliance/irp-uploader.ts`; `.github/workflows/irp-uploader.yml`; `lib/compliance/irp.ts`; `lib/feature-flags.ts:ENABLE_IRP_UPLOADER` |
-| 1.7 | **DPDP 72-hour breach alert cron** — hourly sweep + Resend / structured-log fallback for `DataBreach WHERE reportedAt IS NULL`. | ✅ Already shipped (Round 2) | `jobs/compliance/databreach-deadline-alerts.ts`; `.github/workflows/databreach-deadline-alerts.yml` |
-| 1.8 | **GST derivation (CGST/SGST/IGST)** — zero-rated export, intra-state CGST 9% + SGST 9%, inter-state IGST 18%; live in app. | ✅ Already shipped (Round 2) | `lib/compliance/gst.ts:deriveGstBreakdown` |
-| 1.9 | **MSME payment-alert cron** — daily 04:30 UTC; alerts on overdue MSME payouts. | ✅ Already shipped (Round 2) | `jobs/compliance/msme-payment-alerts.ts`; `.github/workflows/msme-payment-alerts.yml` |
-| 1.10 | **Contract expiry cron** — daily 03:00 UTC; ACTIVE → EXPIRED on `effectiveTo` cross. | ✅ Already shipped | `jobs/compliance/contract-expiry.ts`; `.github/workflows/expire-contracts.yml` |
+| # | Item | Status | File:line evidence |
+| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 1.1 | **TDS withholding wired into org payouts** — Section 194-O default **0.1%** (`"194O": 0.001`, cut from 1% w.e.f. 1-Oct-2024 — verified 2026-06-05; **the old "1%" here was wrong**), **194-O no-PAN fallback 5%** (`NO_PAN_RATE_194O`) / 206AA 20% for 194J/194C. `tdsAmountPaise` deducted from gross before gateway dispatch; `tdsSectionApplied`, `dtaaRateApplied` persisted on `OrganizationPayout`. 🟡 _Section labels are still 1961-Act strings (`194O`/`194J`/`194C`); must map to §393 payment codes before any FY 2026-27 return upload (see [doc 01](./01-tds-overview.md))._ | ✅ This PR | `lib/payments/payouts/org-payout-service.ts` (createOrgPayoutBatch tx); `lib/compliance/tds.ts` (canonical lib) |
+| 1.2 | **MSME 43B(h) deadline tracking on org payouts** — `mustPayByDate` derived from `Organization.msmeStatus` + `msmeWrittenAgreementOnFile`, not a hardcoded `NONE` stub. | ✅ This PR | `lib/payments/payouts/org-payout-service.ts`; `lib/compliance/msme.ts`; schema `Organization.msmeStatus`/`msmeWrittenAgreementOnFile` |
+| 1.3 | **DPDP consent stamping at signup + Stream gate** — essential-purpose `ConsentArtifact` written in the BetterAuth `user.create.after` hook; `STREAM_DATA_PROCESSING` gate refuses Stream upsert when consent absent. | ✅ This PR | `lib/auth.ts` (user.create.after hook); `actions/stream/chat/user.action.ts` (`checkConsent` gate, single + batch) |
+| 1.4 | **GST place-of-supply state code is env-driven** — `SUPPLIER_STATE_CODE` env replaces hardcoded `"KA"`. Place-of-supply rules pick CGST+SGST vs IGST correctly when business address changes. | ✅ This PR | `.env.sample`; `jobs/billing/generate-subscription-invoices.ts`; `app/api/organizations/[orgId]/billing-account/invoices/route.ts` |
+| 1.5 | **Per-org sequential invoice numbering (CGST Rule 46)** — atomic counter table `org_invoice_counters`, `INSERT ON CONFLICT DO UPDATE RETURNING`, format `--`, unbroken sequence per (org, fiscal year). | ✅ This PR | `lib/payments/billing/invoice-numbering.ts`; schema `OrgInvoiceCounter`, `OrganizationInvoice.fiscalYear`, `@@unique([organizationId, invoiceNumber])` |
+| 1.6 | **IRP / IRN upload cron live + flag/creds-gated** — daily 02:30 UTC; behind `ENABLE_IRP_UPLOADER` (verified in `lib/feature-flags.ts`) + ClearTax creds; scoped to `OrganizationInvoice` `irpStatus=PENDING`, `issuedAt within 30d` (CBIC cut-off); sub-₹5cr orgs accept `FAILED`/`PENDING` until they cross AATO ≥ ₹5 cr (threshold unchanged 2026-06-05). | ✅ Already shipped (Round 2) | `jobs/compliance/irp-uploader.ts`; `.github/workflows/irp-uploader.yml`; `lib/compliance/irp.ts`; `lib/feature-flags.ts:ENABLE_IRP_UPLOADER` |
+| 1.7 | **DPDP 72-hour breach alert cron** — hourly sweep + Resend / structured-log fallback for `DataBreach WHERE reportedAt IS NULL`. | ✅ Already shipped (Round 2) | `jobs/compliance/databreach-deadline-alerts.ts`; `.github/workflows/databreach-deadline-alerts.yml` |
+| 1.8 | **GST derivation (CGST/SGST/IGST)** — zero-rated export, intra-state CGST 9% + SGST 9%, inter-state IGST 18%; live in app. | ✅ Already shipped (Round 2) | `lib/compliance/gst.ts:deriveGstBreakdown` |
+| 1.9 | **MSME payment-alert cron** — daily 04:30 UTC; alerts on overdue MSME payouts. | ✅ Already shipped (Round 2) | `jobs/compliance/msme-payment-alerts.ts`; `.github/workflows/msme-payment-alerts.yml` |
+| 1.10 | **Contract expiry cron** — daily 03:00 UTC; ACTIVE → EXPIRED on `effectiveTo` cross. | ✅ Already shipped | `jobs/compliance/contract-expiry.ts`; `.github/workflows/expire-contracts.yml` |
### Tax-adjustment infrastructure shipped in v2 (#776/#778) — schema landed, wiring tracked in §2
-| # | Item | Status | File:line evidence |
-|---|---|---|---|
-| 1.11 | **`CreditNote` model w/ per-org gapless numbering (CGST Rule 53)** — `creditNoteNumber` + `fiscalYear`, `@@unique([organizationId, creditNoteNumber])`, `refundId @unique` (idempotent refund-driven minting), Sec 34 FK to `OrganizationInvoice`. Verified present 2026-06-05. | ✅ Schema landed (v2) | `prisma/schema.prisma model CreditNote`; `lib/payments/billing/credit-note-numbering.ts` (`-CN--`) |
-| 1.12 | **`TdsAdjustment` model** — signed `amountPaise`, `financialYear`/`quarter`, `reportedInForm26Q`; for refund/chargeback TDS reversal as a negative line in the next 26Q→Form 140. Verified present 2026-06-05. | ✅ Schema landed (v2) | `prisma/schema.prisma model TdsAdjustment` |
-| 1.13 | **`GstTcsBatch` + `GstTcsAdjustment` models** — monthly GSTR-8 batch (`netSupplyPaise`/`tcsCollectedPaise`, `@@unique([financialYear, month])`) + signed-`amountPaise` reversal. **No rate constant wired** (collection stubbed pending CA signoff — when wired, use **0.5%** not 1%). Verified 2026-06-05. | ✅ Schema landed (v2); collection deferred | `prisma/schema.prisma model GstTcsBatch / GstTcsAdjustment` |
+| # | Item | Status | File:line evidence |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| 1.11 | **`CreditNote` model w/ per-org gapless numbering (CGST Rule 53)** — `creditNoteNumber` + `fiscalYear`, `@@unique([organizationId, creditNoteNumber])`, `refundId @unique` (idempotent refund-driven minting), Sec 34 FK to `OrganizationInvoice`. Verified present 2026-06-05. | ✅ Schema landed (v2) | `prisma/schema.prisma model CreditNote`; `lib/payments/billing/credit-note-numbering.ts` (`-CN--`) |
+| 1.12 | **`TdsAdjustment` model** — signed `amountPaise`, `financialYear`/`quarter`, `reportedInForm26Q`; for refund/chargeback TDS reversal as a negative line in the next Form 140 (formerly 26Q). Verified present 2026-06-05. | ✅ Schema landed (v2) | `prisma/schema.prisma model TdsAdjustment` |
+| 1.13 | **`GstTcsBatch` + `GstTcsAdjustment` models** — monthly GSTR-8 batch (`netSupplyPaise`/`tcsCollectedPaise`, `@@unique([financialYear, month])`) + signed-`amountPaise` reversal. **No rate constant wired** (collection stubbed pending CA signoff — when wired, use **0.5%** not 1%). Verified 2026-06-05. 🟡 **Update (2026-09-03):** [ADR 26](../enterprise/70-design-decisions/26-gst-principal-model.md) locked the platform in as **Principal supplier for GST**, under which Section 52 TCS collection does not apply at all — these models stay dormant by design, not by omission, and #1360 is relabelled `compliance`/`launch: post-mvp` and gated on the CA overturning that decision. | ✅ Schema landed (v2); collection deferred, CA-gated | `prisma/schema.prisma model GstTcsBatch / GstTcsAdjustment` |
-🟡 **Wiring gap (engineering follow-up, tracked in [doc 05](./05-refund-and-chargeback-tax-adjustments.md)):** these models exist but `lib/payments/operations/refund.ts` does **not** yet write adjustment rows on refund/chargeback. Until wired, every refund still distorts the next 26Q→140 / GSTR-8 period.
+🟡 **Wiring gap (engineering follow-up, tracked in [doc 05](./05-refund-and-chargeback-tax-adjustments.md)):** these models exist but `lib/payments/operations/refund.ts` does **not** yet write adjustment rows on refund/chargeback. This gap only matters on the facilitator-model path, where Section 52 TCS is actually collected; under the current principal-supplier model (ADR 26) no TCS is collected, so no refund distorts a GSTR-8 period. The TDS half of this sentence still applies unconditionally: every refund still distorts the next Form 140 return until `TdsAdjustment` rows are wired.
---
## §2 — WHEN-ASKED — next 2–4 weeks (post-merge follow-ups)
-| # | Item | Why deferred | Ship when |
-|---|---|---|---|
-| 2.1 | **Quarterly TDS returns (Form 26Q→140 / 27Q→144)** — generate the FVU with consultant-wise reconciliation; **must emit §393 numeric payment codes (not `194x` labels) for FY 2026-27** + fold in `TdsAdjustment` negative lines. | Filing-season runway is Jul (Q1 FY 2026-27 return due ~31-Jul-2026) — not blocking design-partner merge. | Before the Q1 FY 2026-27 return (~31 Jul). CA-assisted automation. |
-| 2.2 | **DPDP DSAR export endpoints** — user data export + erasure (right-to-correction, right-to-erasure under §11). | Stub paths exist (`/api/users/[id]/data-export` is a placeholder). | When first user requests under DPDP §11 or after first enterprise buyer's DPA audit. |
-| 2.3 | **In-app consent withdrawal UI** — settings page surfacing `ConsentArtifact` purpose codes, allowing revoke. | API already exists at `/api/organizations/[orgId]/consent`; only UI is missing. | Before public DPDP rules effective-date enforcement (rules-stage now; phased rollout 2025-26). |
-| 2.4 | **GSTIN registry verify** — replace 15-char regex with live GSTN portal lookup. | Audit-trail only; no immediate filing impact. | After first invoice dispute. |
-| 2.5 | **Place-of-supply state capture in B2C checkout** — needed for B2C tax math parity (B2C in separate PR). | Tracked in parallel B2C compliance PR. | When B2C compliance PR opens. |
-| 2.6 | **HSN selection logic** — 999293 vs 999299 split based on service type (currently 999293 catch-all). | CA hasn't flagged a real classification dispute. | After GST audit by CA, ideally before first ITC dispute. |
-| 2.7 | **Invoice-fraud mitigation** — session-level immutability guards on INVOICE-funded orgs; soft-delete audit. | Manual ops sufficient pre-design-partner. | Before multi-tenant self-serve. |
+| # | Item | Why deferred | Ship when |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| 2.1 | **Quarterly TDS returns (Form 140, formerly 26Q / Form 144, formerly 27Q)** — generate the FVU with consultant-wise reconciliation; **must emit §393 numeric payment codes (not `194x` labels) for FY 2026-27** + fold in `TdsAdjustment` negative lines. 🟡 **Update (2026-09-04):** the 31-Jul-2026 Q1 FY 2026-27 due date has passed. No TDS was deducted in that quarter — the `TDSRecord` table has zero rows — so no Form 140 statement was due for Q1. The first live quarter for this item is whichever quarter contains the platform's first completed payout. | Filing-season runway continues into the quarter of the first live payout — not blocking design-partner merge. | Before the Form 140 return for the quarter of the first completed payout. CA-assisted automation. |
+| 2.2 | **DPDP DSAR export endpoints** — user data export + erasure (right-to-correction, right-to-erasure under §11). | Stub paths exist (`/api/users/[id]/data-export` is a placeholder). | When first user requests under DPDP §11 or after first enterprise buyer's DPA audit. |
+| 2.3 | **In-app consent withdrawal UI** — settings page surfacing `ConsentArtifact` purpose codes, allowing revoke. | API already exists at `/api/organizations/[orgId]/consent`; only UI is missing. | Before public DPDP rules effective-date enforcement (rules-stage now; phased rollout 2025-26). |
+| 2.4 | **GSTIN registry verify** — replace 15-char regex with live GSTN portal lookup. | Audit-trail only; no immediate filing impact. | After first invoice dispute. |
+| 2.5 | **Place-of-supply state capture in B2C checkout** — needed for B2C tax math parity. 🟡 **Delivered by PR-E (2026-09-03, `feat/finance-b2c-tax-invoice`, in flight):** a `BillingStateSelect` on every checkout page writes `Payment.consumerStateCode`, and `deriveConsumerInvoiceTax` falls back to the supplier's state under Section 12(2)(b) when the buyer declines to declare one. | Carried by the B2C statutory-invoice PR. | Land with PR-E. |
+| 2.6 | **SAC/HSN selection logic** — the consumer invoice model defaults to SAC **999293** (`prisma/schema.prisma`, `ConsumerInvoice.sacCode`), with **998311** as the alternative classification pending the CA's answer (#1369); both codes carry 18% GST, so this is a classification (ITC-trail) question, not a rate question. | CA hasn't flagged a real classification dispute. | After GST audit by CA, ideally before first ITC dispute. |
+| 2.7 | **Invoice-fraud mitigation** — session-level immutability guards on INVOICE-funded orgs; soft-delete audit. | Manual ops sufficient pre-design-partner. | Before multi-tenant self-serve. |
+| 2.8 | **Outward-supplies register export** — a monthly CSV of every `ConsumerInvoice`/`ConsumerCreditNote` and `OrganizationInvoice`/`CreditNote` row, with place of supply and tax heads, for the CA to file GSTR-1 and GSTR-3B from. Carried by `lib/compliance/gst-outward-register.ts` and the `gst-outward-register-export` job in the same B2C statutory-invoice PR. | Replaces the in-app GSTR JSON builders #1361 originally asked for; the register is the platform's own outward-supply return under the Principal model. | Land with PR-E. |
---
## §3 — DEFER indefinitely (no current requirement)
-| # | Item | Justification |
-|---|---|---|
-| 3.1 | **FEMA Form 15CA / 15CB** | No non-resident consultants on platform yet. Fields exist in `OrganizationPayout` schema; populate manually when first cross-border payout ships. |
-| 3.2 | **FIRC + RBI PA-CB compliance** | Same — domestic-only today. |
-| 3.3 | **SOC 2 Type II certification** | First enterprise buyer's procurement will ask; 6-month effort. Hold until concrete ask. |
-| 3.4 | **ISO 27001 prep** | Less common ask in India B2B. Defer past SOC 2. |
-| 3.5 | **Programs v2 runtime (PROJECT, RETAINER, AOR, EOR)** | Enum values reserved; API returns 400 `PROGRAM_TYPE_NOT_AVAILABLE`. Wait for design-partner demand. |
-| 3.6 | **Multi-currency on BillingAccount / Invoice / Payout** | INR-only today. Open separate epic with ExchangeRateSnapshot model when first cross-border B2B buyer signs. |
-| 3.7 | **Custom RBAC (CustomRole + Permission tables)** | Fixed `MemberRole` enum sufficient for design partners. |
-| 3.8 | **SCIM 2.0 provisioning** | `/api/.../scim/*` placeholder returns 501. Wait for SCIM-aware IdP-demanding buyer. |
-| 3.9 | **Consumer Protection Grievance Officer UI** | Minimal compliance: contact page + email intake suffices for MVP under 30-day resolution rule. |
+| # | Item | Justification |
+| --- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 3.1 | **FEMA Form 15CA / 15CB** | No non-resident consultants on platform yet. Fields exist in `OrganizationPayout` schema; populate manually when first cross-border payout ships. |
+| 3.2 | **FIRC + RBI PA-CB compliance** | Same — domestic-only today. |
+| 3.3 | **SOC 2 Type II certification** | First enterprise buyer's procurement will ask; 6-month effort. Hold until concrete ask. |
+| 3.4 | **ISO 27001 prep** | Less common ask in India B2B. Defer past SOC 2. |
+| 3.5 | **Programs v2 runtime (PROJECT, RETAINER, AOR, EOR)** | Enum values reserved; API returns 400 `PROGRAM_TYPE_NOT_AVAILABLE`. Wait for design-partner demand. |
+| 3.6 | **Multi-currency on BillingAccount / Invoice / Payout** | INR-only today. Open separate epic with ExchangeRateSnapshot model when first cross-border B2B buyer signs. |
+| 3.7 | **Custom RBAC (CustomRole + Permission tables)** | Fixed `MemberRole` enum sufficient for design partners. |
+| 3.8 | **SCIM 2.0 provisioning** | ✅ Shipped (2026-09-03) — no longer deferred. `lib/scim/` implements Users CRUD, bearer-token authentication, group mapping and deprovisioning behind `app/scim/v2/`, and `ScimToken.expiresAt` is enforced on every request. |
+| 3.9 | **Consumer Protection Grievance Officer UI** | Minimal compliance: contact page + email intake suffices for MVP under 30-day resolution rule. |
---
## §4 — Sign-off slots
-| Reviewer | Item set | Sign-off (date / initials) |
-|---|---|---|
-| Finance lead | §1.1 (TDS), §1.2 (MSME), §1.4 (GST PoS), §1.5 (numbering) | _____________ |
-| DPDP officer | §1.3 (consent), §1.7 (breach cron) | _____________ |
-| CA (chartered accountant) | §1.1, §1.5, §1.6 (IRP), §1.8 (GST split) | _____________ |
-| Engineering lead | All §1 items + Phase 0 schema-DB sync | _____________ |
+| Reviewer | Item set | Sign-off (date / initials) |
+| ------------------------- | --------------------------------------------------------- | -------------------------- |
+| Finance lead | §1.1 (TDS), §1.2 (MSME), §1.4 (GST PoS), §1.5 (numbering) | **\*\***\_**\*\*** |
+| DPDP officer | §1.3 (consent), §1.7 (breach cron) | **\*\***\_**\*\*** |
+| CA (chartered accountant) | §1.1, §1.5, §1.6 (IRP), §1.8 (GST split) | **\*\***\_**\*\*** |
+| Engineering lead | All §1 items + Phase 0 schema-DB sync | **\*\***\_**\*\*** |
---
diff --git a/docs/enterprise/10-money-and-ledger/03-ledger-and-postings.md b/docs/enterprise/10-money-and-ledger/03-ledger-and-postings.md
index efb262626..9324511fd 100644
--- a/docs/enterprise/10-money-and-ledger/03-ledger-and-postings.md
+++ b/docs/enterprise/10-money-and-ledger/03-ledger-and-postings.md
@@ -157,11 +157,13 @@ Dr CONSULTANT_PAYABLE(consultant) net + TDS
### 4.5 Host-org payout — `ORG_PAYOUT` (`orgpayout:`)
The host-org mirror of 4.4.
```
-Dr ORG_PAYABLE(org) net + TDS
- Cr CASH(platform) net paid
- Cr TDS_PAYABLE TDS withheld (only if > 0)
+Dr ORG_PAYABLE(org) netPayoutPaise (pre-withholding org share)
+ Cr CASH(platform) amountPaise (what the rail transferred)
+ Cr TDS_PAYABLE tdsAmountPaise (withheld, only if > 0)
```
+`OrganizationPayout.netPayoutPaise` is the pre-withholding figure and `amountPaise` is the post-withholding one, so `amountPaise + tdsAmountPaise` must equal `netPayoutPaise` for these legs to be right. `markOrgPayoutCompleted` asserts exactly that before posting and throws — rolling the completion back rather than journalling a guess — when it does not hold (#1470). The same assertion also refuses a payout whose figures are negative, because the equation alone accepts one (minus one lakh plus nothing does equal minus one lakh) and the posting is skipped for anything that is not greater than zero, which would let such a row settle with no journal at all. `markOrgPayoutReversed` posts the exact mirror, `Dr CASH amountPaise` and `Dr TDS_PAYABLE tdsAmountPaise` against `Cr ORG_PAYABLE netPayoutPaise`, under the same assertion. See the [payout pipeline](07-payout-pipeline.md) for the history: the earlier shape debited the payable at `net + TDS` and credited cash at `net`, which balanced and so passed every write-time check while overstating both sides by the withholding.
+
### 4.6 Top-up refund — `TOPUP_REFUND` (`topup-refund:`)
A confirmed top-up is refunded; the IOU shrinks, cash returns to the gateway. Exact reverse of 4.1.
```
diff --git a/docs/enterprise/10-money-and-ledger/04-wallet-and-topups.md b/docs/enterprise/10-money-and-ledger/04-wallet-and-topups.md
index dd06c2e34..e4f33c160 100644
--- a/docs/enterprise/10-money-and-ledger/04-wallet-and-topups.md
+++ b/docs/enterprise/10-money-and-ledger/04-wallet-and-topups.md
@@ -28,6 +28,8 @@ A wallet is not a single model — it is a `WalletTopUp` lifecycle record paired
The `walletBalance` cache exists for exactly one reason: a conditional SQL `UPDATE … WHERE walletBalance >= amount` is the cheapest correct overdraft guard under concurrency. We can't run that guard against a derived sum, so we keep a cache and let the reconcile cron prove it never drifts. See [Concurrency & idempotency](../30-programs-and-lifecycle/01-concurrency-and-idempotency.md).
+The column is nullable, and an account that has never been credited carries `NULL` rather than zero, which is a real distinction in Postgres because `NULL + amount` is `NULL` and not the new balance. Both `walletCredit` and `walletDebit` therefore write a zero over a `NULL` in the same transaction before they touch the arithmetic, and they read the resulting balance back off the mutated row instead of coercing a `NULL` to zero (#1459). Giving the column a non-null default so the seeding step becomes unnecessary is a schema change, and it belongs to the pre-MVP database reset rather than to any migration written today.
+
---
## 2. WalletTopUp lifecycle
@@ -138,6 +140,8 @@ WHERE "id" = :id
If `rowsAffected === 0`, the balance was insufficient and it throws `WalletInsufficientFundsError`. Because the predicate and the decrement are one atomic statement, two concurrent bookings can never both drain the same last rupee.
+That refusal carries the stable code `WALLET_INSUFFICIENT_FUNDS` and `httpStatus` 402 (#1477), so checkout rethrows it unchanged, `POST /api/checkout` answers 402 with copy telling the buyer to ask their billing admin for a top-up, and Sentry records it as an expected outcome rather than a payment fault. It reports only the requested amount, never the available balance: the guard refuses without reading the row, and re-reading it would add a query inside the checkout transaction that `PG_POOL_MAX=1` would serialise behind everything else.
+
> **Important:** `walletDebit` only moves the **cache**. It does **not** post a journal leg. The accounting leg `Dr WALLET` is posted later from the settlement layer (`createEarningsFromPayment`), where the full fee/payable/GST split is known — that single balanced `booking:` transaction is also the authoritative wallet-history record. See [Booking → earnings](05-booking-to-earnings.md) and [Payment legs](09-payment-legs.md).
`walletCredit` is the mirror: it bumps the cache for any reason, but **only posts a journal txn when `reason === "TOPUP"`**. Refund credits post their WALLET leg from the refund layer (next section), not here — this keeps each cash event owning exactly one posting.
diff --git a/docs/enterprise/10-money-and-ledger/05-booking-to-earnings.md b/docs/enterprise/10-money-and-ledger/05-booking-to-earnings.md
index 54981ec08..c04686692 100644
--- a/docs/enterprise/10-money-and-ledger/05-booking-to-earnings.md
+++ b/docs/enterprise/10-money-and-ledger/05-booking-to-earnings.md
@@ -61,6 +61,8 @@ Two scoping columns let a card live at the **org** level (default across contrac
**Time-scoped, never updated.** A rate change closes the old card (`effectiveTo = now()`) and inserts a new one (`effectiveFrom = now()`) in one transaction (`bumpRateCard()`, `lib/api/organizations/rate-card.ts`). Yesterday's booking still resolves the card where `effectiveFrom <= booking.createdAt < effectiveTo`.
+**One open window per scope, guarded twice (#1405).** The bump is a read-then-write: it looks for the currently effective card, closes it, and inserts the replacement. Under the default isolation level two administrators bumping the same scope at the same moment could each read "nothing is open here" and each insert a row with `effectiveTo = NULL`, after which `resolveEffectiveRateCard()` had two equally valid candidates and picked between them non-deterministically — two bookings a second apart could settle on different splits. `POST /api/organizations/{orgId}/rate-cards` now runs that transaction at the `Serializable` isolation level and wraps it in `withSerializableRetry()`, so the losing writer aborts and re-runs against the winner's state instead of surfacing a serialization error to the caller. Behind that, the partial unique index `rate_card_one_open_window` in `prisma/sql/check-constraints.sql` makes the invariant structural: it is declared `NULLS NOT DISTINCT` over the four scope columns, because three of them are nullable and Postgres would otherwise treat every NULL as distinct and exempt exactly the rows that need covering (an expression index over `COALESCE` was rejected: the enum-to-text cast is not immutable). A write that still collides comes back as HTTP 409 with the code `RATE_CARD_OPEN_WINDOW_CONFLICT`, which asks the caller to re-read the current card and retry rather than reporting a server fault.
+
**Resolution order** (`resolveEffectiveRateCard()`, most-specific → least):
1. `Membership.rateCardOverride` (per-expert).
@@ -72,7 +74,21 @@ Two scoping columns let a card live at the **org** level (default across contrac
7. Org-scoped default.
8. Hardcoded `DEFAULT_RATE_CARD` = **10% / 10% / 80%** (platform / org / expert); `rateCardId = null` is the sentinel for "defaults used".
-**Only tiers 1, 7 and 8 are reachable today.** `resolveOrgSplit()` (`lib/payments/payouts/earnings-service.ts`) is the resolver's only production caller, and it passes just `orgId`, `membershipOverrideId` and `at`. A settling booking can therefore land only on the per-expert override, the org-scoped default, or the hardcoded fallback, even though it has already resolved the plan that would select tiers 2 through 5. The rate-card POST handler will happily create a contract-scoped or `planId`-scoped card, so such a card can exist and never be chosen. Forwarding the booking's scope would change which card settles live money, so it is tracked as an open question under #1319 rather than treated as a documentation gap.
+**Which tiers a booking can reach depends on one flag.** `resolveOrgSplit()` (`lib/payments/payouts/earnings-service.ts`) is the resolver's only production caller, and until #1335 it passed just `orgId`, `membershipOverrideId` and `at`. A settling booking could therefore land only on tiers 1, 7 and 8 — the per-expert override, the org-scoped default, or the hardcoded fallback — even though it had already resolved the plan that selects tiers 2 through 5. The rate-card POST handler will happily create a contract-scoped or `planId`-scoped card, so such a card could exist and never be chosen.
+
+`RATE_CARD_SCOPED_RESOLUTION` closes that gap, and it is **off unless the value is exactly `on`**. The default is off because the flip changes which card settles live money: any scoped card an org created while the tiers were unreachable would begin paying a different split the moment it becomes selectable, so an org must be able to audit its cards first and flip second. The gate is `isScopedRateCardResolutionEnabled()` in `lib/api/organizations/rate-card.ts`; off, `resolveOrgSplit()` makes the pre-#1335 call verbatim.
+
+With the flag on, settlement forwards three more fields, all derived inside the same transaction that writes the earnings rows:
+
+| Field | Where it comes from | When it is null |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `planType` | The settlement's own `AppointmentType`, mapped through the exhaustive `RATE_CARD_PLAN_TYPE` record so an enum rename fails the build. | Never, on the primary leg. |
+| `planId` | The plan already resolved for the org-ownership lookup. | Consultation and subscription bookings, whose plan ids are not carried in the settlement payload. Those still resolve at `planType` granularity (tiers 4 and 5). |
+| `contractId` | `BookingUtilization` (unique on `paymentId`) → `ProgramAssignment` → `Program` → `Contract`, which is the only link a settling payment has to a contract. | Marketplace and self-funded bookings, which have no contract; subscription bookings, which meter utilization at slot-allocation time and so have none yet at settlement; and any contract that does not belong to the settling org. |
+
+That last exclusion is a tenancy guard rather than a nicety. A contract-scoped card is created under `POST /organizations/{orgId}/rate-cards`, which checks the contract against that org, so `ownerContractId` alone identifies the owner — and `resolveEffectiveRateCard()` matches `ownerContractId` without re-asserting the org. Since `Contract.organizationId` is the **sponsoring** org while `resolveOrgSplit()` resolves the expert's **host** org, forwarding the contract unguarded would let one tenant's booking settle on another tenant's negotiated split. Contract scope is therefore reachable only where the sponsor and the host are the same organization, which is the HYBRID case the tier was designed for.
+
+The collaborator leg passes no scope at all under either flag state. ADR 18 makes collaborations org-blind, so the seller's contract and plan must not select a card owned by the collaborator's own org.
**The bps invariant:** `platformBps + orgBps + consultantBps === 10000` on every row — enforced at the creation site (`bumpRateCard()` + the rate-card POST handler), not yet a Postgres CHECK (follow-up).
@@ -187,10 +203,19 @@ On a real over-cap checkout, `recordOverageAtCheckout` (`lib/payments/billing/ov
- **Circuit breaker.** `maxOveragePerCyclePaise` is a per-cycle overage ceiling. If `cycleOverageSoFarPaise + marginal` would breach it, the mapper returns `decision: BLOCK, chargeTo: null` **regardless of `overageBehavior`** — the recorder throws `PROGRAM_CAP_EXHAUSTED` (HTTP 402), the same shape as a `BLOCK`-behavior refusal but with a distinct code so the dashboard can say "cycle ceiling" vs "per-member allocation". An unknown/missing `overageBehavior` also **fails safe to `BLOCK`**.
- **`CHARGE_MEMBER`** → a parent-linked **PENDING side-`Payment`** for the marginal (gateway _not_ called inside the tx; the order is minted lazily when the member opens the resume-checkout surface) + an `OverageEvent(PENDING)`. To avoid double-collecting `basePaise`, checkout carves it out of the org-funded parent's `INVOICE_ACCRUAL` leg (fail-closed: a non-invoice-funded parent has no credit-back path yet, #715, so it aborts rather than double-charge). Member is notified (`notifyOrgProgramOverageDue`) with a pay deep link. The webhook later posts the `OVERAGE_MEMBER` org-relief leg ([§4.8 of ledger & postings](03-ledger-and-postings.md)).
-- **`CHARGE_ORG`** → carve `basePaise` out of the base `INVOICE_ACCRUAL` leg and write the marginal as a distinct **`OVERAGE_INVOICE_ACCRUAL`** leg (the distinct source dodges the `@@unique([paymentId, source])` clash) + an `OverageEvent(PENDING)`. The cycle-close rollup turns it into an `InvoiceLineItem` and walks the event `PENDING → ACCRUED → CHARGED` ([invoicing](08-invoicing.md)).
+- **`CHARGE_ORG` on the INVOICE rail** → carve `basePaise` out of the base `INVOICE_ACCRUAL` leg and write the marginal as a distinct **`OVERAGE_INVOICE_ACCRUAL`** leg (the distinct source dodges the `@@unique([paymentId, source])` clash) + an `OverageEvent(PENDING)`. The cycle-close rollup turns it into an `InvoiceLineItem` and walks the event `PENDING → ACCRUED → CHARGED` ([invoicing](08-invoicing.md)).
+- **`CHARGE_ORG` on the WALLET rail (#1458)** → nothing is billed, because the wallet debit taken when the booking committed is the whole nominal price and therefore already contains the over-cap pass-through. The recorder writes **no** leg and does **not** touch `Payment.amount`; it records an `OverageEvent` that is born `CHARGED` with `settledAt` stamped and `paymentId` pointing at the booking payment whose `WALLET` leg collected it. That event carries no `invoiceLineItemId`, so the reconciler's link invariant accepts either link as proof of collection. Anything else on this rail fails closed with a business error rather than inflating the payment: a positive `overageSurchargeBps` is a markup the wallet debit never took, and an org-sponsored payment carrying none of the `WALLET` / `INVOICE_ACCRUAL` / `LICENSE` funding legs means the funding seam itself has drifted.
+- **`CHARGE_ORG` on the LICENSE rail is refused (#1458).** A licence is a flat fee settled at contract time, so a licence-funded booking moves no money per booking: its funding leg is deliberately ₹0 while `Payment.amount` stays at the full price, and the leg-sum guard excuses that only while the licence leg is the payment's _only_ funding leg. Adding an overage leg re-arms the comparison, so `assert_payment_legs_ok` raised at COMMIT and the booking died with an opaque database error. There is no per-booking rail to collect the marginal on, so `overageBehaviorUnsupportedReason` refuses any charging behaviour on a licence-funded account and checkout keeps the fail-closed backstop.
+- **`CHARGE_MEMBER` is not available on a WALLET account (#715, guarded in #1458).** Collecting from the member requires carving the over-cap portion back out of the parent, which on the wallet rail would mean crediting the wallet mid-transaction — a path that has never been built. `overageBehaviorUnsupportedReason` (`lib/enterprise/reachable-paths.ts`) refuses the combination when the programme is created or patched, so an operator cannot save a configuration whose only outcome is a refused booking. Checkout keeps its fail-closed throw for programmes configured before that guard existed, now carrying the code `OVERAGE_CHARGE_MEMBER_UNSUPPORTED` and an HTTP 409.
The `chargeStatus` state machine itself is a single guarded transition (`transitionOverage`, `overage-transitions.ts`); the overage-event lifecycle table of states (`PENDING/ACCRUED/CHARGED/BLOCKED/REVERSED/FAILED`) is in [funding & programs](../00-foundations/03-funding-and-programs.md) / [programs](../30-programs-and-lifecycle/02-programs.md).
+Because a wallet-funded overage never adds to `Payment.amount`, a cancellation of such a booking refunds exactly what the wallet was debited. The refund cascade splits the refund across the payment's legs, and the single `WALLET` leg equals `Payment.amount`, so a full refund credits the wallet back to the balance it held before the booking. The same cascade reverses the `CHARGED` event, because the money it represented has just been returned and the programme's per-cycle ceiling has to be released with it.
+
+An overage also has to keep the booking journal balanced, and that is a tighter constraint than the leg-sum identity. Every credit in the BOOKING posting is derived from `Payment.originalAmount` plus `taxAmount` — the nominal price — while the debits are the funding legs plus a `DISCOUNT` plug clamped at zero or above. The posting therefore balances only while the funding legs sum to no more than the nominal gross. On the wallet rail that now holds by construction. On the invoice rail it does not: the base carve keeps `basePaise` inside the price, but `marginal = base + surcharge` raises both the accrual leg and `Payment.amount` by the surcharge, which is real funding sitting outside the nominal price. The posting therefore credits that surcharge to `PLATFORM_FEE`, because an over-cap surcharge is a markup the platform charges the organisation for exceeding its own cap and not consultant income — the consultant is paid out of `originalAmount`. Without that credit the posting was short by exactly `surchargePaise`, threw `LedgerImbalanceError`, and the booking committed with no journal entry at all (Sentry `FAMILIARISE_WEB-28`).
+
+The refusals checkout can raise from inside its transaction all carry a machine-readable code, and the catch around that transaction rethrows any error whose code is registered in `BUSINESS_ERROR_CODES` instead of rewriting it. `PROGRAM_CAP_EXHAUSTED` therefore reaches the buyer as the HTTP 402 it was thrown as, with a toast that names the admin action, rather than as the 500 "Something Went Wrong" it used to collapse into.
+
---
## 7. Design decisions & trade-offs
diff --git a/docs/enterprise/10-money-and-ledger/07-payout-pipeline.md b/docs/enterprise/10-money-and-ledger/07-payout-pipeline.md
index c4da6a0c7..5ec42f87f 100644
--- a/docs/enterprise/10-money-and-ledger/07-payout-pipeline.md
+++ b/docs/enterprise/10-money-and-ledger/07-payout-pipeline.md
@@ -61,12 +61,16 @@ Two details distinguish the org machine from the consultant machine. First, the
On `PROCESSING → COMPLETED`, `markOrgPayoutCompleted` posts the settlement (`idempotencyKey = orgpayout:`, `kind = ORG_PAYOUT`) inside the same transaction that flips the status, so a rolled-back transition cannot leave a half-posted ledger.
```
-Dr ORG_PAYABLE(org) net + TDS (clear what we owed the org)
- Cr CASH(platform) net paid
- Cr TDS_PAYABLE TDS withheld (only if > 0)
+Dr ORG_PAYABLE(org) netPayoutPaise (clear what we owed the org, pre-withholding)
+ Cr CASH(platform) amountPaise (what the rail actually transferred)
+ Cr TDS_PAYABLE tdsAmountPaise (withheld, only if > 0)
```
-The **consultant** payout is the mirror — `payout:`, `kind = PAYOUT`: `Dr CONSULTANT_PAYABLE / Cr CASH + TDS_PAYABLE` (`lib/payments/payouts/payout-service.ts`). On `FAILED` (and, on the consultant rail, `CANCELLED`), the linked earnings are released back to `READY` with their `orgPayoutId` / `payoutId` cleared, and provisional `TDSRecord` rows are deleted. The reconciler asserts `sum(orgShare − refunded) == netPayoutPaise` (`ORG_PAYOUT_TOTAL_MISMATCH`, [ledger integrity](13-ledger-integrity.md)).
+The two money columns on `OrganizationPayout` are easy to read the wrong way round, so the schema now says which is which in a `///` comment and the service asserts the relationship before it posts. `netPayoutPaise` is the host organisation's share net of platform fee and refunds, taken **before** withholding, and it is also the base `computeTdsForPayout` is given. `amountPaise` is that figure minus the withholding, which is the sum RazorpayX or Stripe Connect actually moves. The identity `amountPaise + tdsAmountPaise == netPayoutPaise` therefore has to hold for the three legs above to tie out, and `assertOrgPayoutWithholdingIdentity` checks it inside the CAS transaction. When it does not hold there is no correct posting available — any figure we chose would clear the payable or credit cash by an amount that never moved — so the service records a `SystemEvent`, reports to Sentry from outside the transaction (a global-client write while a `$transaction` holds the only pooled connection would deadlock under `PG_POOL_MAX=1`) and throws, which rolls the completion back for the at-least-once webhook or the stuck-payout sweep to re-drive.
+
+Until #1470 the posting debited `netPayoutPaise + TDS` and credited `CASH` at `netPayoutPaise`. That set balances, so the write-time check and the nightly imbalance finding both accepted it, but it cleared `ORG_PAYABLE` and credited `CASH` by exactly one TDS amount too much on every host-org payout, and `markOrgPayoutReversed` mirrored the same wrong shape so only a payout that stayed `COMPLETED` carried the overstatement. The same misreading also sat in the `TDSRecord` the completion files: `cumulativeAmountCredited` summed `netPayoutPaise + tdsAmountPaise` across the financial year, which counts the withholding twice, because `netPayoutPaise` is already the gross credited figure that Section 194-O asks for. Both are corrected, and the reversal is now the exact mirror of the corrected legs (`Dr CASH amountPaise`, `Dr TDS_PAYABLE tdsAmountPaise`, `Cr ORG_PAYABLE netPayoutPaise`) under the same assertion.
+
+The **consultant** payout is the mirror — `payout:`, `kind = PAYOUT`: `Dr CONSULTANT_PAYABLE / Cr CASH + TDS_PAYABLE` (`lib/payments/payouts/payout-service.ts`). On `FAILED` (and, on the consultant rail, `CANCELLED`), the linked earnings are released back to `READY` with their `orgPayoutId` / `payoutId` cleared, and provisional `TDSRecord` rows are deleted. The reconciler asserts `sum(orgShare − refunded) == netPayoutPaise` (`ORG_PAYOUT_TOTAL_MISMATCH`, [ledger integrity](13-ledger-integrity.md)), and it does so only for payouts in `PENDING`, `APPROVED`, `PROCESSING` or `COMPLETED`. A `FAILED`, `REVERSED` or `CANCELLED` payout has deliberately detached its earnings back to `READY` with `orgPayoutId` cleared, so it ends up with nothing attached against a retained `netPayoutPaise`; reporting that as drift was noise rather than a finding (#1471).
> 🔒 **`ENABLE_LIVE_PAYOUTS` is still off.** The whole pipeline runs — batching, TDS/MSME, the status machine, the ledger posting — but **gateway submission is held**, so org payouts sit at `PENDING` (surfaced in the UI as "pending platform enablement", never as a failure). The `ORG_PAYOUT` / `PAYOUT` ledger leg posts only on a real `PROCESSING → COMPLETED`, so no cash-leaving entry exists until go-live. See the [live-payout go-live runbook](../50-operations/06-live-payout-go-live-runbook.md).
@@ -80,17 +84,17 @@ Crucially, a payout that reaches `processed` is **not** guaranteed to be final.
The table below maps each gateway state onto our `PayoutStatus` as `mapPayoutStatus` and the reconcilers actually do it, and flags where the mapping is lossy or inconsistent. Note that `mapPayoutStatus` (the gateway-poll path) is separate from the `payout.reversed` **webhook** path: the webhook handlers now drive the dedicated `REVERSED` status (§3), but the poller's mapping below is unchanged.
-| RazorpayX state | Our `PayoutStatus` | Faithful? | Note |
-|---|---|---|---|
-| `queued` | `PROCESSING` (crons) / `PENDING` (`mapPayoutStatus`) | inconsistent | two code paths map it differently; we have no `QUEUED` state |
-| `pending` | `PENDING` (`mapPayoutStatus`) / `PROCESSING` (crons) | inconsistent | approval-workflow only; we do not use it |
-| `scheduled` | unmapped | gap | falls through to default; we never schedule |
-| `processing` | `PROCESSING` | yes | the normal in-flight state |
-| `processed` | `COMPLETED` | yes | event carries the UTR; persisted to `gatewayUtr` before the `COMPLETED` flip |
-| `reversed` | `FAILED` (poll path) / `REVERSED` (webhook path) | lossy in the poller only | `mapPayoutStatus` still collapses a polled `reversed` to `FAILED`; the `payout.reversed` webhook handler now stamps the dedicated `REVERSED` status and posts the inverse journal (§3, #812) |
-| `rejected` | `FAILED` | lossy | approval/deadline reject indistinguishable from bank failure |
-| `cancelled` | `CANCELLED` | yes | manual cancel of a queued/scheduled payout |
-| `failed` | `FAILED` | yes | Current-Account partner-bank rejection |
+| RazorpayX state | Our `PayoutStatus` | Faithful? | Note |
+| --------------- | ---------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `queued` | `PROCESSING` (crons) / `PENDING` (`mapPayoutStatus`) | inconsistent | two code paths map it differently; we have no `QUEUED` state |
+| `pending` | `PENDING` (`mapPayoutStatus`) / `PROCESSING` (crons) | inconsistent | approval-workflow only; we do not use it |
+| `scheduled` | unmapped | gap | falls through to default; we never schedule |
+| `processing` | `PROCESSING` | yes | the normal in-flight state |
+| `processed` | `COMPLETED` | yes | event carries the UTR; persisted to `gatewayUtr` before the `COMPLETED` flip |
+| `reversed` | `FAILED` (poll path) / `REVERSED` (webhook path) | lossy in the poller only | `mapPayoutStatus` still collapses a polled `reversed` to `FAILED`; the `payout.reversed` webhook handler now stamps the dedicated `REVERSED` status and posts the inverse journal (§3, #812) |
+| `rejected` | `FAILED` | lossy | approval/deadline reject indistinguishable from bank failure |
+| `cancelled` | `CANCELLED` | yes | manual cancel of a queued/scheduled payout |
+| `failed` | `FAILED` | yes | Current-Account partner-bank rejection |
The UTR (Unique Transaction Reference) is the bank-rail receipt a host org uses to trace funds with its bank. It is **null** while a payout is `processing` and only becomes available once the beneficiary bank confirms the credit — immediately for IMPS/UPI, within roughly ninety seconds for NEFT. Our pipeline extracts it from the `payout.processed` payload (the entity carries `utr` by then) and persists it to `gatewayUtr` before flipping the row to `COMPLETED`, so the notification and audit log always hold the canonical bank reference. IMPS and UPI payouts are near-instant (a typical lifecycle of about 180 seconds); if a payout is still `processing` after that window it is most likely in NPCI's "deemed success" state and may take up to **T+3** working days to resolve. NEFT and RTGS run only during bank working hours and not on the second and fourth Saturdays, Sundays, or RBI holidays. `determinePayoutMode` auto-selects the rail by amount and account type: UPI for a VPA fund account, IMPS for a bank transfer up to ₹5,00,000, and NEFT above that; RTGS (minimum ₹2,00,000) is available but not auto-selected.
@@ -149,6 +153,10 @@ TDS is computed by `computeTdsForPayout` (`lib/compliance/tds.ts`). The default
> **Refund-driven TDS reversal now wired via `TDSRecord` (#813), richer model still pending.** When a payout is refunded after TDS has been withheld and deposited, the deductor does not chase a cash refund in the ordinary case: under CBDT Circular 2/2011 (carried forward by the 2025 Act) excess TDS discovered within the same financial year is adjusted against the deductor's liability in a later quarter, surfacing as a reduced or negative line in the next quarterly statement (Form 140 / 144). The refund cascade now implements exactly this: `recordTdsReversal` (`lib/payments/tax/tds-service.ts`) writes a negative `isReversal` `TDSRecord` capped at the original withholding, copying the original's FY/quarter when it is unfiled and stamping the current IST-reckoned quarter when it is already filed (the adjust-against-future-liability convention). A correction return for an already-filed quarter, and an excess discovered after the financial year closes (which must route to the Form 26B refund claim), both remain manual operator actions. 🟡 **Still pending:** the richer `TdsAdjustment` model and the FVU export that would emit these as machine-generated negative lines; this policy is provisional pending CA sign-off.
+**Where the withholding becomes a filing row (#1354).** Until this change the org rail computed TDS, stamped it on `OrganizationPayout`, and stopped there, so a real statutory deduction never reached the quarterly return. `markOrgPayoutCompleted` now writes a `TDSRecord` on the org rail exactly as `reconcile-payout-status` does on the consultant rail, and it writes it at `COMPLETED` and nowhere else. That timing is the point: a batch that is built and then fails never withheld anything, so a record created at batch time would put money on the return that the government was never paid. The record is deleted and rewritten on each completion, because a payout can be `FAILED`, released back to `READY`, re-batched and completed again. `markOrgPayoutReversed` handles the mirror case: when a bank returns a completed payout, `recordOrgTdsReversal` writes a negative `TDSRecord` plus a `TdsAdjustment` that nets the withholding out of the quarter, capped against any reversal already booked so a redelivered webhook cannot reverse twice.
+
+Both rails share one `TDSRecord` table, and a row belongs to exactly one of them. `consultantProfileId` and `organizationId` are both nullable, and two CHECK constraints in `prisma/sql/check-constraints.sql` do the work that `NOT NULL` used to do: `tds_record_deductee_xor` requires exactly one deductee, and `tds_record_payout_rail_matches` stops a row on one rail from citing the other rail's payout. Each rail also carries its own unique key, because a single key spanning both would dedupe nothing — Postgres treats NULLs as distinct, so an org row whose consultant columns are all null never conflicts with itself.
+
Authoritative: `docs/compliance/01-tds-overview.md`.
### 4.2 MSME §15 payment window
@@ -159,7 +167,7 @@ The cost of missing the window is twofold. Commercially, MSMED §16 imposes **co
> 🟡 **Gap — deadline keys off invoice date, not acceptance (no issue filed yet).** MSMED §15 runs the clock from acceptance or deemed acceptance (deemed acceptance being delivery plus fifteen days absent a written objection), but `computeMsmePaymentDeadline` derives `mustPayByDate` from invoice date. For rendered consulting services the two effectively coincide, so invoice date is a defensible conservative proxy, but it is a proxy and not the statutory trigger.
-> 🟡 **Gap — §16 interest is neither documented nor accrued (no issue filed yet).** Nothing in the code models the §16 three-times-RBI-bank-rate monthly-compounding interest on a missed deadline; the cron only *alerts*. That is acceptable for v1 — the alert is meant to prevent the breach — but finance should understand that a missed `mustPayByDate` carries a real statutory interest cost we do not currently compute.
+> 🟡 **Gap — §16 interest is neither documented nor accrued (no issue filed yet).** Nothing in the code models the §16 three-times-RBI-bank-rate monthly-compounding interest on a missed deadline; the cron only _alerts_. That is acceptable for v1 — the alert is meant to prevent the breach — but finance should understand that a missed `mustPayByDate` carries a real statutory interest cost we do not currently compute.
> 🟥 **Divergence vs `docs/compliance/03-msme-43b-h.md`.** That doc states 43B(h) "carries forward unchanged into the Income-tax Act, 2025 … under equivalent clause numbering." The mechanics are unchanged, but the **clause number changed**: under the 2025 Act old §43B becomes **Section 37** and the MSME limb §43B(h) becomes **Section 37(2)(g)** ("any sum payable … to a micro or small enterprise beyond the time limit specified in section 15 of the MSMED Act, 2006"), with the ITR-due-date relief again expressly excluding that clause (corroborated by [TaxGuru's §37 explainer](https://taxguru.in/income-tax/section-37-income-tax-act-2025-earlier-section-43b-income-tax-act-1961.html)). The compliance doc's "equivalent clause numbering" phrasing is stale. (This doc does not edit docs/compliance.) The revised Udyam thresholds in force since 1 April 2025 (S.O. 1364(E)) are MICRO ≤ ₹2.5 cr investment / ≤ ₹10 cr turnover, SMALL ≤ ₹25 cr / ≤ ₹100 cr, and MEDIUM ≤ ₹125 cr / ≤ ₹500 cr, applied as a composite test; the disallowance reaches only MICRO and SMALL suppliers, which is why `computeMsmePaymentDeadline` routes MEDIUM and NONE to ordinary terms.
@@ -199,7 +207,7 @@ A note on the consultant rail, since this doc is host-side: the consultant pipel
## 7. Design decisions & trade-offs
-**Periodic batch with an `idempotencyKey` dedup, not a per-earning payout.** Each `READY` earning *could* fire its own transfer the moment its hold elapses, but that would mean N gateway calls, N TDS computations, and N rows per org per period — and TDS section logic wants the *aggregate* pool, not per-earning amounts. So the cron rolls a period's `READY` earnings into **one** `OrganizationPayout`, computes TDS once on the pool, and submits one transfer. The dedup is `OrganizationPayout.idempotencyKey @unique`: when two overlapping cron workers race the same period, the loser's insert hits `P2002` and the service falls through to return the winner's already-created row (`org-payout-service.ts`), so a retry or a replica cannot double-pay. The cost is up to a period of settlement latency; the benefit is one auditable payout per period and no N-way gateway fan-out.
+**Periodic batch with an `idempotencyKey` dedup, not a per-earning payout.** Each `READY` earning _could_ fire its own transfer the moment its hold elapses, but that would mean N gateway calls, N TDS computations, and N rows per org per period — and TDS section logic wants the _aggregate_ pool, not per-earning amounts. So the cron rolls a period's `READY` earnings into **one** `OrganizationPayout`, computes TDS once on the pool, and submits one transfer. The dedup is `OrganizationPayout.idempotencyKey @unique`: when two overlapping cron workers race the same period, the loser's insert hits `P2002` and the service falls through to return the winner's already-created row (`org-payout-service.ts`), so a retry or a replica cannot double-pay. The cost is up to a period of settlement latency; the benefit is one auditable payout per period and no N-way gateway fan-out.
**The flag freezes submission, not the pipeline.** With `ENABLE_LIVE_PAYOUTS` off, batching, TDS/MSME, the status machine, and the eventual ledger posting all run; only the gateway call is held, and the row is deliberately left at `PENDING` rather than claimed to `PROCESSING`. That keeps the whole path exercised in staging and seed data and makes go-live a flag flip rather than a code path that has never run. The cost is rows sitting at `PENDING` that an operator must read as "held," not "stuck" — hence the explicit "pending platform enablement" UI copy. The rejected alternative, short-circuiting the whole pipeline behind the flag, would mean the first real payout runs untested code.
@@ -209,13 +217,14 @@ The mock-Redis case is the sharper one, and it is why the check rejects mock out
### What this design survived
-**A false-FAILed payout the gateway had already accepted → double disbursement (`8a924d41`, #785 task #24).** The processing catch block marked a payout `PROCESSING → FAILED` and unlinked its earnings (back to `READY`) on *any* throw — including a DB write that threw *after* RazorpayX had already accepted the transfer. The released earnings would then re-batch under a **fresh `idempotencyKey` the gateway will not dedupe**, paying the same money twice. The fix hoists `providerPayoutId` above the `try` so the catch can tell a **pre-gateway** failure (no provider id yet — safe to FAIL and release) from a **post-gateway** one (provider id set — money already sent): the latter persists the gateway id, leaves the row `PROCESSING` with earnings *linked* (so the batcher's `payoutId: null` filter cannot re-batch them), and lets the stuck-payout handler reconcile it against the gateway. The flag was off, so no production money was double-paid — this was caught end-to-end before go-live.
+**A false-FAILed payout the gateway had already accepted → double disbursement (`8a924d41`, #785 task #24).** The processing catch block marked a payout `PROCESSING → FAILED` and unlinked its earnings (back to `READY`) on _any_ throw — including a DB write that threw _after_ RazorpayX had already accepted the transfer. The released earnings would then re-batch under a **fresh `idempotencyKey` the gateway will not dedupe**, paying the same money twice. The fix hoists `providerPayoutId` above the `try` so the catch can tell a **pre-gateway** failure (no provider id yet — safe to FAIL and release) from a **post-gateway** one (provider id set — money already sent): the latter persists the gateway id, leaves the row `PROCESSING` with earnings _linked_ (so the batcher's `payoutId: null` filter cannot re-batch them), and lets the stuck-payout handler reconcile it against the gateway. The flag was off, so no production money was double-paid — this was caught end-to-end before go-live.
-**TDS over-withholding 50× because the PAN was encrypted (`7f7e7d12`, #785).** Both payout services passed `OrganizationTaxInfo.panEncrypted` *ciphertext* straight into `computeTdsForPayout` as `panNumber`. The ciphertext failed `isValidPan`'s `[A-Z]{5}[0-9]{4}[A-Z]` regex, so the engine took the **194-O no-PAN fallback (5%)** instead of the with-PAN **0.1%** — withholding fifty times too much from every host-org payout that had a PAN safely on file. The fix added `panOnFile: boolean` to `TdsConsultantInput`: callers now pass `panNumber: null, panOnFile: !!taxInfo.panEncrypted`, so "a PAN exists" is signalled without trying to format-check ciphertext that cannot be validated until decrypt-at-filing-time. This is why §1.1's with-PAN figure is ₹40, not ₹2,000.
+**TDS over-withholding 50× because the PAN was encrypted (`7f7e7d12`, #785).** Both payout services passed `OrganizationTaxInfo.panEncrypted` _ciphertext_ straight into `computeTdsForPayout` as `panNumber`. The ciphertext failed `isValidPan`'s `[A-Z]{5}[0-9]{4}[A-Z]` regex, so the engine took the **194-O no-PAN fallback (5%)** instead of the with-PAN **0.1%** — withholding fifty times too much from every host-org payout that had a PAN safely on file. The fix added `panOnFile: boolean` to `TdsConsultantInput`: callers now pass `panNumber: null, panOnFile: !!taxInfo.panEncrypted`, so "a PAN exists" is signalled without trying to format-check ciphertext that cannot be validated until decrypt-at-filing-time. This is why §1.1's with-PAN figure is ₹40, not ₹2,000.
---
### Related docs
+
- [Earnings lifecycle](06-earnings-lifecycle.md) — the `EarningStatus` machine, holds, and refund decrements this pipeline consumes.
- [Booking → earnings](05-booking-to-earnings.md) — the rate-card bps snapshot that feeds the earnings row.
- [Ledger & postings](03-ledger-and-postings.md) — the `ORG_PAYOUT` / `PAYOUT` transactions in full.
diff --git a/docs/enterprise/10-money-and-ledger/08-invoicing.md b/docs/enterprise/10-money-and-ledger/08-invoicing.md
index 57d8db093..73869bcd5 100644
--- a/docs/enterprise/10-money-and-ledger/08-invoicing.md
+++ b/docs/enterprise/10-money-and-ledger/08-invoicing.md
@@ -265,6 +265,16 @@ The status-level invoice transition is the coarse view (`PAID → REFUNDED` for
---
+## 8b. Consumer invoices (B2C) — #1365
+
+Everything above concerns `OrganizationInvoice`, which is the document a sponsoring organization receives. A personal buyer paying by card receives a different document on a different series, and that path is documented separately in [B2C tax invoices and credit notes](../../payments/07-b2c-tax-invoice.md).
+
+The two families are deliberately separate models rather than one model with nullable columns. `OrganizationInvoice` requires an organization, a billing account and a due date, and those columns are load-bearing for dunning and for the IRP e-invoice payload; a consumer invoice has none of them, is paid before it is issued, and runs on one platform-wide gapless series instead of one series per organization. Collapsing them would make every one of those columns optional and would quietly weaken the B2B guarantees this page describes.
+
+What the two families share is the register. `jobs/compliance/gst-outward-register-export.ts` reads both invoice models and both credit-note models for a period and emits a single outward-supplies CSV for GSTR-1, stamping `gstr1ExportedAt` on the rows it reported so a re-run never re-stamps them.
+
+---
+
## 9. Overage roll-up into a line item (#715 / #775)
A `CHARGE_ORG` program overage isn't billed instantly — its marginal accrues as an `OVERAGE_INVOICE_ACCRUAL` `PaymentLeg` at checkout ([booking → earnings §6.3](05-booking-to-earnings.md)) and is **rolled into the cycle's invoice** alongside the base bookings. `rollupOrgInvoiceAccruals` (`lib/payments/billing/invoice-rollup.ts`, driven by `jobs/billing/settle-invoice-accruals.ts`) gathers each org's unbilled `SUCCEEDED` payments carrying **either** accrual source, sums **both** leg sources into the line `unitPricePaise` (the base + the overage), and emits one `InvoiceLineItem` per booking. The accrual read, invoice create, and stamp all run inside a single **Serializable** transaction (#813), so two overlapping rollup runs can no longer both issue an invoice for the same accrual set — the loser aborts with a P2034 serialization error, which the job treats as a benign skip. The monthly cadence and the workflow's `concurrency` group are the outer belt; the in-transaction read is the suspenders.
diff --git a/docs/enterprise/10-money-and-ledger/09-payment-legs.md b/docs/enterprise/10-money-and-ledger/09-payment-legs.md
index 663a48617..0af5c61b8 100644
--- a/docs/enterprise/10-money-and-ledger/09-payment-legs.md
+++ b/docs/enterprise/10-money-and-ledger/09-payment-legs.md
@@ -3,14 +3,14 @@ title: Payment legs & stackable funding
band: 10-money-and-ledger
audience: sde2
status: live
-last-reviewed: 2026-06-05
+last-reviewed: 2026-09-03
---
# Payment legs & stackable funding
**What this covers:** how one booking can be funded by several sources at once (`PaymentLeg`), and how each leg source maps to a **debit in the `BOOKING` ledger posting**. This is the funding side of [booking → earnings](05-booking-to-earnings.md).
-> A single checkout can stack funding: a wallet covers most of the price, a referral credit chips in, the learner's card picks up the rest. `PaymentLeg` models it — one `Payment`, N legs whose amounts sum to `Payment.amount`. Those same legs become the **debit side** of the booking journal transaction.
+> A single checkout can stack funding: a wallet covers most of the price, a referral credit chips in, the learner's card picks up the rest. `PaymentLeg` models it — one `Payment` and N legs, of which every funding leg except the platform-issued referral credit sums to `Payment.amount`. Those same legs become the **debit side** of the booking journal transaction.
---
@@ -83,7 +83,7 @@ flowchart LR
## 3. Invariants
-1. **Sum identity.** `sum(non-reversal PaymentLeg.amountPaise) === Payment.amount` (LICENSE is 0). Since #786 the funding legs are append-only: a refund never mutates the original leg, it nets through a negative `*_REVERSAL` sibling, so the original legs always still sum to `Payment.amount`. Each reversal leg must be negative and may never exceed its original sibling in magnitude. Enforced at checkout; the reconciler's `PAYMENT_LEG_SUM_MISMATCH` (now pair-aware, with a `FUNDING_SUM_DRIFT` vs `REVERSAL_PAIR_VIOLATION` reason) is the retroactive detector ([ledger integrity](13-ledger-integrity.md)).
+1. **Sum identity.** `sum(non-reversal, non-REFERRAL_CREDIT PaymentLeg.amountPaise) === Payment.amount` (LICENSE is 0 and stays in the sum). `Payment.amount` is the amount charged to the gateway, which the schema defines as the figure left after discounts and tax and **after** referral credits have been deducted. A `REFERRAL_CREDIT` leg therefore records value that has already been taken out of `amount`, and adding it back into the sum would demand the same credit twice, so it is excluded (#1347). The credit leg is still written, because it is the `PLATFORM_PROMO` debit in the booking journal (§2); it simply does not participate in the funding identity. A payment whose only funding legs are zero-value `LICENSE` legs is exempt from the comparison altogether, because the licence is absorbed at contract time and the leg is deliberately ₹0 while `Payment.amount` stays at the full list price, and the constraint trigger carries that same carve so it can never reject at `COMMIT` a checkout the checker waves through. That exemption removes the sum comparison and nothing else: both the checker and the trigger still apply the reversal-pair rules below to such a payment, because a reversal leg that exceeds the original it reverses is corrupt under either reading of the sum. Since #786 the funding legs are append-only: a refund never mutates the original leg, it nets through a negative `*_REVERSAL` sibling, so the original legs always still sum to `Payment.amount`. Each reversal leg must be negative and may never exceed its original sibling in magnitude. Enforced at checkout, and made uncommittable by the `payment_legs_sum_to_amount` constraint trigger in `prisma/sql/payment-legs-triggers.sql`; the reconciler's `PAYMENT_LEG_SUM_MISMATCH` (now pair-aware, with a `FUNDING_SUM_DRIFT` vs `REVERSAL_PAIR_VIOLATION` reason) is the retroactive detector ([ledger integrity](13-ledger-integrity.md)).
2. **Leg count ≥ 1.** A `SUCCEEDED` payment with zero legs is a data bug.
3. **Source uniqueness per payment.** `@@unique([paymentId, source])` — a duplicate-source leg fails on insert (`P2002`) rather than corrupting the sum. Reversal legs respect the same rule: there is at most one reversal sibling per source, and subsequent partial refunds net into it. If split-billing across sub-orgs becomes real, drop this and add a `legGroupId` (tracked follow-up).
4. **`sourceRef` for reversal.** Populated for `REFERRAL_CREDIT` (→ `ReferralCredit.id`) and where a gateway/accrual ref exists. `WALLET` legs no longer reference a per-row wallet log (`WalletEntry` was removed in #772) — the authoritative wallet movement is the booking journal's `Dr WALLET(org)` leg; the cache decrement is `walletDebit()`. `LICENSE`/`CARD` may omit `sourceRef`.
@@ -101,25 +101,27 @@ price: 500,000
- referral covers: 50,000 → PaymentLeg(REFERRAL_CREDIT, amountPaise=50000)
- card covers: 150,000 → PaymentLeg(CARD, amountPaise=150000)
-sum (excl. LICENSE=0): 200,000 == Payment.amount: 200,000
+Payment.amount (what the gateway is charged): 150,000
+funding sum (LICENSE 0 + CARD 150,000): 150,000 == Payment.amount
```
-The resulting booking posting debits `PLATFORM_PROMO` 50,000 + `CASH` 150,000 against the fee/payable/GST credits.
+`Payment.amount` is 150,000 rather than 200,000 because the ₹500 of referral credit was deducted before the order was minted, so the learner's card was only ever asked for the remaining ₹1,500. The `REFERRAL_CREDIT` leg still carries its 50,000, but the sum identity in §3 skips it, which is exactly what stops the credit being demanded a second time. The resulting booking posting debits `PLATFORM_PROMO` 50,000 + `CASH` 150,000 against the fee/payable/GST credits.
### 4.1 A wallet + referral + card stack
The canonical three-source stack the mental model opens with. A learner books a ₹3,000 (300,000 paise) session sponsored by a **WALLET-funded org** (`fundingSource = WALLET`) that has ₹2,000 of wallet balance left; the learner also holds ₹200 of referral credit; the card covers the rest. Checkout allocates **in priority order** — entitlement/wallet first, then platform credits, card last:
```
-price: 300,000
- - wallet covers: 200,000 → PaymentLeg(WALLET, amountPaise=200000)
- - referral covers: 20,000 → PaymentLeg(REFERRAL_CREDIT, amountPaise=20000)
- - card covers: 80,000 → PaymentLeg(CARD, amountPaise=80000)
+price: 300,000
+ - wallet covers: 200,000 → PaymentLeg(WALLET, amountPaise=200000)
+ - referral covers: 20,000 → PaymentLeg(REFERRAL_CREDIT, amountPaise=20000)
+ - card covers: 80,000 → PaymentLeg(CARD, amountPaise=80000)
-sum: 300,000 == Payment.amount: 300,000
+Payment.amount (post-credit): 280,000
+funding sum (WALLET 200,000 + CARD 80,000): 280,000 == Payment.amount
```
-The `walletDebit()` overdraft guard ([wallet & top-ups §4](04-wallet-and-topups.md)) atomically tests-and-decrements the ₹2,000 → ₹0 cache in the same tx the `WALLET` leg is written. The booking posting then debits `WALLET(org) 200,000` + `PLATFORM_PROMO 20,000` (the referral credit the platform eats) + `CASH 80,000`, balanced against the fee/payable/GST credits ([booking → earnings §3](05-booking-to-earnings.md#3-the-booking-posting)). Three sources, three legs, one `Payment` — and the journal's debit side is exactly those three legs summed by source ([ledger & postings §4.2](03-ledger-and-postings.md#42-booking--booking-bookingpaymentid)). Note `Payment.amount` here is the **full** 300,000 because none of these legs is excluded from it — unlike a pure referral-funded booking, where the credit is netted out of `amount` and the `DISCOUNT` plug picks up the gap (the trap behind the [booking → earnings §7 war story](05-booking-to-earnings.md#7-design-decisions--trade-offs)).
+The `walletDebit()` overdraft guard ([wallet & top-ups §4](04-wallet-and-topups.md)) atomically tests-and-decrements the ₹2,000 → ₹0 cache in the same tx the `WALLET` leg is written. The booking posting then debits `WALLET(org) 200,000` + `PLATFORM_PROMO 20,000` (the referral credit the platform eats) + `CASH 80,000`, balanced against the fee/payable/GST credits ([booking → earnings §3](05-booking-to-earnings.md#3-the-booking-posting)). Three sources, three legs, one `Payment` — and the journal's debit side is exactly those three legs summed by source ([ledger & postings §4.2](03-ledger-and-postings.md#42-booking--booking-bookingpaymentid)). Note that `Payment.amount` here is 280,000 and not the full 300,000, because the ₹200 of referral credit was netted out of it before the order was minted. That is the same asymmetry the `DISCOUNT` plug exists to absorb: the plug is computed from the sum of the funding-leg **debits**, which does include `PLATFORM_PROMO`, so the credit is counted exactly once on the journal side and zero times on the `Payment.amount` side (the trap behind the [booking → earnings §7 war story](05-booking-to-earnings.md#7-design-decisions--trade-offs)).
---
@@ -144,6 +146,8 @@ Refunds are a `Refund` row (not an inverse leg) plus a `REFUND` journal transact
- **The `CHARGE_ORG` overage that double-billed via an extra leg (`7f7e7d12`, #785 C3).** When an org-charged overage was recorded at checkout, the code **added** an `OVERAGE_INVOICE_ACCRUAL` leg for the marginal *on top of* the base `INVOICE_ACCRUAL` leg — but the base leg already covered the over-cap pass-through (`basePaise`). Because `rollupOrgInvoiceAccruals` sums **both** leg sources into the invoice ([invoicing §9](08-invoicing.md#9-overage-roll-up-into-a-line-item-715--775)), the org was billed `basePaise` **twice**, and `sum(PaymentLeg.amountPaise)` no longer equalled `Payment.amount` — tripping the reconciler's `PAYMENT_LEG_SUM_MISMATCH` ([ledger integrity](13-ledger-integrity.md)). The fix **carves** `basePaise` *out* of the base `INVOICE_ACCRUAL` leg and writes only the genuinely-additional surcharge as the overage leg, so the two legs sum to the price exactly. The symmetric `CHARGE_MEMBER` carve (so `basePaise` isn't collected on both the org's parent leg and the member's side-charge) shipped in the same commit — latent, since no `CHARGE_MEMBER` program is configured yet. This is the invariant in §3 rule 1 doing its job: the leg-sum identity is what made a silent double-bill a *loud* reconcile finding.
+- **The two definitions of `Payment.amount` that could not both be true (2026-09-03, #1347).** The schema has always described `Payment.amount` as the final amount charged to the gateway, taken after discounts and tax and **after** referral credits are deducted, and checkout writes a `CARD` leg equal to exactly that figure. The referral consumption helper then writes a positive `REFERRAL_CREDIT` leg for the credit it just applied, so the legs on a credit-funded booking added up to `amount` *plus* the credit. Rule 1 of §3, the checkout sweep, and the `payment_legs_sum_to_amount` constraint trigger all read the identity as a plain sum over every non-reversal leg, so the trigger — which is deferred to `COMMIT` and is live on the database — raised `check_violation` and rolled back the entire checkout transaction for any booking that spent referral credit. The two readings of `amount` were irreconcilable: either the field meant the pre-credit price, in which case the gateway was being asked for the wrong number, or the credit leg did not belong in the sum. The resolution keeps the field's long-standing meaning and narrows the identity instead, so the funding sum now excludes `REFERRAL_CREDIT` in the checker, in the trigger, and in this document. The credit leg is untouched and still posts as the `PLATFORM_PROMO` debit; the `DISCOUNT` plug in `earnings-service.ts` already based itself on the sum of funding-leg debits including `PLATFORM_PROMO`, so the journal side needed no change at all.
+
---
### Related docs
diff --git a/docs/enterprise/10-money-and-ledger/12-payment-webhooks.md b/docs/enterprise/10-money-and-ledger/12-payment-webhooks.md
index 0a6121990..b1f38568f 100644
--- a/docs/enterprise/10-money-and-ledger/12-payment-webhooks.md
+++ b/docs/enterprise/10-money-and-ledger/12-payment-webhooks.md
@@ -128,11 +128,25 @@ A `Payment` is created in `PENDING` when checkout creates the gateway order. A s
---
+## 4a. The gateway payment id, and why a refund used to need a network call
+
+Razorpay's `Payment.paymentIntent` column holds the **order** id (`order_…`), because that is what checkout creates and what the capture events name. Refund and dispute webhooks, however, identify their subject by the **payment** id (`pay_…`), and until #1353 nothing on our side stored one. The dispatcher therefore had to translate: for every `refund.*` event it called `payments.fetch(payment_id)` purely to read back the `order_id`. When that call failed — a gateway blip, an expired credential, a cold instance timing out — the dispatcher passed the `pay_…` id through unchanged, `handleRefundCreated` looked it up against `paymentIntent`, found nothing, and returned a `DeferSignal`. The event then sat unprocessed while the stuck-event sweeper re-drove it for up to seven days against a payment that had been captured all along.
+
+`Payment.gatewayPaymentId` closes that. The confirmation pipeline persists the `pay_…` id at capture, in the same Phase 1 update that flips the row to `SUCCEEDED` — ADR 21 already makes that the single writer of the payment's capture truth, and the gateway id is part of that truth, so no second writer is introduced. The column is unique, so two Payment rows can never claim the same gateway capture.
+
+Downstream, `handleRefundCreated` and `handleDisputeCreated` resolve their payment with one `findFirst` whose `OR` accepts **either** id, and the dispatcher now reads our own row first and calls `payments.fetch` only when the database has never seen that capture. The gateway call is a fallback for rows written before this change, not the only path. For disputes the benefit is larger still: a failed lookup used to mean the dispute could not be linked to a payment at all, which raised a `CRITICAL_DISPUTE_UNLINKED` page and left disputed earnings payable until the six-hourly reconcile cron noticed.
+
+## 4b. State-as-outbox for the post-capture legs
+
+Some of what a capture owes the buyer cannot happen inside the confirmation transaction. Creating their Stream chat channel is outbound network work, so it runs after the commit and is deliberately not awaited. That made it invisible when it failed: a crash or a Stream outage in that window left a confirmed, paid booking with no conversation, and the only trace was a Sentry event.
+
+Rather than introduce a queue table, the row that already records the work carries the completion stamp. `Appointment.chatChannelEnsuredAt` is written only once the channel calls have actually returned, which turns "confirmed, paid, and still `NULL`" into an exact query for the work that was lost. `reconcile-orphaned-confirmations` runs that query as its second pass and calls back into the same `ensureChannelsForAppointment` the live path uses. `WebhookEvent.deferCount` is the same idea one layer up: a deferral leaves the row looking exactly like a crash, so counting the deferrals is the only mark that path leaves behind, and it is what the sweeper alerts on. This is the pattern ADR 27 describes in full.
+
## 5. Monitoring and archival
Three concerns keep the inbound pipeline observable and bounded: replay of crashed events, archival of old rows, and alerting on verification failures.
-The **stuck-event sweeper** (`sweep-stuck-webhook-events`, §1) is the primary recovery mechanism — it re-drives `processed=false, error=null` events that an `after()` crash left behind, which would otherwise become the highest-blast-radius zombies (PAID money with an ISSUED invoice, uncredited top-ups, unpersisted chargebacks). The sweeper also drains the deliberate before-capture deferrals (a `refund.created`/`refund.processed` whose payment is not yet captured), giving each one up to a 7-day `giveUpAfterHours` window before it is terminally capped so an unknown payment cannot churn indefinitely (#813). Its sister, the **archive cron** (`archive-webhook-events`, weekly), deletes processed events older than 30 days and failed/errored events older than 90 days, keeping the table lean while retaining failures long enough to debug. **Alerting** rides on the row state: a handler error is stamped on `WebhookEvent.error` (surfaced by the sweeper's `stillFailing` count), and a signature-verification failure is recorded as a `WEBHOOK` warning via `recordSystemEvent`, since repeated HMAC failures indicate tampering or a secret misconfiguration. The org-relevant operator surfaces are absorbed from `docs/payments/webhooks/01-monitoring.md`.
+The **stuck-event sweeper** (`sweep-stuck-webhook-events`, §1) is the primary recovery mechanism — it re-drives `processed=false, error=null` events that an `after()` crash left behind, which would otherwise become the highest-blast-radius zombies (PAID money with an ISSUED invoice, uncredited top-ups, unpersisted chargebacks). The sweeper also drains the deliberate before-capture deferrals (a `refund.created`/`refund.processed` whose payment is not yet captured), giving each one up to a 7-day `giveUpAfterHours` window before it is terminally capped so an unknown payment cannot churn indefinitely (#813). Its sister, the **archive cron** (`archive-webhook-events`, weekly), deletes processed events older than 30 days and failed/errored events older than 90 days, keeping the table lean while retaining failures long enough to debug. **Alerting** rides on the row state: a handler error is stamped on `WebhookEvent.error` (surfaced by the sweeper's `stillFailing` count), and a signature-verification failure is recorded as a `WEBHOOK` warning via `recordSystemEvent`, since repeated HMAC failures indicate tampering or a secret misconfiguration. Since #1356 a deferral is alertable too. Each time a handler answers with a `DeferSignal` the dispatcher increments `WebhookEvent.deferCount`, and the sweeper raises one Sentry warning per run naming every event that has either deferred five times or been unprocessed for more than an hour. That closes the gap the seven-day give-up cap left: the cap is the point at which we abandon an event, not a point at which anybody is told about it. The org-relevant operator surfaces are absorbed from `docs/payments/webhooks/01-monitoring.md`.
---
diff --git a/docs/enterprise/10-money-and-ledger/13-ledger-integrity.md b/docs/enterprise/10-money-and-ledger/13-ledger-integrity.md
index a65995c82..e062d12a0 100644
--- a/docs/enterprise/10-money-and-ledger/13-ledger-integrity.md
+++ b/docs/enterprise/10-money-and-ledger/13-ledger-integrity.md
@@ -49,12 +49,13 @@ flowchart TD
| `OVERAGE_CHARGESTATUS_INTEGRITY` | per `OverageEvent` (link/state) | CHARGE_MEMBER pending/failed/charged ⇒ has a side-`Payment`; CHARGE_ORG accrued/charged ⇒ has an `InvoiceLineItem`; any `CHARGED` ⇒ `settledAt` set | the `transitionOverage` state machine was bypassed or a write half-completed |
| `LEDGER_ACCOUNT_NON_INR` | per `LedgerAccount` | `currency == INR` for every account (#783) | a posting keyed an INR-paise amount by a display currency — would break receivable/payable clearing |
| `ACTIVE_SEAT_COUNT_DRIFT` | per `BillingSubscription` | `activeSeatCount == count(in-period LICENSED_SEAT ACTIVE assignments)` | the per-seat invoice line-item counter missed a write (or reflects historical drift before its writer existed) |
-| `PAYMENT_LEG_SUM_MISMATCH` | per `Payment` with org legs | `sum(PaymentLeg.amountPaise) == Payment.amount` (LICENSE legs are 0) | a leg writer (checkout / wallet / referral / overage) emitted the wrong amount |
+| `PAYMENT_LEG_SUM_MISMATCH` | per `Payment` with org legs | `sum(non-reversal, non-REFERRAL_CREDIT PaymentLeg.amountPaise) == Payment.amount` (LICENSE legs are 0; the referral credit is already netted out of `amount`, #1347) | a leg writer (checkout / wallet / referral / overage) emitted the wrong amount |
| `INVOICE_TOTAL_MISMATCH` | per `OrganizationInvoice` | `totalPaise == subtotalPaise + CGST + SGST + IGST` | a mis-totaled GST invoice (filing defect); the issue-time assert in `invoice-rollup.ts` blocks new ones, this sweeps legacy/manual rows |
-| `ORG_PAYOUT_TOTAL_MISMATCH` | per `OrganizationPayout` | `sum(orgShare − refunded) of batched earnings == netPayoutPaise` | the batch claim updated earnings but the payout total diverged |
+| `ORG_PAYOUT_TOTAL_MISMATCH` | per `OrganizationPayout` in `PENDING` / `APPROVED` / `PROCESSING` / `COMPLETED` | `sum(orgShare − refunded) of batched earnings == netPayoutPaise` | the batch claim updated earnings but the payout total diverged. Terminal-with-release statuses (`FAILED`, `REVERSED`, `CANCELLED`) are skipped because they detach their earnings back to `READY` by design (#1471) |
| `LEDGER_TXN_IMBALANCE` | per `LedgerTransaction` (**full scope only**) | `Σdebit == Σcredit` | a manual SQL edit or a future writer bug broke a posting; **zero of these across a reseed is the gate** that justified removing the three legacy logs |
| `LEDGER_BALANCE_SNAPSHOT_DRIFT` | per `LedgerAccount` (**full scope only**) | maintained `LedgerAccountBalance` snapshot == journal `Σ(DEBIT)−Σ(CREDIT)` (#776) | the O(1) running-balance cache drifted, or an account with entries has no snapshot row (a posting bypassed `postLedgerTxn`) |
| `REFUND_BOOKING_COHERENCE` | per `BookingUtilization` (**full scope only**) | fully-refunded payment ⇒ utilization reversed; reversed utilization ⇒ a `SUCCEEDED` refund backs it (#776 §C) | a cap leak (money back but the seat still consumed) or a seat released for free |
+| `LEDGER_DUAL_WRITE_GAP` | per `OrganizationPayout` with `clawbackAmountPaise > 0` | a `clawback:*` `LedgerTransaction` exists against that payout (#1408) | the payout claims recovered cash the journal never saw: `reversePayoutClawback` posts the reversal best-effort inside a `try`/`catch`, and the two other writers of `clawbackAmountPaise` (`refund.ts`, `booking-refund.ts`) post nothing at all |
**Grouped by what each check protects** — the flat list above is alphabetical; this is the pipeline as a defender, from "is the journal itself sound" through "do the caches match" to "who gets paged":
diff --git a/docs/enterprise/30-programs-and-lifecycle/06-feature-flags-and-rollout.md b/docs/enterprise/30-programs-and-lifecycle/06-feature-flags-and-rollout.md
index 091973cb2..f160dfea9 100644
--- a/docs/enterprise/30-programs-and-lifecycle/06-feature-flags-and-rollout.md
+++ b/docs/enterprise/30-programs-and-lifecycle/06-feature-flags-and-rollout.md
@@ -16,19 +16,20 @@ Flags are read from `process.env` at module load, so setting one requires a rede
Six flags are exported from the module, and each one is the literal expression `process.env.X === "true"`, so an absent or empty value means off. The table below gives each flag's default, purpose, and the surfaces it dark-fails when off.
-| Flag | Default | Purpose | Gated surfaces when OFF |
-| ------------------------------ | ------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ENABLE_HOST_ORGS` | off | Hosting orgs (agencies hosting experts, 3-way split). | `POST /organizations` rejects `canHost=true` with 400 `HOST_ORGS_GATED`; `POST …/members` rejects `role=EXPERT`; the org-create wizard hides the host capability (server flag threaded to the wizard); the public org directory shows a "coming soon" state; the host routes stay gated; `/experts` + `/payouts` nav hidden; `earnings-service` takes the sponsor-only split. |
-| `ENABLE_LIVE_PAYOUTS` | off | Live payout **disbursement** gate (#776 §B). | The whole pipeline runs (batches, ledger, TDS, status machine) but gateway submission is held; org/consultant payouts sit `PROCESSING`, surfaced honestly as "pending platform enablement", **never** as a failure. Server-only — the home action-center + payout surfaces read it server-side and pass the boolean down. |
-| `ENABLE_DUNNING_SUSPEND` | off | Dunning cascade that suspends an org with an overdue invoice. | `lib/payments/operations/checkout.ts` skips the suspend gate, so an org with an overdue invoice keeps booking. Decide before self-serve tenants (#812/#779). |
-| `ENABLE_TDS_194O_GROSS` | off | Section 194-O withholding computed on the GROSS sale amount, with the three-limb ₹5,00,000 exemption. | The legacy base (consultant share net of platform commission) and the 194J ₹50,000 threshold stay in force. Flipping this changes real withholding, so it needs written CA sign-off first — see #1132. |
-| `TDS_ENGINE` | `LEGACY` | Withholding engine selector (`LEGACY` \| `194O`). Read inline at payout time; flipping to `194O` also requires `ENABLE_TDS_194O_GROSS` + CA sign-off (#738). | Non-module env gate read in `lib/payments/payouts/payout-service.ts`. |
-| `ENABLE_CONSOLIDATED_INVOICE` | off | Monthly invoice-accrual settlement cron (`settle-invoice-accruals`). | Absent means off — accrual rows accumulate until finance enables it. Documented here because it gates real money movement despite living outside `feature-flags.ts`. |
-| `DPDP_SWEEPER_DELETE` | absent | Consent-retention sweeper delete mode. | Absent = report-only. Intentional default; see required-secrets doc. |
+| Flag | Default | Purpose | Gated surfaces when OFF |
+| ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ENABLE_HOST_ORGS` | off | Hosting orgs (agencies hosting experts, 3-way split). | `POST /organizations` rejects `canHost=true` with 400 `HOST_ORGS_GATED`; `POST …/members` rejects `role=EXPERT`; the org-create wizard hides the host capability (server flag threaded to the wizard); the public org directory shows a "coming soon" state; the host routes stay gated; `/experts` + `/payouts` nav hidden; `earnings-service` takes the sponsor-only split. |
+| `ENABLE_LIVE_PAYOUTS` | off | Live payout **disbursement** gate (#776 §B). | The whole pipeline runs (batches, ledger, TDS, status machine) but gateway submission is held; org/consultant payouts sit `PROCESSING`, surfaced honestly as "pending platform enablement", **never** as a failure. Server-only — the home action-center + payout surfaces read it server-side and pass the boolean down. |
+| `ENABLE_DUNNING_SUSPEND` | off | Dunning cascade that suspends an org with an overdue invoice. | `lib/payments/operations/checkout.ts` skips the suspend gate, so an org with an overdue invoice keeps booking. Decide before self-serve tenants (#812/#779). |
+| `ENABLE_TDS_194O_GROSS` | off | Section 194-O withholding computed on the GROSS sale amount, with the three-limb ₹5,00,000 exemption. | The legacy base (consultant share net of platform commission) and the 194J ₹50,000 threshold stay in force. Flipping this changes real withholding, so it needs written CA sign-off first — see #1132. |
+| `TDS_ENGINE` | `LEGACY` | Withholding engine selector (`LEGACY` \| `194O`). Read inline at payout time; flipping to `194O` also requires `ENABLE_TDS_194O_GROSS` + CA sign-off (#738). | Non-module env gate read in `lib/payments/payouts/payout-service.ts`. |
+| `ENABLE_CONSOLIDATED_INVOICE` | off | Monthly invoice-accrual settlement cron (`settle-invoice-accruals`). | Absent means off — accrual rows accumulate until finance enables it. Documented here because it gates real money movement despite living outside `feature-flags.ts`. |
+| `DPDP_SWEEPER_DELETE` | absent | Consent-retention sweeper delete mode. | Absent = report-only. Intentional default; see required-secrets doc. |
+| `RATE_CARD_SCOPED_RESOLUTION` | off | Lets settlement forward the booking's contract and plan scope to the rate-card resolver (#1335). On only when the value is exactly `on`. | Off, `resolveOrgSplit()` passes org scope alone, so a contract- or plan-scoped `RateCard` can exist and never be selected — only the per-expert override, the org default and the hardcoded 10/10/80 are reachable. Read per call by `isScopedRateCardResolutionEnabled()` in `lib/api/organizations/rate-card.ts`; flipping it changes which card settles live money, so audit the org's existing scoped cards first. |
> **Other non-module gates** live in `.github/workflows/*.yml` (`ENABLE_IRP_UPLOADER`, `ENABLE_STRIPE_PAYOUTS`) and are tracked in `50-operations/07-required-secrets.md`.
-| `ENABLE_TDS_ADMIN_VIEW` | off | Admin TDS dashboard + Form 26Q filing surfaces. | `app/api/admin/tds/route.ts` returns 404 (hides from discovery). TDS data is still captured continuously by the payout pipeline; only the _filing workflow_ (mark-as-filed, decrypted-PAN view) is gated. |
-| `ENABLE_BETTERSTACK_TELEMETRY` | off | Better Stack Telemetry log sink for operational events (#776 §K). | `recordSystemEvent`/`recordSystemError` always write the `SystemEvent` table (source of truth); the flag (plus `BETTERSTACK_SOURCE_TOKEN` + `BETTERSTACK_INGEST_URL`) only adds the fire-and-forget side-channel that ships those events so a stuck payout / failed reconcile / HMAC failure can page someone. Never on the critical path. |
+> | `ENABLE_TDS_ADMIN_VIEW` | off | Admin TDS dashboard + Form 26Q filing surfaces. | `app/api/admin/tds/route.ts` returns 404 (hides from discovery). TDS data is still captured continuously by the payout pipeline; only the _filing workflow_ (mark-as-filed, decrypted-PAN view) is gated. |
+> | `ENABLE_BETTERSTACK_TELEMETRY` | off | Better Stack Telemetry log sink for operational events (#776 §K). | `recordSystemEvent`/`recordSystemError` always write the `SystemEvent` table (source of truth); the flag (plus `BETTERSTACK_SOURCE_TOKEN` + `BETTERSTACK_INGEST_URL`) only adds the fire-and-forget side-channel that ships those events so a stuck payout / failed reconcile / HMAC failure can page someone. Never on the critical path. |
`ENABLE_HOST_ORGS` is the broadest of the six — flipping it off doesn't just
hide a page, it changes the **split math** and dark-fails a whole capability.
diff --git a/docs/enterprise/50-operations/01-api-reference.md b/docs/enterprise/50-operations/01-api-reference.md
index 79363d002..64ddd2f1c 100644
--- a/docs/enterprise/50-operations/01-api-reference.md
+++ b/docs/enterprise/50-operations/01-api-reference.md
@@ -41,7 +41,7 @@ flowchart LR
```
> **How to read this table.** Each row is one `path × verb`.
-> **Min role** is the *floor* — `requireOrgAccess(orgId, minRole)` (or
+> **Min role** is the _floor_ — `requireOrgAccess(orgId, minRole)` (or
> `requireOrgOwner`) from `lib/auth-helpers.ts`; higher ranks and
> platform admins always pass. 🔒 rows gate on
> `requireOrgBillingAdminOrOwner` (`lib/auth/billing-admin-gate.ts`,
@@ -54,14 +54,14 @@ flowchart LR
> (`lib/enterprise/audit-actions.ts`).
Every enterprise-layer HTTP endpoint, exhaustively. Roles are the
-*minimum* required role — higher-rank roles and platform admins
+_minimum_ required role — higher-rank roles and platform admins
always pass. Audit actions are the string literals emitted by the
route on success; rows land in `OrgAuditLog` with the category shown
in parentheses. Constants live in `lib/enterprise/audit-actions.ts`.
> **Billing surfaces are governed by `requireOrgBillingAdminOrOwner`**
> (`lib/auth/billing-admin-gate.ts`) — an **OWNER ∨ BILLING_ADMIN**
-> disjunction. MAINTAINER is *deliberately excluded* from money
+> disjunction. MAINTAINER is _deliberately excluded_ from money
> surfaces even though it outranks BILLING_ADMIN on the org ladder.
> Rows gated this way are marked 🔒 **OWNER / BILLING_ADMIN** below.
@@ -73,156 +73,156 @@ the bottom._
These are the unscoped routes that operate above any single organization — the org switcher feed, org creation, the public directory, and invite acceptance.
-| Path | Verb | Min role | Purpose | Audit actions |
-|------|------|----------|---------|----------------|
-| `/api/organizations` | `GET` | authenticated | List the caller's orgs (switcher feed) | — |
-| `/api/organizations` | `POST` | authenticated | Create org + BillingAccount + OWNER Membership. Also upserts an `OrgWorkspaceProfile` for the creator (so they become "an operator of at least one org") and returns `orgWorkspaceProfileId` on the response. | `MEMBER_ADDED` (MEMBER) |
-| `/api/organizations/public` | `GET` | public | Public org directory (no session). Filtered to `isPublic = true`. | — |
+| Path | Verb | Min role | Purpose | Audit actions |
+| --------------------------------------- | ------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| `/api/organizations` | `GET` | authenticated | List the caller's orgs (switcher feed) | — |
+| `/api/organizations` | `POST` | authenticated | Create org + BillingAccount + OWNER Membership. Also upserts an `OrgWorkspaceProfile` for the creator (so they become "an operator of at least one org") and returns `orgWorkspaceProfileId` on the response. | `MEMBER_ADDED` (MEMBER) |
+| `/api/organizations/public` | `GET` | public | Public org directory (no session). Filtered to `isPublic = true`. | — |
| `/api/organizations/invitations/accept` | `POST` | authenticated | Accept an invite via token. Side-effects: LEARNER invites lazily upsert a `ConsulteeProfile` (via `ensureConsulteeProfile`); EXPERT invites upsert a placeholder `ConsultantProfile` (`Domain "General"`, `scheduleType = WEEKLY`, `verificationStatus = PENDING_VERIFICATION`) if the user doesn't already have one. | `INVITE_ACCEPTED` (MEMBER) |
## Org record
These routes read and mutate the organization record itself, including branding assets and the platform-admin verification state machine.
-| Path | Verb | Min role | Purpose | Audit actions |
-|------|------|----------|---------|----------------|
-| `/api/organizations/[orgId]` | `GET` | LEARNER | Full merged org record + capabilities + counts | — |
-| `/api/organizations/[orgId]` | `PATCH` | active member 🔓 **field-level RBAC** | Branding + policy + capability flips. The gate is `requireOrgAccess` (any active member) followed by a **field-level allowlist**: OWNER may touch every field; MAINTAINER is limited to `MAINTAINER_FIELDS` (name, description, industry, website, sizeBucket, logo, bannerImage, primaryColor, secondaryColor); BILLING_ADMIN is limited to `BILLING_ADMIN_FIELDS` (billingEmail, paymentTermsDays). Any out-of-remit field → `403 FIELD_RBAC_FORBIDDEN` naming the offending fields. Capability guard: can't disable both `canSponsor`/`canHost`; can't disable `canSponsor` while wallet balance > 0. | `SETTINGS_CHANGED` (SETTINGS) |
-| `/api/organizations/[orgId]` | `DELETE` | OWNER | Hard-delete (refused `409` if any contracts/invoices/POs/earnings exist — admins DEACTIVATE instead). No audit row: the org and its `OrgAuditLog` rows are deleted in the same tx, so there's nothing to write to. | — |
-| `/api/organizations/[orgId]/branding/[asset]` | `POST` | OWNER | Upload logo or banner image (multipart `file`; `asset` = `logo` \| `banner`) | `SETTINGS_CHANGED` (SETTINGS) |
-| `/api/organizations/[orgId]/branding/[asset]` | `DELETE` | OWNER | Remove logo or banner image (`asset` = `logo` \| `banner`) | `SETTINGS_CHANGED` (SETTINGS) |
-| `/api/organizations/[orgId]/settings` | `GET` | LEARNER | Thin settings projection | — |
-| `/api/admin/organizations/[orgId]/verify` | `POST` | platform ADMIN | One route handles `VERIFY / REJECT / SUSPEND / REACTIVATE / DEACTIVATE` (action upper-cased, defaults to `VERIFY`). `REJECT` requires a `reason` and keeps the org `PENDING_VERIFICATION` (stamps `verificationReason` + `verificationRejectedAt` for the resubmit loop). | `VERIFIED` / `VERIFICATION_REJECTED` / `SUSPENDED` / `REACTIVATED` / `DEACTIVATED` (SYSTEM) |
+| Path | Verb | Min role | Purpose | Audit actions |
+| --------------------------------------------- | -------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `/api/organizations/[orgId]` | `GET` | LEARNER | Full merged org record + capabilities + counts | — |
+| `/api/organizations/[orgId]` | `PATCH` | active member 🔓 **field-level RBAC** | Branding + policy + capability flips. The gate is `requireOrgAccess` (any active member) followed by a **field-level allowlist**: OWNER may touch every field; MAINTAINER is limited to `MAINTAINER_FIELDS` (name, description, industry, website, sizeBucket, logo, bannerImage, primaryColor, secondaryColor); BILLING_ADMIN is limited to `BILLING_ADMIN_FIELDS` (billingEmail, paymentTermsDays). Any out-of-remit field → `403 FIELD_RBAC_FORBIDDEN` naming the offending fields. Capability guard: can't disable both `canSponsor`/`canHost`; can't disable `canSponsor` while wallet balance > 0. | `SETTINGS_CHANGED` (SETTINGS) |
+| `/api/organizations/[orgId]` | `DELETE` | OWNER | Hard-delete (refused `409` if any contracts/invoices/POs/earnings exist — admins DEACTIVATE instead). No audit row: the org and its `OrgAuditLog` rows are deleted in the same tx, so there's nothing to write to. | — |
+| `/api/organizations/[orgId]/branding/[asset]` | `POST` | OWNER | Upload logo or banner image (multipart `file`; `asset` = `logo` \| `banner`) | `SETTINGS_CHANGED` (SETTINGS) |
+| `/api/organizations/[orgId]/branding/[asset]` | `DELETE` | OWNER | Remove logo or banner image (`asset` = `logo` \| `banner`) | `SETTINGS_CHANGED` (SETTINGS) |
+| `/api/organizations/[orgId]/settings` | `GET` | LEARNER | Thin settings projection | — |
+| `/api/admin/organizations/[orgId]/verify` | `POST` | platform ADMIN | One route handles `VERIFY / REJECT / SUSPEND / REACTIVATE / DEACTIVATE` (action upper-cased, defaults to `VERIFY`). `REJECT` requires a `reason` and keeps the org `PENDING_VERIFICATION` (stamps `verificationReason` + `verificationRejectedAt` for the resubmit loop). | `VERIFIED` / `VERIFICATION_REJECTED` / `SUSPENDED` / `REACTIVATED` / `DEACTIVATED` (SYSTEM) |
## Members and invitations
These routes manage membership records and the invitation lifecycle; the anti-lockout guard and the LEARNER↔EXPERT transition guard both live here.
-| Path | Verb | Min role | Purpose | Audit actions |
-|------|------|----------|---------|----------------|
-| `/api/organizations/[orgId]/members` | `GET` | active member | Paginated list; `?role=` / `?status=` / `?q=` | — |
-| `/api/organizations/[orgId]/members` | `POST` | MAINTAINER | Direct add (idempotent on userId). If the userId matches a `REMOVED` membership the row is reactivated, with the same `LEARNER ↔ EXPERT` transition guard applied (`409 ROLE_TRANSITION_BLOCKED` on violation). | `MEMBER_ADDED` / `MEMBER_REACTIVATED` (MEMBER) |
-| `/api/organizations/[orgId]/members/bulk` | `GET` `POST` `PUT` `PATCH` `DELETE` | — | **Deterministic `405` stub** (`BULK_REMOVAL_NOT_SUPPORTED`). Bulk member ops are intentionally unsupported in v1 so nothing bypasses the last-OWNER anti-lockout guard; use the single-member PATCH instead. See `deletion-policy`. | — |
-| `/api/organizations/[orgId]/members/[memberId]` | `GET` | active member | Full member record | — |
-| `/api/organizations/[orgId]/members/[memberId]` | `PATCH` | MAINTAINER | Role / status / departmentLabel / payoutRecipient. Returns `409 ROLE_TRANSITION_BLOCKED` if the caller tries to flip LEARNER ↔ EXPERT (`lib/enterprise/role-transitions.ts`); last-OWNER anti-lockout guard runs in a Serializable tx. | `ROLE_CHANGE` / `STATUS_CHANGE` (MEMBER) |
-| `/api/organizations/[orgId]/members/[memberId]` | `DELETE` | MAINTAINER | Set `status = REMOVED` | `MEMBER_REMOVED` (MEMBER) |
-| `/api/organizations/[orgId]/invitations` | `GET` | MAINTAINER | Pending + accepted + revoked invites | — |
-| `/api/organizations/[orgId]/invitations` | `POST` | MAINTAINER | Send (or resend) invite | `INVITE_SENT` / `INVITE_RESENT` (MEMBER) |
-| `/api/organizations/[orgId]/invitations/[invitationId]` | `GET` | MAINTAINER | Invite detail | — |
-| `/api/organizations/[orgId]/invitations/[invitationId]` | `DELETE` | MAINTAINER | Revoke | `INVITE_REVOKED` (MEMBER) |
+| Path | Verb | Min role | Purpose | Audit actions |
+| ------------------------------------------------------- | ----------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `/api/organizations/[orgId]/members` | `GET` | active member | Paginated list; `?role=` / `?status=` / `?q=` | — |
+| `/api/organizations/[orgId]/members` | `POST` | MAINTAINER | Direct add (idempotent on userId). If the userId matches a `REMOVED` membership the row is reactivated, with the same `LEARNER ↔ EXPERT` transition guard applied (`409 ROLE_TRANSITION_BLOCKED` on violation). | `MEMBER_ADDED` / `MEMBER_REACTIVATED` (MEMBER) |
+| `/api/organizations/[orgId]/members/bulk` | `GET` `POST` `PUT` `PATCH` `DELETE` | — | **Deterministic `405` stub** (`BULK_REMOVAL_NOT_SUPPORTED`). Bulk member ops are intentionally unsupported in v1 so nothing bypasses the last-OWNER anti-lockout guard; use the single-member PATCH instead. See `deletion-policy`. | — |
+| `/api/organizations/[orgId]/members/[memberId]` | `GET` | active member | Full member record | — |
+| `/api/organizations/[orgId]/members/[memberId]` | `PATCH` | MAINTAINER | Role / status / departmentLabel / payoutRecipient. Returns `409 ROLE_TRANSITION_BLOCKED` if the caller tries to flip LEARNER ↔ EXPERT (`lib/enterprise/role-transitions.ts`); last-OWNER anti-lockout guard runs in a Serializable tx. | `ROLE_CHANGE` / `STATUS_CHANGE` (MEMBER) |
+| `/api/organizations/[orgId]/members/[memberId]` | `DELETE` | MAINTAINER | Set `status = REMOVED` | `MEMBER_REMOVED` (MEMBER) |
+| `/api/organizations/[orgId]/invitations` | `GET` | MAINTAINER | Pending + accepted + revoked invites | — |
+| `/api/organizations/[orgId]/invitations` | `POST` | MAINTAINER | Send (or resend) invite | `INVITE_SENT` / `INVITE_RESENT` (MEMBER) |
+| `/api/organizations/[orgId]/invitations/[invitationId]` | `GET` | MAINTAINER | Invite detail | — |
+| `/api/organizations/[orgId]/invitations/[invitationId]` | `DELETE` | MAINTAINER | Revoke | `INVITE_REVOKED` (MEMBER) |
## Contracts
These routes cover the contract lifecycle — creation, term edits, the lock state that freezes terms once a contract is in use, and the supersede flow that replaces a contract immutably.
-| Path | Verb | Min role | Purpose | Audit actions |
-|------|------|----------|---------|----------------|
-| `/api/organizations/[orgId]/contracts` | `GET` | MAINTAINER | List with `?status=` filter | — |
-| `/api/organizations/[orgId]/contracts` | `POST` | OWNER | Create DRAFT/ACTIVE contract. May atomically mint a flat-fee `BillingSubscription` when the BillingAccount is `fundingSource=LICENSE` (`licenseFeePaise` + `licenseCycle`). `requireActive` — a contract can't bind an unverified org. | `CONTRACT_CREATED` (CONTRACT) |
-| `/api/organizations/[orgId]/contracts/[contractId]` | `GET` | MAINTAINER | Contract detail + programs; response carries a derived `locked` flag (term-field lock state). | — |
-| `/api/organizations/[orgId]/contracts/[contractId]` | `PATCH` | OWNER | Status transitions + terms. **Term fields** (`effectiveFrom`, `effectiveTo`, `paymentTermsDays`) lock once the contract is signed/billing (`getContractLockState`) → `409 CONTRACT_TERMS_LOCKED`; `autoRenew` stays editable. **`status=TERMINATED`** from ACTIVE is guarded: `409` while any live assignment is in its current cycle, or `409 CONTRACT_HAS_OUTSTANDING_INVOICES` while ISSUED/OVERDUE invoices exist; once allowed, an in-tx cascade flips programs ACTIVE→EXPIRED and their ACTIVE assignments→CLOSED. | `CONTRACT_SIGNED` / `CONTRACT_TERMINATED` / `CONTRACT_EXPIRED` (CONTRACT) |
-| `/api/organizations/[orgId]/contracts/[contractId]` | `DELETE` | OWNER | DRAFT-only hard delete (refused if programs attached) | `CONTRACT_TERMINATED` (CONTRACT) |
-| `/api/organizations/[orgId]/contracts/[contractId]/supersede` | `POST` | OWNER | #779 §A — contracts are immutable in use; supersede mints a successor with new terms, re-points programs, and retires the old row. `reason` accepts only `AMENDMENT` (cuts over now, old→TERMINATED) or `RENEWAL` (chains off old `effectiveTo`, old→EXPIRED). Invoices keep their old `contractId`; `supersededByContractId @unique` is the double-run backstop. `409` if the contract isn't ACTIVE or is already superseded. | `CONTRACT_SUPERSEDED` (CONTRACT) |
+| Path | Verb | Min role | Purpose | Audit actions |
+| ------------------------------------------------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
+| `/api/organizations/[orgId]/contracts` | `GET` | MAINTAINER | List with `?status=` filter | — |
+| `/api/organizations/[orgId]/contracts` | `POST` | OWNER | Create DRAFT/ACTIVE contract. May atomically mint a flat-fee `BillingSubscription` when the BillingAccount is `fundingSource=LICENSE` (`licenseFeePaise` + `licenseCycle`). `requireActive` — a contract can't bind an unverified org. | `CONTRACT_CREATED` (CONTRACT) |
+| `/api/organizations/[orgId]/contracts/[contractId]` | `GET` | MAINTAINER | Contract detail + programs; response carries a derived `locked` flag (term-field lock state). | — |
+| `/api/organizations/[orgId]/contracts/[contractId]` | `PATCH` | OWNER | Status transitions + terms. **Term fields** (`effectiveFrom`, `effectiveTo`, `paymentTermsDays`) lock once the contract is signed/billing (`getContractLockState`) → `409 CONTRACT_TERMS_LOCKED`; `autoRenew` stays editable. **`status=TERMINATED`** from ACTIVE is guarded: `409` while any live assignment is in its current cycle, or `409 CONTRACT_HAS_OUTSTANDING_INVOICES` while ISSUED/OVERDUE invoices exist; once allowed, an in-tx cascade flips programs ACTIVE→EXPIRED and their ACTIVE assignments→CLOSED. | `CONTRACT_SIGNED` / `CONTRACT_TERMINATED` / `CONTRACT_EXPIRED` (CONTRACT) |
+| `/api/organizations/[orgId]/contracts/[contractId]` | `DELETE` | OWNER | DRAFT-only hard delete (refused if programs attached) | `CONTRACT_TERMINATED` (CONTRACT) |
+| `/api/organizations/[orgId]/contracts/[contractId]/supersede` | `POST` | OWNER | #779 §A — contracts are immutable in use; supersede mints a successor with new terms, re-points programs, and retires the old row. `reason` accepts only `AMENDMENT` (cuts over now, old→TERMINATED) or `RENEWAL` (chains off old `effectiveTo`, old→EXPIRED). Invoices keep their old `contractId`; `supersededByContractId @unique` is the double-run backstop. `409` if the contract isn't ACTIVE or is already superseded. | `CONTRACT_SUPERSEDED` (CONTRACT) |
## Programs and assignments
These routes manage programs and their per-member assignments, including the money-config lock that freezes pricing fields once a program is live.
-| Path | Verb | Min role | Purpose | Audit actions |
-|------|------|----------|---------|----------------|
-| `/api/organizations/[orgId]/programs` | `GET` | active member | List programs for org (canSponsor) | — |
-| `/api/organizations/[orgId]/programs` | `POST` | MAINTAINER | Create LICENSED_SEAT or CREDIT_POOL program | `PROGRAM_CREATED` (PROGRAM) |
-| `/api/organizations/[orgId]/programs/[programId]` | `GET` | active member | Program detail; response carries a derived `locked` flag (money-config lock state). | — |
-| `/api/organizations/[orgId]/programs/[programId]` | `PATCH` | MAINTAINER | Safe-field edits (`name`, `status`, `allowedCategories`) always allowed. **Money fields** (`coveredPlanTypes`, `ratePerSeatPaise`, `coveredEngagementsPerCycle`, `creditBudgetPerCycle`, `overageBehavior`, `overageSurchargeBps`, `priceCapPerEngagementPaise`, `maxOveragePerCyclePaise`) freeze once the program is in use (`getProgramLockState`) → `409 PROGRAM_CONFIG_LOCKED`. **`archived=true`** stamps `archivedAt`, guarded `409 PROGRAM_HAS_ACTIVE_ASSIGNMENTS` if live allocations exist. | `PROGRAM_PAUSED` / `PROGRAM_ARCHIVED` (PROGRAM) |
-| `/api/organizations/[orgId]/programs/[programId]` | `DELETE` | MAINTAINER | DRAFT/no-assignment hard delete (Serializable; refused if assignments or historical utilizations exist) | `PROGRAM_DELETED` (PROGRAM) |
-| `/api/organizations/[orgId]/programs/[programId]/assignments` | `GET` | active member | List assignments | — |
-| `/api/organizations/[orgId]/programs/[programId]/assignments` | `POST` | MAINTAINER | Upsert assignment for a membership | `PROGRAM_ASSIGNED` (PROGRAM) |
-| `/api/organizations/[orgId]/programs/[programId]/assignments/[assignmentId]` | `GET` | active member | Assignment detail + utilizations | — |
-| `/api/organizations/[orgId]/programs/[programId]/assignments/[assignmentId]` | `PATCH` | MAINTAINER | Period / engagementsUsed reconciliation; `status` flip emits unassign | `PROGRAM_ASSIGNMENT_UPDATED` / `PROGRAM_UNASSIGNED` (PROGRAM) |
-| `/api/organizations/[orgId]/programs/[programId]/assignments/[assignmentId]` | `DELETE` | MAINTAINER | Remove assignment | `PROGRAM_UNASSIGNED` (PROGRAM) |
+| Path | Verb | Min role | Purpose | Audit actions |
+| ---------------------------------------------------------------------------- | -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `/api/organizations/[orgId]/programs` | `GET` | active member | List programs for org (canSponsor) | — |
+| `/api/organizations/[orgId]/programs` | `POST` | MAINTAINER | Create LICENSED_SEAT or CREDIT_POOL program | `PROGRAM_CREATED` (PROGRAM) |
+| `/api/organizations/[orgId]/programs/[programId]` | `GET` | active member | Program detail; response carries a derived `locked` flag (money-config lock state). | — |
+| `/api/organizations/[orgId]/programs/[programId]` | `PATCH` | MAINTAINER | Safe-field edits (`name`, `status`, `allowedCategories`) always allowed. **Money fields** (`coveredPlanTypes`, `ratePerSeatPaise`, `coveredEngagementsPerCycle`, `creditBudgetPerCycle`, `overageBehavior`, `overageSurchargeBps`, `priceCapPerEngagementPaise`, `maxOveragePerCyclePaise`) freeze once the program is in use (`getProgramLockState`) → `409 PROGRAM_CONFIG_LOCKED`. **`archived=true`** stamps `archivedAt`, guarded `409 PROGRAM_HAS_ACTIVE_ASSIGNMENTS` if live allocations exist. | `PROGRAM_PAUSED` / `PROGRAM_ARCHIVED` (PROGRAM) |
+| `/api/organizations/[orgId]/programs/[programId]` | `DELETE` | MAINTAINER | DRAFT/no-assignment hard delete (Serializable; refused if assignments or historical utilizations exist) | `PROGRAM_DELETED` (PROGRAM) |
+| `/api/organizations/[orgId]/programs/[programId]/assignments` | `GET` | active member | List assignments | — |
+| `/api/organizations/[orgId]/programs/[programId]/assignments` | `POST` | MAINTAINER | Upsert assignment for a membership | `PROGRAM_ASSIGNED` (PROGRAM) |
+| `/api/organizations/[orgId]/programs/[programId]/assignments/[assignmentId]` | `GET` | active member | Assignment detail + utilizations | — |
+| `/api/organizations/[orgId]/programs/[programId]/assignments/[assignmentId]` | `PATCH` | MAINTAINER | Period / engagementsUsed reconciliation; `status` flip emits unassign | `PROGRAM_ASSIGNMENT_UPDATED` / `PROGRAM_UNASSIGNED` (PROGRAM) |
+| `/api/organizations/[orgId]/programs/[programId]/assignments/[assignmentId]` | `DELETE` | MAINTAINER | Remove assignment | `PROGRAM_UNASSIGNED` (PROGRAM) |
## Billing account
These routes expose the billing account, wallet balance, and top-up flow; the money-mutating ones gate on `requireOrgBillingAdminOrOwner` and are marked 🔒.
-| Path | Verb | Min role | Purpose | Audit actions |
-|------|------|----------|---------|----------------|
-| `/api/organizations/[orgId]/billing` | `GET` | MANAGER | Aggregated billing snapshot for the unified Billing dashboard (month-to-date gross, outstanding, pending charges, paymentTermsDays). DB-side `aggregate({ _sum })`, O(1). | — |
-| `/api/organizations/[orgId]/billing-account` | `GET` | MANAGER | Account summary + balance + creditLimit | — |
-| `/api/organizations/[orgId]/billing-account` | `PATCH` | 🔒 OWNER / BILLING_ADMIN | Change billingEmail / fundingSource (guarded) | `SETTINGS_CHANGED` (SETTINGS) |
-| `/api/organizations/[orgId]/billing-account/wallet` | `GET` | MANAGER | Wallet balance + history (the org's WALLET-account `LedgerEntry` rows) | — |
-| `/api/organizations/[orgId]/billing-account/wallet/top-ups` | `GET` | MANAGER | List top-ups (pending + confirmed) | — |
-| `/api/organizations/[orgId]/billing-account/wallet/top-ups` | `POST` | 🔒 OWNER / BILLING_ADMIN | Mint Razorpay order + a PENDING `WalletTopUp` (keyed by `providerOrderId @unique`); the webhook (`notes.type=wallet_topup`) confirms it idempotently and posts the `TOPUP` txn (`Dr CASH / Cr WALLET`) | `WALLET_TOPUP` (WALLET) — `WALLET_TOPUP_CONFIRMED` is emitted by the webhook |
-| `/api/organizations/[orgId]/billing-account/wallet/top-ups/[topUpId]` | `GET` | MANAGER | Top-up detail; `topUpId` is the `WalletTopUp` id | — |
+| Path | Verb | Min role | Purpose | Audit actions |
+| --------------------------------------------------------------------- | ------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| `/api/organizations/[orgId]/billing` | `GET` | MANAGER | Aggregated billing snapshot for the unified Billing dashboard (month-to-date gross, outstanding, pending charges, paymentTermsDays). DB-side `aggregate({ _sum })`, O(1). | — |
+| `/api/organizations/[orgId]/billing-account` | `GET` | MANAGER | Account summary + balance + creditLimit | — |
+| `/api/organizations/[orgId]/billing-account` | `PATCH` | 🔒 OWNER / BILLING_ADMIN | Change billingEmail / fundingSource (guarded) | `SETTINGS_CHANGED` (SETTINGS) |
+| `/api/organizations/[orgId]/billing-account/wallet` | `GET` | MANAGER | Wallet balance + history (the org's WALLET-account `LedgerEntry` rows) | — |
+| `/api/organizations/[orgId]/billing-account/wallet/top-ups` | `GET` | MANAGER | List top-ups (pending + confirmed) | — |
+| `/api/organizations/[orgId]/billing-account/wallet/top-ups` | `POST` | 🔒 OWNER / BILLING_ADMIN | Mint Razorpay order + a PENDING `WalletTopUp` (keyed by `providerOrderId @unique`); the webhook (`notes.type=wallet_topup`) confirms it idempotently and posts the `TOPUP` txn (`Dr CASH / Cr WALLET`) | `WALLET_TOPUP` (WALLET) — `WALLET_TOPUP_CONFIRMED` is emitted by the webhook |
+| `/api/organizations/[orgId]/billing-account/wallet/top-ups/[topUpId]` | `GET` | MANAGER | Top-up detail; `topUpId` is the `WalletTopUp` id | — |
## Invoices and purchase orders
These routes cover manual invoices, invoice-payment initiation, PDF rendering, and purchase orders; the webhook completes the ISSUED→PAID flip out of band.
-| Path | Verb | Min role | Purpose | Audit actions |
-|------|------|----------|---------|----------------|
-| `/api/organizations/[orgId]/billing-account/invoices` | `GET` | MANAGER | List with `?status=` filter | — |
-| `/api/organizations/[orgId]/billing-account/invoices` | `POST` | 🔒 OWNER / BILLING_ADMIN | Manual invoice. Dashboard composer defaults `dueDate` to NET-60 and posts `issueImmediately: true` so the row lands as `ISSUED` in a single call. | `INVOICE_GENERATED` (INVOICE) |
-| `/api/organizations/[orgId]/billing-account/invoices/[invoiceId]` | `GET` | MANAGER | Invoice detail | — |
-| `/api/organizations/[orgId]/billing-account/invoices/[invoiceId]` | `PATCH` | 🔒 OWNER / BILLING_ADMIN | Status transitions (DRAFT→ISSUED, DRAFT→CANCELLED, ISSUED/OVERDUE→VOID) | `INVOICE_ISSUED` / `INVOICE_CANCELLED` / `INVOICE_VOIDED` (INVOICE) |
-| `/api/organizations/[orgId]/billing-account/invoices/[invoiceId]/pay` | `POST` | 🔒 OWNER / BILLING_ADMIN | Mint Razorpay order for the invoice; the webhook (`notes.type=invoice_payment`) flips ISSUED→PAID and posts the `INVOICE_PAID` txn (`Dr CASH / Cr ORG_RECEIVABLE`) | `INVOICE_PAYMENT_INITIATED` (INVOICE) — `INVOICE_PAID` is emitted by the webhook |
-| `/api/organizations/[orgId]/billing-account/invoices/[invoiceId]/pdf` | `GET` | MANAGER | Rendered invoice PDF | — |
-| `/api/organizations/[orgId]/billing-account/purchase-orders` | `GET` | MANAGER | List POs | — |
-| `/api/organizations/[orgId]/billing-account/purchase-orders` | `POST` | 🔒 OWNER / BILLING_ADMIN | Create PO | `PURCHASE_ORDER_CREATED` (INVOICE) |
-| `/api/organizations/[orgId]/billing-account/purchase-orders/[poId]` | `GET` | MANAGER | PO detail + linked invoices | — |
-| `/api/organizations/[orgId]/billing-account/purchase-orders/[poId]` | `PATCH` | 🔒 OWNER / BILLING_ADMIN | Update PO metadata | — |
-| `/api/organizations/[orgId]/billing-account/purchase-orders/[poId]` | `DELETE` | 🔒 OWNER / BILLING_ADMIN | Cancel PO (if unused) | — |
+| Path | Verb | Min role | Purpose | Audit actions |
+| --------------------------------------------------------------------- | -------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| `/api/organizations/[orgId]/billing-account/invoices` | `GET` | MANAGER | List with `?status=` filter | — |
+| `/api/organizations/[orgId]/billing-account/invoices` | `POST` | 🔒 OWNER / BILLING_ADMIN | Manual invoice. Dashboard composer defaults `dueDate` to NET-60 and posts `issueImmediately: true` so the row lands as `ISSUED` in a single call. | `INVOICE_GENERATED` (INVOICE) |
+| `/api/organizations/[orgId]/billing-account/invoices/[invoiceId]` | `GET` | MANAGER | Invoice detail | — |
+| `/api/organizations/[orgId]/billing-account/invoices/[invoiceId]` | `PATCH` | 🔒 OWNER / BILLING_ADMIN | Status transitions (DRAFT→ISSUED, DRAFT→CANCELLED, ISSUED/OVERDUE→VOID) | `INVOICE_ISSUED` / `INVOICE_CANCELLED` / `INVOICE_VOIDED` (INVOICE) |
+| `/api/organizations/[orgId]/billing-account/invoices/[invoiceId]/pay` | `POST` | 🔒 OWNER / BILLING_ADMIN | Mint Razorpay order for the invoice; the webhook (`notes.type=invoice_payment`) flips ISSUED→PAID and posts the `INVOICE_PAID` txn (`Dr CASH / Cr ORG_RECEIVABLE`) | `INVOICE_PAYMENT_INITIATED` (INVOICE) — `INVOICE_PAID` is emitted by the webhook |
+| `/api/organizations/[orgId]/billing-account/invoices/[invoiceId]/pdf` | `GET` | MANAGER | Rendered invoice PDF | — |
+| `/api/organizations/[orgId]/billing-account/purchase-orders` | `GET` | MANAGER | List POs | — |
+| `/api/organizations/[orgId]/billing-account/purchase-orders` | `POST` | 🔒 OWNER / BILLING_ADMIN | Create PO | `PURCHASE_ORDER_CREATED` (INVOICE) |
+| `/api/organizations/[orgId]/billing-account/purchase-orders/[poId]` | `GET` | MANAGER | PO detail + linked invoices | — |
+| `/api/organizations/[orgId]/billing-account/purchase-orders/[poId]` | `PATCH` | 🔒 OWNER / BILLING_ADMIN | Update PO metadata | — |
+| `/api/organizations/[orgId]/billing-account/purchase-orders/[poId]` | `DELETE` | 🔒 OWNER / BILLING_ADMIN | Cancel PO (if unused) | — |
## Rate cards, earnings, payouts (host side)
These are the host-side money routes for organizations that earn — rate cards, the payout account, and the earnings-to-payout rollup; most mutations gate on `requireOrgBillingAdminOrOwner`.
-| Path | Verb | Min role | Purpose | Audit actions |
-|------|------|----------|---------|----------------|
-| `/api/organizations/[orgId]/rate-cards` | `GET` | active member (canHost) | Effective cards + history. Read widened from MANAGER so an EXPERT can confirm their commission split. | — |
-| `/api/organizations/[orgId]/rate-cards` | `POST` | 🔒 OWNER / BILLING_ADMIN (canHost) | Create / bump a card (atomic two-step) | `RATE_CARD_BUMPED` (PROGRAM) |
-| `/api/organizations/[orgId]/rate-cards/[cardId]` | `GET` | MANAGER (canHost) | Card detail | — |
-| `/api/organizations/[orgId]/rate-cards/[cardId]` | `PATCH` | 🔒 OWNER / BILLING_ADMIN (canHost) | Close (set `effectiveTo`) | `RATE_CARD_BUMPED` (PROGRAM) |
-| `/api/organizations/[orgId]/payout-account` | `GET` | MANAGER | Account summary + last4 | — |
-| `/api/organizations/[orgId]/payout-account` | `PUT` | OWNER | Replace account (encrypted at rest) | `SETTINGS_CHANGED` (SETTINGS) |
-| `/api/organizations/[orgId]/earnings` | `GET` | MANAGER | List OrganizationEarnings rows | — |
-| `/api/organizations/[orgId]/payouts` | `GET` | MANAGER | List OrganizationPayouts | — |
-| `/api/organizations/[orgId]/payouts` | `POST` | 🔒 OWNER / BILLING_ADMIN | Roll up earnings → PayoutCycle | `PAYOUT_INITIATED` (PAYOUT) |
-| `/api/organizations/[orgId]/payouts/[payoutId]` | `GET` | MANAGER | Payout detail + earnings list | — |
-| `/api/organizations/[orgId]/payouts/[payoutId]` | `PATCH` | 🔒 OWNER / BILLING_ADMIN | Flip to PROCESSED / CANCELLED | `PAYOUT_INITIATED` / `PAYOUT_CANCELLED` (PAYOUT) |
+| Path | Verb | Min role | Purpose | Audit actions |
+| ------------------------------------------------ | ------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `/api/organizations/[orgId]/rate-cards` | `GET` | active member (canHost) | Effective cards + history. Read widened from MANAGER so an EXPERT can confirm their commission split. | — |
+| `/api/organizations/[orgId]/rate-cards` | `POST` | 🔒 OWNER / BILLING_ADMIN (canHost) | Create / bump a card (atomic two-step). A card scoped to a `contractId`, `planType` or `planId` is only selected at settlement when `RATE_CARD_SCOPED_RESOLUTION=on` (#1335). With the flag off, settlement forwards only the org id, the membership override and the payment time: a valid membership override wins, then the org default card, and with neither the built-in default (10% platform, 10% org, 80% consultant) applies. | `RATE_CARD_BUMPED` (PROGRAM) |
+| `/api/organizations/[orgId]/rate-cards/[cardId]` | `GET` | MANAGER (canHost) | Card detail | — |
+| `/api/organizations/[orgId]/rate-cards/[cardId]` | `PATCH` | 🔒 OWNER / BILLING_ADMIN (canHost) | Close (set `effectiveTo`) | `RATE_CARD_BUMPED` (PROGRAM) |
+| `/api/organizations/[orgId]/payout-account` | `GET` | MANAGER | Account summary + last4 | — |
+| `/api/organizations/[orgId]/payout-account` | `PUT` | OWNER | Replace account (encrypted at rest) | `SETTINGS_CHANGED` (SETTINGS) |
+| `/api/organizations/[orgId]/earnings` | `GET` | MANAGER | List OrganizationEarnings rows | — |
+| `/api/organizations/[orgId]/payouts` | `GET` | MANAGER | List OrganizationPayouts | — |
+| `/api/organizations/[orgId]/payouts` | `POST` | 🔒 OWNER / BILLING_ADMIN | Roll up earnings → PayoutCycle | `PAYOUT_INITIATED` (PAYOUT) |
+| `/api/organizations/[orgId]/payouts/[payoutId]` | `GET` | MANAGER | Payout detail + earnings list | — |
+| `/api/organizations/[orgId]/payouts/[payoutId]` | `PATCH` | 🔒 OWNER / BILLING_ADMIN | Flip to PROCESSED / CANCELLED | `PAYOUT_INITIATED` / `PAYOUT_CANCELLED` (PAYOUT) |
## Reimbursements, disputes, documents (read surfaces)
These are read-only roster endpoints — reimbursements, disputes, documents, trials, appointments, and recordings — all gated at MANAGER and none of them emit audit rows.
-| Path | Verb | Min role | Purpose | Audit actions |
-|------|------|----------|---------|----------------|
-| `/api/organizations/[orgId]/reimbursements` | `GET` | MANAGER | Reimbursement roster | — |
-| `/api/organizations/[orgId]/reimbursements/export` | `GET` | MANAGER | CSV export of reimbursements | — |
-| `/api/organizations/[orgId]/disputes` | `GET` | MANAGER | Dispute roster (org-scoped) | — |
-| `/api/organizations/[orgId]/documents` | `GET` | MANAGER | Org document list | — |
-| `/api/organizations/[orgId]/trials` | `GET` | MANAGER | Trial roster | — |
-| `/api/organizations/[orgId]/appointments` | `GET` | MANAGER | Org appointment feed | — |
-| `/api/organizations/[orgId]/recordings` | `GET` | MANAGER | Stream recording roster | — |
+| Path | Verb | Min role | Purpose | Audit actions |
+| -------------------------------------------------- | ----- | -------- | ---------------------------- | ------------- |
+| `/api/organizations/[orgId]/reimbursements` | `GET` | MANAGER | Reimbursement roster | — |
+| `/api/organizations/[orgId]/reimbursements/export` | `GET` | MANAGER | CSV export of reimbursements | — |
+| `/api/organizations/[orgId]/disputes` | `GET` | MANAGER | Dispute roster (org-scoped) | — |
+| `/api/organizations/[orgId]/documents` | `GET` | MANAGER | Org document list | — |
+| `/api/organizations/[orgId]/trials` | `GET` | MANAGER | Trial roster | — |
+| `/api/organizations/[orgId]/appointments` | `GET` | MANAGER | Org appointment feed | — |
+| `/api/organizations/[orgId]/recordings` | `GET` | MANAGER | Stream recording roster | — |
## SSO and domains
These routes configure SSO providers, the break-glass escape hatch, and domain claims; the OWNER-only gates reflect that these are IdP-trust roots.
-| Path | Verb | Min role | Purpose | Audit actions |
-|------|------|----------|---------|----------------|
-| `/api/organizations/[orgId]/sso` | `GET` | MANAGER | Settings read | — |
-| `/api/organizations/[orgId]/sso` | `PATCH` | OWNER | allowedEmailDomains / enforceSSO / defaultRoleForAutoJoin | `SSO_ENABLED` / `SSO_DISABLED` / `SETTINGS_CHANGED` (SETTINGS) |
-| `/api/organizations/[orgId]/sso/providers` | `GET` | MANAGER | List providers | — |
-| `/api/organizations/[orgId]/sso/providers` | `POST` | OWNER | Add SAML/OIDC provider | `SSO_ENABLED` (SETTINGS) |
-| `/api/organizations/[orgId]/sso/providers/[providerId]` | `GET` | MANAGER | Provider detail. Response includes a derived `providerType` of `SAML` or `OIDC`, inferred from whether `samlConfig` or `oidcConfig` is populated on the row. | — |
-| `/api/organizations/[orgId]/sso/providers/[providerId]` | `DELETE` | OWNER | Remove provider | `SSO_DISABLED` (SETTINGS) |
-| `/api/organizations/[orgId]/sso/break-glass` | `POST` | OWNER | #779 §E — open a time-boxed IdP-outage escape hatch (password login re-allowed while `breakGlassUntil > now`). `hours` 1–72 (default 4), `reason` required (min 5 chars). `404` if SSO isn't enforced. Who/why lives in the audit row, not on columns. | `SETTINGS_CHANGED` (SETTINGS) |
-| `/api/organizations/[orgId]/sso/break-glass` | `DELETE` | OWNER | Close the window early (clears `breakGlassUntil`). `404` if SSO isn't enforced. | `SETTINGS_CHANGED` (SETTINGS) |
-| `/api/organizations/[orgId]/domain-claims` | `GET` | MANAGER | List claims | — |
-| `/api/organizations/[orgId]/domain-claims` | `POST` | OWNER | Claim domain | `DOMAIN_CLAIMED` (SETTINGS) |
-| `/api/organizations/[orgId]/domain-claims/[domain]` | `DELETE` | OWNER | Release claim | `DOMAIN_RELEASED` (SETTINGS) |
-| `/api/organizations/[orgId]/domain-claims/[domain]/verify` | `POST` | OWNER | Verify the DNS TXT record at `_familiarise-verify.` matches the claim's `verificationToken`; flips `verifiedAt` NULL→now() and unlocks domain-based SSO auto-join. | `DOMAIN_VERIFIED` (SETTINGS) |
+| Path | Verb | Min role | Purpose | Audit actions |
+| ---------------------------------------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
+| `/api/organizations/[orgId]/sso` | `GET` | MANAGER | Settings read | — |
+| `/api/organizations/[orgId]/sso` | `PATCH` | OWNER | allowedEmailDomains / enforceSSO / defaultRoleForAutoJoin | `SSO_ENABLED` / `SSO_DISABLED` / `SETTINGS_CHANGED` (SETTINGS) |
+| `/api/organizations/[orgId]/sso/providers` | `GET` | MANAGER | List providers | — |
+| `/api/organizations/[orgId]/sso/providers` | `POST` | OWNER | Add SAML/OIDC provider | `SSO_ENABLED` (SETTINGS) |
+| `/api/organizations/[orgId]/sso/providers/[providerId]` | `GET` | MANAGER | Provider detail. Response includes a derived `providerType` of `SAML` or `OIDC`, inferred from whether `samlConfig` or `oidcConfig` is populated on the row. | — |
+| `/api/organizations/[orgId]/sso/providers/[providerId]` | `DELETE` | OWNER | Remove provider | `SSO_DISABLED` (SETTINGS) |
+| `/api/organizations/[orgId]/sso/break-glass` | `POST` | OWNER | #779 §E — open a time-boxed IdP-outage escape hatch (password login re-allowed while `breakGlassUntil > now`). `hours` 1–72 (default 4), `reason` required (min 5 chars). `404` if SSO isn't enforced. Who/why lives in the audit row, not on columns. | `SETTINGS_CHANGED` (SETTINGS) |
+| `/api/organizations/[orgId]/sso/break-glass` | `DELETE` | OWNER | Close the window early (clears `breakGlassUntil`). `404` if SSO isn't enforced. | `SETTINGS_CHANGED` (SETTINGS) |
+| `/api/organizations/[orgId]/domain-claims` | `GET` | MANAGER | List claims | — |
+| `/api/organizations/[orgId]/domain-claims` | `POST` | OWNER | Claim domain | `DOMAIN_CLAIMED` (SETTINGS) |
+| `/api/organizations/[orgId]/domain-claims/[domain]` | `DELETE` | OWNER | Release claim | `DOMAIN_RELEASED` (SETTINGS) |
+| `/api/organizations/[orgId]/domain-claims/[domain]/verify` | `POST` | OWNER | Verify the DNS TXT record at `_familiarise-verify.` matches the claim's `verificationToken`; flips `verifiedAt` NULL→now() and unlocks domain-based SSO auto-join. | `DOMAIN_VERIFIED` (SETTINGS) |
## SCIM provisioning
@@ -230,14 +230,14 @@ SCIM **runtime** (the IdP-facing `/scim/v2/...` push surface) lives outside
this table; these are the org-admin **configuration** routes. All are
OWNER-only — provisioning tokens and group mappings are IdP-trust roots.
-| Path | Verb | Min role | Purpose | Audit actions |
-|------|------|----------|---------|----------------|
-| `/api/organizations/[orgId]/scim/tokens` | `GET` | OWNER | List provisioning tokens (secrets masked) | — |
-| `/api/organizations/[orgId]/scim/tokens` | `POST` | OWNER | Mint a SCIM bearer token (returned once) | `SCIM_TOKEN_CREATED` (SYSTEM) |
-| `/api/organizations/[orgId]/scim/tokens/[tokenId]` | `DELETE` | OWNER | Revoke a token | `SCIM_TOKEN_REVOKED` (SYSTEM) |
-| `/api/organizations/[orgId]/scim/group-mappings` | `GET` | OWNER | List IdP-group → role mappings | — |
-| `/api/organizations/[orgId]/scim/group-mappings` | `POST` | OWNER | Map an IdP group to a `MemberRole` | `SCIM_GROUP_MAPPED` (SYSTEM) |
-| `/api/organizations/[orgId]/scim/group-mappings/[mappingId]` | `DELETE` | OWNER | Remove a group mapping | `SCIM_GROUP_UNMAPPED` (SYSTEM) |
+| Path | Verb | Min role | Purpose | Audit actions |
+| ------------------------------------------------------------ | -------- | -------- | ----------------------------------------- | ------------------------------ |
+| `/api/organizations/[orgId]/scim/tokens` | `GET` | OWNER | List provisioning tokens (secrets masked) | — |
+| `/api/organizations/[orgId]/scim/tokens` | `POST` | OWNER | Mint a SCIM bearer token (returned once) | `SCIM_TOKEN_CREATED` (SYSTEM) |
+| `/api/organizations/[orgId]/scim/tokens/[tokenId]` | `DELETE` | OWNER | Revoke a token | `SCIM_TOKEN_REVOKED` (SYSTEM) |
+| `/api/organizations/[orgId]/scim/group-mappings` | `GET` | OWNER | List IdP-group → role mappings | — |
+| `/api/organizations/[orgId]/scim/group-mappings` | `POST` | OWNER | Map an IdP group to a `MemberRole` | `SCIM_GROUP_MAPPED` (SYSTEM) |
+| `/api/organizations/[orgId]/scim/group-mappings/[mappingId]` | `DELETE` | OWNER | Remove a group mapping | `SCIM_GROUP_UNMAPPED` (SYSTEM) |
## Outbound webhooks
@@ -245,51 +245,51 @@ OWNER-only — provisioning tokens and group mappings are IdP-trust roots.
**secret rotation and endpoint deletion are OWNER-only** (highest-trust
operations from the integrator's POV). Read surfaces are MANAGER.
-| Path | Verb | Min role | Purpose | Audit actions |
-|------|------|----------|---------|----------------|
-| `/api/organizations/[orgId]/webhooks` | `GET` | MANAGER | List endpoints | — |
-| `/api/organizations/[orgId]/webhooks` | `POST` | 🔒 OWNER / BILLING_ADMIN | Create endpoint (returns secret once) | `WEBHOOK_ENDPOINT_CREATED` (WEBHOOK) |
-| `/api/organizations/[orgId]/webhooks/[endpointId]` | `GET` | MANAGER | Endpoint detail | — |
-| `/api/organizations/[orgId]/webhooks/[endpointId]` | `PATCH` | 🔒 OWNER / BILLING_ADMIN | Update / pause / resume | `WEBHOOK_ENDPOINT_PAUSED` / `WEBHOOK_ENDPOINT_RESUMED` / `WEBHOOK_ENDPOINT_UPDATED` (WEBHOOK) |
-| `/api/organizations/[orgId]/webhooks/[endpointId]` | `DELETE` | OWNER | Remove endpoint | `WEBHOOK_ENDPOINT_DELETED` (WEBHOOK) |
-| `/api/organizations/[orgId]/webhooks/[endpointId]/rotate-secret` | `POST` | OWNER | Mint a fresh 32-byte secret (returned once); stashes the prior secret + stamps `secretRotatedAt` so the worker dual-signs for a 24h grace window. Rate-limited (`orgWebhookLimiter`). BILLING_ADMIN can pause/disable but **not** rotate. | `WEBHOOK_SECRET_ROTATED` (WEBHOOK) |
-| `/api/organizations/[orgId]/webhooks/[endpointId]/deliveries` | `GET` | MANAGER | Delivery attempt history | — |
-| `/api/organizations/[orgId]/webhooks/[endpointId]/deliveries/[deliveryId]/redeliver` | `POST` | 🔒 OWNER / BILLING_ADMIN | Re-enqueue a single delivery | `WEBHOOK_DELIVERY_REDELIVERED` (WEBHOOK) |
+| Path | Verb | Min role | Purpose | Audit actions |
+| ------------------------------------------------------------------------------------ | -------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `/api/organizations/[orgId]/webhooks` | `GET` | MANAGER | List endpoints | — |
+| `/api/organizations/[orgId]/webhooks` | `POST` | 🔒 OWNER / BILLING_ADMIN | Create endpoint (returns secret once) | `WEBHOOK_ENDPOINT_CREATED` (WEBHOOK) |
+| `/api/organizations/[orgId]/webhooks/[endpointId]` | `GET` | MANAGER | Endpoint detail | — |
+| `/api/organizations/[orgId]/webhooks/[endpointId]` | `PATCH` | 🔒 OWNER / BILLING_ADMIN | Update / pause / resume | `WEBHOOK_ENDPOINT_PAUSED` / `WEBHOOK_ENDPOINT_RESUMED` / `WEBHOOK_ENDPOINT_UPDATED` (WEBHOOK) |
+| `/api/organizations/[orgId]/webhooks/[endpointId]` | `DELETE` | OWNER | Remove endpoint | `WEBHOOK_ENDPOINT_DELETED` (WEBHOOK) |
+| `/api/organizations/[orgId]/webhooks/[endpointId]/rotate-secret` | `POST` | OWNER | Mint a fresh 32-byte secret (returned once); stashes the prior secret + stamps `secretRotatedAt` so the worker dual-signs for a 24h grace window. Rate-limited (`orgWebhookLimiter`). BILLING_ADMIN can pause/disable but **not** rotate. | `WEBHOOK_SECRET_ROTATED` (WEBHOOK) |
+| `/api/organizations/[orgId]/webhooks/[endpointId]/deliveries` | `GET` | MANAGER | Delivery attempt history | — |
+| `/api/organizations/[orgId]/webhooks/[endpointId]/deliveries/[deliveryId]/redeliver` | `POST` | 🔒 OWNER / BILLING_ADMIN | Re-enqueue a single delivery | `WEBHOOK_DELIVERY_REDELIVERED` (WEBHOOK) |
## Compliance: verification, consent, data exports
Routes in this group implement DPDP §11 (data access bundles), §12 (consent grant/withdrawal), and the self-serve verification resubmit loop; the minimum role column reflects that financial PII in export bundles demands the same governance floor as billing mutations.
-| Path | Verb | Min role | Purpose | Audit actions |
-|------|------|----------|---------|----------------|
-| `/api/organizations/[orgId]/verification/resubmit` | `POST` | MAINTAINER | #779 §A — self-serve resubmit after an admin REJECT. Bumps `verificationSubmittedAt`, clears `verificationReason` + `verificationRejectedAt`. `409 NOTHING_TO_RESUBMIT` unless the org is `PENDING_VERIFICATION` with a non-null rejection stamp. | `VERIFICATION_RESUBMITTED` (SYSTEM) |
-| `/api/organizations/[orgId]/consent` | `GET` | MANAGER | ConsentArtifact roster (org-scoped via member relation); `?userId=` / `?active=` / `?limit=` | — |
-| `/api/organizations/[orgId]/consent` | `POST` | MANAGER | Record a grant. `userId` is validated as a non-empty string (1–128 chars) because `User.id` is a `cuid()`, not a UUID. Writes a SHA-256-hashed `ConsentArtifact`. | `CONSENT_GRANTED` (CONSENT) |
-| `/api/organizations/[orgId]/consent` | `DELETE` | MANAGER | Withdraw (DPDP §12) — stamps `withdrawnAt` on the user's active artifacts. `?userId=` required; `?purposeCode=` scopes the withdrawal (omit to withdraw all). Withdrawal is irreversible; a re-grant is a fresh artifact. | `CONSENT_WITHDRAWN` (CONSENT) |
-| `/api/organizations/[orgId]/data-exports` | `GET` | 🔒 OWNER / BILLING_ADMIN | List export jobs (last 30 days). Rows are `OrgDataExportJob`. | — |
-| `/api/organizations/[orgId]/data-exports` | `POST` | 🔒 OWNER / BILLING_ADMIN | Request a DPDP §11 export bundle (async worker). **Rate-limited 1/24h** (`orgDataExportLimiter`); bundles carry financial PII, hence the billing-governance floor. Returns `202`. | `DATA_EXPORT_REQUESTED` (SYSTEM) |
-| `/api/organizations/[orgId]/data-exports/[exportId]/download` | `GET` | 🔒 OWNER / BILLING_ADMIN | Signed-URL download when `status=READY` and unexpired. `409 EXPORT_NOT_READY`, `410 EXPORT_EXPIRED`. | `DATA_EXPORT_DOWNLOADED` (SYSTEM) |
+| Path | Verb | Min role | Purpose | Audit actions |
+| ------------------------------------------------------------- | -------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `/api/organizations/[orgId]/verification/resubmit` | `POST` | MAINTAINER | #779 §A — self-serve resubmit after an admin REJECT. Bumps `verificationSubmittedAt`, clears `verificationReason` + `verificationRejectedAt`. `409 NOTHING_TO_RESUBMIT` unless the org is `PENDING_VERIFICATION` with a non-null rejection stamp. | `VERIFICATION_RESUBMITTED` (SYSTEM) |
+| `/api/organizations/[orgId]/consent` | `GET` | MANAGER | ConsentArtifact roster (org-scoped via member relation); `?userId=` / `?active=` / `?limit=` | — |
+| `/api/organizations/[orgId]/consent` | `POST` | MANAGER | Record a grant. `userId` is validated as a non-empty string (1–128 chars) because `User.id` is a `cuid()`, not a UUID. Writes a SHA-256-hashed `ConsentArtifact`. | `CONSENT_GRANTED` (CONSENT) |
+| `/api/organizations/[orgId]/consent` | `DELETE` | MANAGER | Withdraw (DPDP §12) — stamps `withdrawnAt` on the user's active artifacts. `?userId=` required; `?purposeCode=` scopes the withdrawal (omit to withdraw all). Withdrawal is irreversible; a re-grant is a fresh artifact. | `CONSENT_WITHDRAWN` (CONSENT) |
+| `/api/organizations/[orgId]/data-exports` | `GET` | 🔒 OWNER / BILLING_ADMIN | List export jobs (last 30 days). Rows are `OrgDataExportJob`. | — |
+| `/api/organizations/[orgId]/data-exports` | `POST` | 🔒 OWNER / BILLING_ADMIN | Request a DPDP §11 export bundle (async worker). **Rate-limited 1/24h** (`orgDataExportLimiter`); bundles carry financial PII, hence the billing-governance floor. Returns `202`. | `DATA_EXPORT_REQUESTED` (SYSTEM) |
+| `/api/organizations/[orgId]/data-exports/[exportId]/download` | `GET` | 🔒 OWNER / BILLING_ADMIN | Signed-URL download when `status=READY` and unexpired. `409 EXPORT_NOT_READY`, `410 EXPORT_EXPIRED`. | `DATA_EXPORT_DOWNLOADED` (SYSTEM) |
## Checkout, analytics, activity, audit
These routes cover the advisory overage preview, analytics rollups, and the two audit-log read surfaces (the narrower `/activity` feed and the wider `/audit` read plus its auditable CSV export).
-| Path | Verb | Min role | Purpose | Audit actions |
-|------|------|----------|---------|----------------|
-| `/api/organizations/[orgId]/checkout/overage-preview` | `GET` | active member | #777 §C — advisory pre-checkout overage preview ("will booking this plan breach my cap, and what does it cost?"). Price is read **server-side** from the plan list price (`?planType=` / `?planId=` / `?sessions=`); a safe over-estimate vs the authoritative checkout charge. | — |
-| `/api/organizations/[orgId]/analytics` | `GET` | MANAGER | Rollups (bookings, revenue, earnings, wallet burn) | — |
-| `/api/organizations/[orgId]/activity` | `GET` | MANAGER | OrgAuditLog feed (filterable by `?category=` / `?action=` / date) | — |
-| `/api/organizations/[orgId]/audit` | `GET` | active member | Audit-log read (paginated; `?actions[]=` / `?category=` / date). Wider read than `/activity`. | — |
-| `/api/organizations/[orgId]/audit/export` | `GET` | MAINTAINER | CSV export of the audit trail (`?actions[]=` / date). The export is itself auditable. | `AUDIT_LOG_EXPORTED` (SETTINGS) |
+| Path | Verb | Min role | Purpose | Audit actions |
+| ----------------------------------------------------- | ----- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| `/api/organizations/[orgId]/checkout/overage-preview` | `GET` | active member | #777 §C — advisory pre-checkout overage preview ("will booking this plan breach my cap, and what does it cost?"). Price is read **server-side** from the plan list price (`?planType=` / `?planId=` / `?sessions=`); a safe over-estimate vs the authoritative checkout charge. | — |
+| `/api/organizations/[orgId]/analytics` | `GET` | MANAGER | Rollups (bookings, revenue, earnings, wallet burn) | — |
+| `/api/organizations/[orgId]/activity` | `GET` | MANAGER | OrgAuditLog feed (filterable by `?category=` / `?action=` / date) | — |
+| `/api/organizations/[orgId]/audit` | `GET` | active member | Audit-log read (paginated; `?actions[]=` / `?category=` / date). Wider read than `/activity`. | — |
+| `/api/organizations/[orgId]/audit/export` | `GET` | MAINTAINER | CSV export of the audit trail (`?actions[]=` / date). The export is itself auditable. | `AUDIT_LOG_EXPORTED` (SETTINGS) |
## Stream (chat / video)
These two routes expose the org's Stream chat and video metadata; the call/recording export is auditable because it is a compliance pull.
-| Path | Verb | Min role | Purpose | Audit actions |
-|------|------|----------|---------|----------------|
-| `/api/organizations/[orgId]/stream/channels` | `GET` | MANAGER | Stream chat channel roster (metadata only; message bodies are never fetched, per ADR 20) | `STREAM_CHANNELS_EXPORTED` (SYSTEM) |
-| `/api/organizations/[orgId]/stream/calls` | `GET` | MANAGER | Call/recording metadata export (compliance pull) | `STREAM_CALLS_EXPORTED` (SYSTEM) |
+| Path | Verb | Min role | Purpose | Audit actions |
+| -------------------------------------------- | ----- | -------- | ---------------------------------------------------------------------------------------- | ----------------------------------- |
+| `/api/organizations/[orgId]/stream/channels` | `GET` | MANAGER | Stream chat channel roster (metadata only; message bodies are never fetched, per ADR 20) | `STREAM_CHANNELS_EXPORTED` (SYSTEM) |
+| `/api/organizations/[orgId]/stream/calls` | `GET` | MANAGER | Call/recording metadata export (compliance pull) | `STREAM_CALLS_EXPORTED` (SYSTEM) |
## Retired audit actions
diff --git a/docs/enterprise/50-operations/07-required-secrets.md b/docs/enterprise/50-operations/07-required-secrets.md
index 5de3957f6..e6d342b21 100644
--- a/docs/enterprise/50-operations/07-required-secrets.md
+++ b/docs/enterprise/50-operations/07-required-secrets.md
@@ -64,6 +64,7 @@ real value.
| `SUPABASE_SERVICE_ROLE_KEY` | 4 workflows | Storage and admin operations in document and recording jobs. |
| `NEXT_PUBLIC_SUPABASE_URL` | 6 workflows | Supabase project URL. |
| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | 4 workflows | The public Supabase key. It is required by every job that reaches `lib/supabase.ts`, including the ones that only ever use the admin client, because that module constructs the public client first and throws at module scope when the key is unset. Until #1270 no workflow referenced it at all, so `mark-expired-recordings`, `cleanup-old-stream-recordings`, `transfer-expiring-recordings` and `purge-deleted-documents` all died during import on every run they have ever had. The secret itself has been provisioned since 2025-12-09; only the workflow references were missing. |
+| `PAN_ENCRYPTION_KEY` | `tds-return-draft` | Hex AES-256-GCM key that decrypts `ConsultantTaxInfo.panEncrypted` and `OrganizationTaxInfo.panEncrypted`. Only the quarterly TDS return export needs it, and only to write the full PAN into the private return CSV. Without it every PAN cell in that CSV is blank and the CA cannot file the quarter; the job still succeeds, so the failure is silent. |
| `RESEND_API_KEY` | 4 workflows | Transactional email delivery. |
| `STREAM_API_KEY`, `STREAM_API_SECRET`, `NEXT_PUBLIC_STREAM_API_KEY` | Stream jobs | Stream.io video and chat administration. |
| `SENTRY_DSN` | all 56 scheduled workflows + `cron-heartbeat` | Fallback alert sink in `scripts/ci/notify-ops-failure.sh`. Because `SLACK_OPS_WEBHOOK_URL` has never been provisioned, this is currently the _only_ channel by which a money-cron _failure_ reaches anyone. It is also the value each scheduled workflow falls back to when exporting `NEXT_PUBLIC_SENTRY_DSN` (see the next row). |
@@ -85,12 +86,14 @@ real value.
Every row here is currently silently degraded in production. These should be
provisioned before launch, in roughly this order.
-| Secret | Consumers | What is broken without it |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `SLACK_OPS_WEBHOOK_URL` | all 56 scheduled workflows | No money-cron failure is paged anywhere. `scripts/ci/notify-ops-failure.sh` now falls back to Sentry when `SENTRY_DSN` is present, so this is no longer a total blackout, but Slack remains the intended primary channel. |
-| `NOVU_SECRET_KEY` | `dunning`, `generate-subscription-invoices`, `wallet-low-balance`, `timeout-member-overages`, `detect-consultant-no-shows`, `send-appointment-reminders`, `transfer-expiring-recordings` | Money notifications never send. Customers are not told that an invoice is overdue, that a wallet is low, or that an overage was charged, while the underlying money state changes anyway. |
-| `NEXT_PUBLIC_APP_URL` | `databreach-deadline-alerts`, `detect-consultant-no-shows`, `msme-payment-alerts`, `send-appointment-reminders` | Links inside outbound emails are built against an empty origin, so recipients receive broken URLs. |
-| `MSME_ALERT_EMAIL` | `msme-payment-alerts` | The MSME 45-day payment-deadline alert has no recipient, so a statutory deadline under Section 43B(h) can pass unnoticed. |
+| Secret | Consumers | What is broken without it |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SLACK_OPS_WEBHOOK_URL` | all 56 scheduled workflows | No money-cron failure is paged anywhere. `scripts/ci/notify-ops-failure.sh` now falls back to Sentry when `SENTRY_DSN` is present, so this is no longer a total blackout, but Slack remains the intended primary channel. |
+| `NOVU_SECRET_KEY` | `dunning`, `generate-subscription-invoices`, `wallet-low-balance`, `timeout-member-overages`, `detect-consultant-no-shows`, `send-appointment-reminders`, `transfer-expiring-recordings` | Money notifications never send. Customers are not told that an invoice is overdue, that a wallet is low, or that an overage was charged, while the underlying money state changes anyway. |
+| `NEXT_PUBLIC_APP_URL` | `databreach-deadline-alerts`, `detect-consultant-no-shows`, `msme-payment-alerts`, `send-appointment-reminders` | Links inside outbound emails are built against an empty origin, so recipients receive broken URLs. |
+| `MSME_ALERT_EMAIL` | `msme-payment-alerts` | The MSME 45-day payment-deadline alert has no recipient, so a statutory deadline under Section 43B(h) can pass unnoticed. |
+| `PLATFORM_GSTIN` | `gst-outward-register-export`, the invoice and credit-note download routes | The platform cannot identify itself as the supplier, so it issues no tax invoice at all. `getPlatformSupplier()` fails closed by design, which means every consumer download returns a 503 and the monthly register healer mints nothing. |
+| `SUPPLIER_STATE_CODE` | `gst-outward-register-export`, the checkout tax engine | A fallback only: consumer invoicing reads the supplier's state from the first two digits of `PLATFORM_GSTIN` and uses this variable only when the GSTIN carries none. Setting it to a state the GSTIN contradicts stops consumer invoicing altogether, because the mint fails closed rather than guess. |
### Missing — live payouts
@@ -120,6 +123,7 @@ that turning the flag on does not become an archaeology exercise.
| `LOAD_TEST_EMAIL`, `LOAD_TEST_PASSWORD` | `load-test` | The manual k6 load test cannot authenticate. The workflow is `workflow_dispatch`-only, so this never affects scheduled runs. |
| `PLATFORM_LUT_NUMBER`, `PLATFORM_LUT_VALID_TILL` | `lib/compliance/lut.ts` (checkout + invoicing tax gates) | Absent or expired means international supplies are charged 18% IGST instead of zero-rated (#1230). That is the fail-closed default and is legally safe — it just costs foreign customers more until finance files Form RFD-11 for the current FY and sets both values. `VALID_TILL` is the inclusive ISO date, normally the FY end (`YYYY-03-31`). |
| `SENTRY_AUTH_TOKEN` (GSTR-8 workflow) | `gstr8-draft-export` | The job still runs and prints the draft, but its empty-period warning never reaches Sentry — an unattended silent zero. |
+| `PLATFORM_INVOICE_PREFIX` | `gst-outward-register-export` | The consumer invoice and credit-note series falls back to the `FAM` prefix, so documents are still issued on a gapless statutory series. Set this only if finance wants a different series name; it is a naming preference, not a launch blocker. |
## The second surface: Netlify runtime environment
@@ -144,13 +148,20 @@ it. The consequence is narrow but worth stating plainly: gateway webhooks cannot
be exercised on a preview, so refund, dispute and payout events can only be
tested against production or locally.
-| Variable | Read by | What is broken where it is missing |
-| ---------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `RAZORPAY_ALLOW_TEST_KEYS_IN_PRODUCTION` | `lib/payments/core/razorpay.ts` at module load | Optional pre-launch opt-out. When it is exactly `true`, a Razorpay TEST key under the production posture logs a loud error instead of throwing, so checkout, refunds and cancellation previews boot against test mode. Delete it and set LIVE keys before signup opens. |
-| `RAZORPAY_WEBHOOK_SECRET` | `app/api/webhooks/razorpay/route.ts` | Every Razorpay webhook is rejected with a 500 before signature verification. Confirmed missing on Deploy Preview; **production has not been confirmed either way and should be**, because no live payment has ever exercised it. |
-| `RAZORPAYX_WEBHOOK_SECRET` | same route, payout-signature fallback | Payout webhooks signed with the X secret fail verification. Not yet provisioned anywhere; live payouts remain gated. |
-| `STRIPE_WEBHOOK_SECRET` | `app/api/webhooks/stripe/route.ts` | Same failure shape on the Stripe route. |
-| `STREAM_WEBHOOK_SECRET` | `app/api/stream/webhooks/route.ts` | Same failure shape on the Stream route. |
+| Variable | Read by | What is broken where it is missing |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CRON_SECRET` | `netlify/functions/cron-tick.mts`, plus every `app/api/cleanup/*` route it calls | The ticker (ADR 27, #1356) cannot authenticate to any `/api/cleanup/*` route, so it returns 500 without ever POSTing a target, and the ten money sweeps it drives fall back to GitHub Actions' measured ~100-minute cadence (ADR 22). This is the same secret already required for the GitHub Actions manifest above; it must additionally be set in the **Netlify production context**, which is a separate store this row exists to call out. |
+| `CRON_TICK_BASE_URL` | `netlify/functions/cron-tick.mts` | Optional. Netlify sets `URL` to the site's primary deploy URL in every context, and the ticker POSTs against that by default. Set this only to override where the ticker sends its requests — for example, running `netlify dev` locally against a `next dev` instance on a different port. |
+| `RAZORPAY_ALLOW_TEST_KEYS_IN_PRODUCTION` | `lib/payments/core/razorpay.ts` at module load | Optional pre-launch opt-out. When it is exactly `true`, a Razorpay TEST key under the production posture logs a loud error instead of throwing, so checkout, refunds and cancellation previews boot against test mode. Delete it and set LIVE keys before signup opens. |
+| `RAZORPAY_WEBHOOK_SECRET` | `app/api/webhooks/razorpay/route.ts` | Every Razorpay webhook is rejected with a 500 before signature verification. Confirmed missing on Deploy Preview; **production has not been confirmed either way and should be**, because no live payment has ever exercised it. |
+| `RAZORPAY_WEBHOOK_SECRET_PREVIOUS` | `app/api/webhooks/razorpay/route.ts`, alongside the current secret (#1451) | Optional, and empty is the correct steady state. It holds the previous webhook signing secret for the duration of a rotation, during which the route accepts a signature made with either value; without it, every delivery that Razorpay signed before the dashboard finished switching over is rejected as a forgery and the money event behind it is lost. Set it to the outgoing secret immediately before rotating, and delete it once the dashboard shows the new secret and no unverified deliveries remain. |
+| `RAZORPAYX_WEBHOOK_SECRET` | same route, payout-signature fallback | Payout webhooks signed with the X secret fail verification. Not yet provisioned anywhere; live payouts remain gated. |
+| `STRIPE_WEBHOOK_SECRET` | `app/api/webhooks/stripe/route.ts` | Same failure shape on the Stripe route. |
+| `STRIPE_ENABLED` | `assertGatewayUsable` in `lib/payments/validation/gateway-guards.ts`, read at call time | Optional, and absent is the intended default (#1351). Stripe is a contingency rail rather than a live payment method, so without the exact value `true` any attempt to route a checkout to Stripe or to mint a Stripe payment intent throws a `DisabledGatewayError`. Refunds of payments already taken on Stripe stay outside the fence and keep working, and so do mock payments: `createPaymentIntent` returns a mock intent before it reaches the guard, so a deployment running with `ENABLE_MOCK_PAYMENTS=true` can still exercise a Stripe-labelled Mock Pay flow with the fence closed. |
+| `NEXT_PUBLIC_STRIPE_ENABLED` | `paymentGateways` in `app/checkout/plans/utils.ts`, inlined into the client bundle at build time | Optional, and absent is the intended default (#1351). The Stripe card on the four checkout pages renders a disabled "Coming Soon" button and no `StripeCheckout` mounts. Because the value is inlined at build time, turning Stripe on requires a redeploy and not just an environment change, and because it ships to the browser it is not a security control on its own. |
+| `STRIPE_ALLOW_TEST_KEYS_IN_PRODUCTION` | `initializeStripeClient` in `lib/payments/core/stripe.ts`, when the client is lazily constructed | Optional pre-launch opt-out, the Stripe twin of `RAZORPAY_ALLOW_TEST_KEYS_IN_PRODUCTION`. When it is exactly `true`, a test-mode secret key under the production posture logs a loud error instead of throwing `STRIPE_TEST_KEY_IN_PRODUCTION`. The guard treats both prefixes as test mode, the standard `sk_test_…` and the restricted `rk_test_…` that Stripe recommends for server-side use. Delete it and set a LIVE key before Stripe is ever enabled for customers. |
+| `STREAM_WEBHOOK_SECRET` | `app/api/stream/webhooks/route.ts` | Same failure shape on the Stream route. |
+| `RATE_CARD_SCOPED_RESOLUTION` | `lib/api/organizations/rate-card.ts` (`isScopedRateCardResolutionEnabled`), consumed by `resolveOrgSplit` in `lib/payments/payouts/earnings-service.ts`; also read by `.github/workflows/sync-payment-earnings.yml` as the GitHub repository variable `vars.RATE_CARD_SCOPED_RESOLUTION` | Absent means off, which is the intended default (#1335). Off, settlement forwards only org scope, so a contract- or plan-scoped `RateCard` an org has created can never be selected and its bookings settle on the org default instead. To enable, set the exact value `on` in BOTH stores: the Netlify environment (the capture webhook) and the GitHub repository variable (the earnings healer). Any other value, including `true`, leaves it off. Not a credential; it is listed because the two surfaces read the same money code, and a value present in only one store would settle the same booking two different ways depending on which surface accrued it. |
Confirming production is a two-minute check and it has never been done, so it is
worth doing before the first live payment rather than after: open the Netlify
diff --git a/docs/enterprise/70-design-decisions/00-README.md b/docs/enterprise/70-design-decisions/00-README.md
index dd5258f47..2491862ee 100644
--- a/docs/enterprise/70-design-decisions/00-README.md
+++ b/docs/enterprise/70-design-decisions/00-README.md
@@ -8,7 +8,7 @@ last-reviewed: 2026-06-15
# Design decisions (ADRs) — band index
-This band collects the architecture decision records for the enterprise layer. Where the other bands document *what* the system does and *how* it does it, each ADR here records *why* one design was chosen over its alternatives, at the moment the choice was made. Read these before proposing a structural change: most "why don't we just…" questions are answered by an ADR, and a change that reverses one should say so explicitly in its PR description.
+This band collects the architecture decision records for the enterprise layer. Where the other bands document _what_ the system does and _how_ it does it, each ADR here records _why_ one design was chosen over its alternatives, at the moment the choice was made. Read these before proposing a structural change: most "why don't we just…" questions are answered by an ADR, and a change that reverses one should say so explicitly in its PR description.
## Format
@@ -21,32 +21,35 @@ Every ADR follows the same four-part shape, written in full sentences:
## Index
-All twenty-five ADRs below are written and live (#793 wrote the first twelve; #872 added 15–17; #971 added 18; the dashboard consolidation added 19–20; the money-productionization pass added 21–22; #1051 added 23; the offering content model added 24; and #705 added 25); this index is the authoritative list. Each row links to its record.
-
-| # | ADR | Decision in one line |
-|---|---|---|
-| 01 | [Double-entry journal over three logs](01-double-entry-over-three-logs.md) | One balanced `LedgerTransaction`/`LedgerEntry` journal replaced `FundingLedgerEntry`, `WalletEntry`, and `SettlementLedgerEntry` (#772). |
-| 02 | [Integer paise and basis points](02-integer-paise-and-basis-points.md) | All money is integer paise and all splits are integer basis points, so no float ever touches a balance. |
-| 03 | [Deterministic ledger-account IDs](03-deterministic-ledger-account-ids.md) | Ledger accounts use deterministic composite IDs (kind|org|consultant|currency) instead of UUIDs (#783). |
-| 04 | [Batch payouts over streaming](04-batch-payouts-over-streaming.md) | Earnings settle in periodic idempotent batches rather than per-earning transfers. |
-| 05 | [GitHub Actions crons](05-github-actions-crons.md) | Scheduled jobs run as GitHub Actions invoking `npx tsx jobs/**` directly (with `CRON_SECRET`-gated routes as a manual fallback) rather than Netlify scheduled functions. |
-| 06 | [Typed Membership over BetterAuth Member](06-typed-membership-over-betterauth-member.md) | Every permission gate reads the typed `Membership` row, never BetterAuth's own member table. |
-| 07 | [Upstash rate limiting](07-upstash-rate-limiting.md) | BetterAuth's built-in limiter stays off; Upstash sliding windows gate the sensitive routes. |
-| 08 | [Gapless invoice counters](08-gapless-invoice-counters.md) | Invoice and credit-note numbers come from per-org, per-fiscal-year atomic counters to satisfy CGST Rules 46/53. |
-| 09 | [Webhook secret-rotation grace](09-webhook-rotation-grace.md) | Outbound webhook secret rotation dual-signs for 24 hours so receivers can cut over without a hard break. |
-| 10 | [Session-generation clock](10-session-generation-clock.md) | Role changes bump `User.sessionGeneration` to force a membership refetch instead of revoking sessions. |
-| 11 | [Live-payout submission freeze](11-live-payout-submission-freeze.md) | `ENABLE_LIVE_PAYOUTS` freezes only the gateway submission step; the whole pipeline upstream of it runs for real. |
-| 12 | [PENDING_TRUST earnings parking](12-pending-trust-earnings-parking.md) | Earnings for unverified INVOICE-funded orgs park in `PENDING_TRUST` until the org verifies or pays, closing the ghost-org fraud hole (#687). |
-| 13 | [Postgres-native concurrency](13-postgres-native-concurrency.md) | State transitions are guarded by CAS WHERE clauses, Serializable retries, version columns, and Redis cron locks — no Kafka, RabbitMQ, Temporal, or Inngest at this stage. |
-| 14 | [Async and queue posture](14-async-queue-posture.md) | Background work stays queue-less for launch (GH Actions crons + `after()` + sweeper re-drives); Upstash QStash is the pre-approved escalation, gated on two named telemetry triggers. |
-| 15 | [Currency as enum with display fields](15-currency-as-enum-with-display-fields.md) | Settlement currency stays the `Currency` enum; gateway and buyer codes live in free-text display fields, and the ledger is keyed INR-only (#783). |
-| 16 | [Slot freshness without realtime](16-slot-freshness-without-realtime.md) | Slot freshness comes from server-authoritative 409 conflicts plus focused refetch and invalidate-on-mutation, not Supabase Realtime. |
-| 17 | [Timezone pinned to IST for launch](17-timezone-pinned-to-ist-for-launch.md) | The platform pins to IST and removes the speculative DST materialization layer; the full IANA-TZID implementation is deferred to #872. |
-| 18 | [Open B2B/B2C boundary](18-open-b2b-b2c-boundary.md) | Sponsors fund any marketplace consultant and collaborations stay org-blind by design; `ProgramConsultantAllowlist` and `Membership.exclusiveEngagement` began as schema stubs and have both been enforced at checkout since 2026-07-11. |
-| 19 | [Personal-vs-org dashboard split](19-personal-vs-org-dashboard-split.md) | Dashboards split by the org-ness of the underlying session, plan or payment — views split, instruments do not; a nav entry must be a distinct destination, so scope variants become on-page toggles and filters become tabs; admin and staff keep two URL trees over one implementation, with access decided by a permission matrix rather than by which tree you landed in. |
-| 20 | [Org visibility into member sessions](20-org-visibility-into-member-sessions.md) | An organization sees that a session happened — member, counterpart, plan title, time, status, cost — and never what happened in it; notes, feedback, recordings, document contents and chat stay with the two participants, enforced by select allowlists that branch on whether the scope constrains the caller to be one of them. |
-| 21 | [Single writer for payment confirmation](21-single-writer-for-payment-confirmation.md) | `Payment.paymentStatus` is written by the confirmation pipeline and by nothing else; the webhook, the client's signature return, the on-demand sync and the reconcile cron all call `routeCapturedPayment` rather than recording the conclusion themselves, because a second writer turns `handlePaymentSuccess`'s already-SUCCEEDED guard from "this work is done" into "this work will never be done". |
-| 22 | [Queue posture, revisited with measurements](22-queue-posture-revisited-with-measurements.md) | Measured cadence shows sub-hourly GitHub Actions schedules deliver roughly one tick per 100 minutes while nothing overlaps, so the defect is missed ticks rather than contention; the QStash escalation in ADR 14 is now authorised, Temporal stays out on cost and fit rather than on the architectural objection its 2026 Lambda workers retired, and Inngest is recorded with concrete adoption triggers. |
-| 23 | [Notification scope](23-notification-scope.md) | A notification inherits the org-ness of the record that triggered it: dual-context payloads carry a required `NotificationScope`, deep links resolve to the owning dashboard rather than bouncing everyone to their personal tree, the Inbox filters the shared feed back apart by scope, and three org categories make the previously unmutable `ORG_*` family configurable. |
-| 24 | [The offering content model](24-offering-content-model.md) | An offering is described by structured content rather than one free-text blob: `subtitle`, `targetAudience`, `whatsIncluded` and a polymorphic `PlanFaq` land on all four plan types, the two curriculum tables stay separate but both gain a free-text `sectionLabel` that groups sessions under a heading, `level` becomes the `PlanLevel` enum, all four plan types get a detail page gated by `isPlanViewable`, and the pricing toggle becomes a chooser with an Open-details and a booking CTA. |
-| 25 | [Per-session reviews and the published score](25-per-session-reviews-and-published-score.md) | A review belongs to a session rather than to a relationship (`@@unique([appointmentId, consulteeProfileId])`), a group session contributes the mean of its attendees as one data point through the denormalized `ratingUnitId`, `ConsultantProfile.publishedRating` stays null below five distinct rated sessions, public reviews and the private CSAT in `AppointmentFeedback` remain separate objects because FTC 16 CFR §465.1(d) makes a bare star rating a consumer review, and every attendee of every held session is asked identically with no sentiment gate and no incentive (#705). |
+All twenty-six ADRs below are written and live (#793 wrote the first twelve; #872 added 15–17; #971 added 18; the dashboard consolidation added 19–20; the money-productionization pass added 21–22; #1051 added 23; the offering content model added 24; #705 added 25; and the 2026-09-03 financial audit added 27 — 26 is numbered for a companion decision from the same audit that has not yet merged); this index is the authoritative list. Each row links to its record.
+All twenty-six ADRs below are written and live (#793 wrote the first twelve; #872 added 15–17; #971 added 18; the dashboard consolidation added 19–20; the money-productionization pass added 21–22; #1051 added 23; the offering content model added 24; #705 added 25; and the 2026-09-03 financial audit added 26); this index is the authoritative list. Each row links to its record.
+
+| # | ADR | Decision in one line |
+| --- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 01 | [Double-entry journal over three logs](01-double-entry-over-three-logs.md) | One balanced `LedgerTransaction`/`LedgerEntry` journal replaced `FundingLedgerEntry`, `WalletEntry`, and `SettlementLedgerEntry` (#772). |
+| 02 | [Integer paise and basis points](02-integer-paise-and-basis-points.md) | All money is integer paise and all splits are integer basis points, so no float ever touches a balance. |
+| 03 | [Deterministic ledger-account IDs](03-deterministic-ledger-account-ids.md) | Ledger accounts use deterministic composite IDs (kind|org|consultant|currency) instead of UUIDs (#783). |
+| 04 | [Batch payouts over streaming](04-batch-payouts-over-streaming.md) | Earnings settle in periodic idempotent batches rather than per-earning transfers. |
+| 05 | [GitHub Actions crons](05-github-actions-crons.md) | Scheduled jobs run as GitHub Actions invoking `npx tsx jobs/**` directly (with `CRON_SECRET`-gated routes as a manual fallback) rather than Netlify scheduled functions. |
+| 06 | [Typed Membership over BetterAuth Member](06-typed-membership-over-betterauth-member.md) | Every permission gate reads the typed `Membership` row, never BetterAuth's own member table. |
+| 07 | [Upstash rate limiting](07-upstash-rate-limiting.md) | BetterAuth's built-in limiter stays off; Upstash sliding windows gate the sensitive routes. |
+| 08 | [Gapless invoice counters](08-gapless-invoice-counters.md) | Invoice and credit-note numbers come from per-org, per-fiscal-year atomic counters to satisfy CGST Rules 46/53. |
+| 09 | [Webhook secret-rotation grace](09-webhook-rotation-grace.md) | Outbound webhook secret rotation dual-signs for 24 hours so receivers can cut over without a hard break. |
+| 10 | [Session-generation clock](10-session-generation-clock.md) | Role changes bump `User.sessionGeneration` to force a membership refetch instead of revoking sessions. |
+| 11 | [Live-payout submission freeze](11-live-payout-submission-freeze.md) | `ENABLE_LIVE_PAYOUTS` freezes only the gateway submission step; the whole pipeline upstream of it runs for real. |
+| 12 | [PENDING_TRUST earnings parking](12-pending-trust-earnings-parking.md) | Earnings for unverified INVOICE-funded orgs park in `PENDING_TRUST` until the org verifies or pays, closing the ghost-org fraud hole (#687). |
+| 13 | [Postgres-native concurrency](13-postgres-native-concurrency.md) | State transitions are guarded by CAS WHERE clauses, Serializable retries, version columns, and Redis cron locks — no Kafka, RabbitMQ, Temporal, or Inngest at this stage. |
+| 14 | [Async and queue posture](14-async-queue-posture.md) | Background work stays queue-less for launch (GH Actions crons + `after()` + sweeper re-drives); Upstash QStash is the pre-approved escalation, gated on two named telemetry triggers. |
+| 15 | [Currency as enum with display fields](15-currency-as-enum-with-display-fields.md) | Settlement currency stays the `Currency` enum; gateway and buyer codes live in free-text display fields, and the ledger is keyed INR-only (#783). |
+| 16 | [Slot freshness without realtime](16-slot-freshness-without-realtime.md) | Slot freshness comes from server-authoritative 409 conflicts plus focused refetch and invalidate-on-mutation, not Supabase Realtime. |
+| 17 | [Timezone pinned to IST for launch](17-timezone-pinned-to-ist-for-launch.md) | The platform pins to IST and removes the speculative DST materialization layer; the full IANA-TZID implementation is deferred to #872. |
+| 18 | [Open B2B/B2C boundary](18-open-b2b-b2c-boundary.md) | Sponsors fund any marketplace consultant and collaborations stay org-blind by design; `ProgramConsultantAllowlist` and `Membership.exclusiveEngagement` began as schema stubs and have both been enforced at checkout since 2026-07-11. |
+| 19 | [Personal-vs-org dashboard split](19-personal-vs-org-dashboard-split.md) | Dashboards split by the org-ness of the underlying session, plan or payment — views split, instruments do not; a nav entry must be a distinct destination, so scope variants become on-page toggles and filters become tabs; admin and staff keep two URL trees over one implementation, with access decided by a permission matrix rather than by which tree you landed in. |
+| 20 | [Org visibility into member sessions](20-org-visibility-into-member-sessions.md) | An organization sees that a session happened — member, counterpart, plan title, time, status, cost — and never what happened in it; notes, feedback, recordings, document contents and chat stay with the two participants, enforced by select allowlists that branch on whether the scope constrains the caller to be one of them. |
+| 21 | [Single writer for payment confirmation](21-single-writer-for-payment-confirmation.md) | `Payment.paymentStatus` is written by the confirmation pipeline and by nothing else; the webhook, the client's signature return, the on-demand sync and the reconcile cron all call `routeCapturedPayment` rather than recording the conclusion themselves, because a second writer turns `handlePaymentSuccess`'s already-SUCCEEDED guard from "this work is done" into "this work will never be done". |
+| 22 | [Queue posture, revisited with measurements](22-queue-posture-revisited-with-measurements.md) | Measured cadence shows sub-hourly GitHub Actions schedules deliver roughly one tick per 100 minutes while nothing overlaps, so the defect is missed ticks rather than contention; the QStash escalation in ADR 14 is now authorised, Temporal stays out on cost and fit rather than on the architectural objection its 2026 Lambda workers retired, and Inngest is recorded with concrete adoption triggers. |
+| 23 | [Notification scope](23-notification-scope.md) | A notification inherits the org-ness of the record that triggered it: dual-context payloads carry a required `NotificationScope`, deep links resolve to the owning dashboard rather than bouncing everyone to their personal tree, the Inbox filters the shared feed back apart by scope, and three org categories make the previously unmutable `ORG_*` family configurable. |
+| 24 | [The offering content model](24-offering-content-model.md) | An offering is described by structured content rather than one free-text blob: `subtitle`, `targetAudience`, `whatsIncluded` and a polymorphic `PlanFaq` land on all four plan types, the two curriculum tables stay separate but both gain a free-text `sectionLabel` that groups sessions under a heading, `level` becomes the `PlanLevel` enum, all four plan types get a detail page gated by `isPlanViewable`, and the pricing toggle becomes a chooser with an Open-details and a booking CTA. |
+| 25 | [Per-session reviews and the published score](25-per-session-reviews-and-published-score.md) | A review belongs to a session rather than to a relationship (`@@unique([appointmentId, consulteeProfileId])`), a group session contributes the mean of its attendees as one data point through the denormalized `ratingUnitId`, `ConsultantProfile.publishedRating` stays null below five distinct rated sessions, public reviews and the private CSAT in `AppointmentFeedback` remain separate objects because FTC 16 CFR §465.1(d) makes a bare star rating a consumer review, and every attendee of every held session is asked identically with no sentiment gate and no incentive (#705). |
+| 27 | [State-as-outbox with a scheduled ticker](27-state-as-outbox-and-scheduled-ticker.md) | No generic outbox table is added — domain rows (`Payment`, `Appointment`, `Refund`, `WalletTopUp`, `WebhookEvent`, `OutboundWebhookDelivery`, `FailedEmail`) already carry the durable state one exists to provide; instead `netlify/functions/cron-tick.mts` POSTs the latency-sensitive `/api/cleanup/*` sweeps every five minutes, because GitHub Actions was measured delivering a sub-hourly schedule roughly once per hundred minutes (ADR 22), while Actions keeps the daily/weekly crons and the unbounded backstop (#866, #1010, #1356). |
+| 26 | [GST — the platform bills as principal supplier](26-gst-principal-model.md) | The platform is the supplier of record for GST — 18% on the full discounted price, a B2C tax invoice and credit note on the platform's own gapless series, and no Section 52 TCS collection — paired with the pre-existing Section 194-O operator withholding on income tax, pending a CA opinion on whether that pairing holds (#1360, #1361, #1388). |
diff --git a/docs/enterprise/70-design-decisions/15-currency-as-enum-with-display-fields.md b/docs/enterprise/70-design-decisions/15-currency-as-enum-with-display-fields.md
index 0c2ad7ae3..707709bf1 100644
--- a/docs/enterprise/70-design-decisions/15-currency-as-enum-with-display-fields.md
+++ b/docs/enterprise/70-design-decisions/15-currency-as-enum-with-display-fields.md
@@ -47,10 +47,20 @@ boundary. `toCurrencyEnum()` (in `lib/payments/validation/currency-guards.ts`)
is the single normaliser: it trims, upper-cases, and accepts only codes in the
enum, throwing on anything else so a webhook caller dead-letters the event
rather than settling a currency the platform cannot represent. That enum is
-deliberately narrower than `CURRENCY_MULTIPLIERS` (in `lib/payments/index.ts`),
-which lists display-only FX codes the UI can render but the platform cannot
+deliberately narrower than `SUPPORTED_CURRENCY_CODES` (in
+`lib/currency-codes.ts`), which lists the display-only FX codes the navbar can
+render and the checkout pages can estimate in, but which the platform cannot
settle; the two must not be conflated, and a comment in the guard cross-links
-them.
+them. `CURRENCY_MULTIPLIERS` used to play that role and is referenced by older
+revisions of this document; it was deleted in #1396 because nothing imported it.
+
+The same file now carries `assertInrSettlement`, which is the enforcement half
+of this decision. `toCurrencyEnum` says which currencies the platform can
+represent; `assertInrSettlement` says which one it can actually settle, and it
+runs as the first statement of both `createRazorpayOrder` and
+`createStripeCheckoutSession`. A caller that reads a currency out of the
+database and hands it to a gateway therefore fails loudly rather than minting an
+order denominated in a foreign subunit.
This decision also closed three latent multi-currency defects found in the same
review. Ledger accounts must never be keyed by a row's settlement currency:
diff --git a/docs/enterprise/70-design-decisions/26-gst-principal-model.md b/docs/enterprise/70-design-decisions/26-gst-principal-model.md
new file mode 100644
index 000000000..889448fbe
--- /dev/null
+++ b/docs/enterprise/70-design-decisions/26-gst-principal-model.md
@@ -0,0 +1,51 @@
+---
+title: GST — the platform bills as principal supplier
+band: 70-design-decisions
+audience: sde3
+status: live
+last-reviewed: 2026-09-03
+---
+
+# ADR 26 — GST: the platform bills as principal supplier
+
+## Context
+
+Checkout has always charged 18% GST on the full discounted booking price (`lib/payments/pricing/derive-checkout-amount.ts` → `lib/payments/tax/tax-engine.ts`), and the booking journal credits `GST_PAYABLE` for that amount (`lib/payments/payouts/earnings-service.ts`). That is the behaviour of a supplier of record: the platform sells the consultation to the buyer and remits output tax on the whole consideration. Income tax was wired the other way round: the platform withholds Section 194-O as an e-commerce operator paying an e-commerce participant (`lib/compliance/tds-194o.ts`, `lib/compliance/tds.ts`), which is the behaviour of a facilitator.
+
+The 2026-09-03 financial audit assumed the facilitator reading for GST as well and filed GST-TCS Section 52 collection (#1360) and GSTR builders (#1361) as launch blockers. The two readings cannot both drive the code: a facilitator charges GST only on its commission and collects 0.5% TCS on registered suppliers' sales; a principal charges GST on the whole price, issues the tax invoice to the buyer, and collects no TCS because it is the supplier. Consulting is not a Section 9(5) notified service, so neither reading is forced by statute; it is a business-model choice with a chartered accountant's sign-off.
+
+## Decision
+
+The platform bills as **principal supplier for GST**. Concretely:
+
+1. GST stays at 18% on the full discounted price, booked to `GST_PAYABLE` at settlement, exactly as today.
+2. The platform will issue a numbered **B2C tax invoice** for every consumer supply and a **credit note** for every refund (`ConsumerInvoice`, `ConsumerCreditNote`, platform-wide gapless series under CGST Rule 46 and Rule 53), alongside the existing org invoices for sponsored supplies. This is design intent, not yet shipped: the models do not exist in the schema as of this ADR and land with PR-E (`feat/finance-b2c-tax-invoice`, in flight).
+3. Place of supply for a consumer is the declared or remembered billing state; when no address is on record, it defaults to the **supplier's state under Section 12(2)(b)** of the IGST Act, which makes the supply intra-state (CGST + SGST). This is the opposite of the B2B derivation's IGST fallback, which stays as an audit signal for org invoices.
+4. GST-TCS under Section 52 **does not apply** on this model and is not collected. The dormant schema (`Payment.gstTcsCollectedPaise`, `GstTcsBatch`, the GSTR-8 draft builder) stays in place, correctly annotated at 0.5%, and is only wired if the CA overturns this decision.
+5. The platform's own outward-supply return is produced as a period **register export** (all tax invoices and credit notes, with place of supply and tax heads) that the CA files GSTR-1 and GSTR-3B from. No in-app GSTR JSON builders.
+6. Income tax is unchanged: 194-O at 0.1% with the three-limb ₹5 lakh exemption, withheld on both the consultant and the host-org payout rails and reported on Form 140 (formerly 26Q) with Section 393 payment codes.
+
+## Alternatives considered
+
+The facilitator model — GST only on the platform's commission, 0.5% Section 52 TCS collected on registered consultants' sales, and monthly GSTR-8 filing — was rejected because it does not match the code that already exists: checkout has always charged 18% GST on the full discounted price and the booking journal has always credited `GST_PAYABLE` for that full amount, which is principal-supplier behaviour, not facilitator behaviour. Adopting the facilitator reading now would mean re-deriving every historical GST figure, wiring the dormant TCS schema, and building GSTR-8 tooling that the platform does not currently need — a pricing, invoice and ledger re-architecture rather than a continuation of the current design. It remains the fallback if the CA rejects the principal-supplier pairing (see Consequences below).
+
+## Consequences
+
+Every consumer payment will leave a statutory document trail the buyer can download once the B2C tax-invoice work lands, which closes the "incomplete information" gap in the money journey; that work (`ConsumerInvoice`, `ConsumerCreditNote`) is in flight and not yet in the schema (tracked as PR-E, `feat/finance-b2c-tax-invoice`). The register export gives the CA one file per month instead of a database query, once it ships alongside the invoices. Consultants who hold a GSTIN invoice the platform, not the buyer; that is a contractual and onboarding matter, not a code path, and belongs in the consultant terms.
+
+The pairing of principal-for-GST with operator-for-income-tax is defensible but unusual, and it is the first question on the CA list below. If the CA rejects it, the facilitator model is a pricing, invoice and ledger re-architecture (GST only on the platform fee, TCS on registered consultants, GSTR-8 monthly) and would be a new ADR.
+
+## Questions for the chartered accountant
+
+1. Does the principal-for-GST plus 194-O-operator pairing hold for a consultation marketplace where the platform sets the commission but the consultant sets the price and delivers the service?
+2. Referral credits are platform-funded and are applied **after** tax at checkout (price → discount code → tax → credits), so a buyer using a ₹500 credit pays GST on the pre-credit base. Is a platform-funded credit a discount recorded on the invoice under Section 15(3)(a), which would reduce the taxable value, or third-party consideration, which would not? The code path is `deriveCheckoutAmount`; nothing changes until this is answered.
+3. SAC classification: the platform defaults to 999293 (commercial training and coaching). For advisory consultations 998311 or 998399 may be the correct code; rates are unaffected, input-tax-credit trails are not.
+4. Is the Section 12(2)(b) supplier-state default acceptable for consumers who decline to declare a state, or must the checkout collect a state before payment?
+5. Confirm that Section 52 TCS registration is not required while the platform is the supplier of record.
+
+## Related
+
+- ADR 21 (single writer for payment confirmation) — the invoice is minted inside the same pipeline, never by a second writer.
+- ADR 08 (gapless invoice counters) — the platform series reuses the same atomic counter shape.
+- docs/compliance/02-gst-overview.md, docs/compliance/15-india-compliance-shipping-checklist.md, docs/compliance/10-rbi-pa-and-payment-architecture.md (Path C).
+- #1360 (relabelled CA-gated), #1361 (re-scoped to the register export), #1365, #1370.
diff --git a/docs/enterprise/70-design-decisions/27-state-as-outbox-and-scheduled-ticker.md b/docs/enterprise/70-design-decisions/27-state-as-outbox-and-scheduled-ticker.md
new file mode 100644
index 000000000..6e6f6ec90
--- /dev/null
+++ b/docs/enterprise/70-design-decisions/27-state-as-outbox-and-scheduled-ticker.md
@@ -0,0 +1,37 @@
+---
+title: State-as-outbox with a scheduled ticker
+band: 70-design-decisions
+audience: sde3
+status: live
+last-reviewed: 2026-09-03
+---
+
+# ADR 27 — State-as-outbox with a scheduled ticker
+
+## Context
+
+ADR 14 kept the platform queue-less for launch; ADR 22 measured GitHub Actions delivering every sub-hourly schedule roughly once per hundred minutes and authorised QStash as the escalation. The 2026-09-03 financial audit asked for a transactional outbox for post-payment side effects (#1356), and the owner asked for an unbiased answer on whether one is needed.
+
+Three facts settle it. First, the repo already has the durable state an outbox exists to provide: `WebhookEvent` is an inbox with a processed flag, `OutboundWebhookDelivery` and `FailedEmail` are outboxes with retry state, and every money-bearing follow-up is keyed on a domain row that already exists (`Payment`, `Appointment`, `Refund`, `WalletTopUp`). Second, every job under `jobs/` already has an HTTP twin under `app/api/cleanup/*` built by `lib/cron/cleanup-route.ts`, gated by `CRON_SECRET` and wrapped in the same `withCronLock`, so any scheduler that can POST can drive the fleet. Third, the only side effect that lacked a re-drive was Stream channel creation and its notification after a capture, and that is derivable from the appointment row.
+
+So the missing piece was never a table. It was a scheduler that fires when it says it will.
+
+## Decision
+
+1. **Domain rows are the outbox.** No generic outbox table is added. A follow-up that must survive a crash is expressed as a nullable stamp on the row it belongs to (for example `Appointment.chatChannelEnsuredAt`) plus an idempotent ensure-step in an existing sweeper.
+2. **A Netlify scheduled function is the ticker.** `netlify/functions/cron-tick.mts` runs every five minutes and POSTs the latency-sensitive sweep routes (stuck webhooks, refund cascade and reconcile, abandoned payments, payment-status reconcile, orphaned confirmations, orphaned top-up captures, outbound webhook dispatch, earnings sync and release) with the cron secret. Each route already holds a fail-closed Redis lock, so a ticker run and a GitHub Actions run cannot overlap; the loser answers 409 and that is expected.
+3. **GitHub Actions stays** for daily and weekly business crons, for the unbounded backstop runs of the same sweepers, and for manual dispatch with its run history.
+4. **Routes invoked by the ticker take a `limit`** so a single run fits inside the Next function ceiling of 26 seconds; the nightly Actions run remains unbounded.
+5. **QStash remains the escalation**, not the default. Its triggers are unchanged from ADR 14 and ADR 22: a notification fan-out that exceeds the synchronous budget, a measured webhook-processing SLO breach that a five-minute tick cannot close, or the Netlify scheduler proving as unreliable as Actions. Inngest and Temporal remain out on the criteria ADR 22 records.
+
+## Consequences
+
+The worst case for a buyer whose `after()` callback died falls from about a hundred minutes to about five, with no new vendor, no new secret inside the money path and no new table to reconcile. The trade-off is one more place that fires the fleet, which is why the ticker only ever hits routes that are already lock-guarded and idempotent, and why the cron heartbeat keeps watching the Actions side independently.
+
+Anyone adding a follow-up to a money path should first ask which row already records the obligation and which sweeper already walks that row, and only then consider a new mechanism.
+
+## Related
+
+- ADR 05 (GitHub Actions crons), ADR 14 (queue posture), ADR 22 (measurements) — this ADR narrows their remedy, it does not reverse them.
+- ADR 21 (single writer for payment confirmation) — the ticker never writes payment status; it only re-invokes the pipeline.
+- #866, #1010 (QStash plan), #1356 (the outbox request this answers), #1246 (orphan gateway orders, still hygiene).
diff --git a/docs/enterprise/90-audits/04-simplification-proposal.md b/docs/enterprise/90-audits/04-simplification-proposal.md
index dc1cec108..a16295dd0 100644
--- a/docs/enterprise/90-audits/04-simplification-proposal.md
+++ b/docs/enterprise/90-audits/04-simplification-proposal.md
@@ -23,6 +23,14 @@ toc-depth: 2
> This document remains useful as a historical record of the doc-dedup +
> dead-code + helper-consolidation recipes.
+> **Note (2026-09-03):** The SCIM section below (A2, and every other
+> reference to stubbing `lib/scim/` to a 501) is superseded. SCIM 2.0 has
+> since shipped in full: `lib/scim/` implements Users CRUD, bearer-token
+> authentication, group mapping and deprovisioning, and `ScimToken.expiresAt`
+> is enforced on every request. The "zero customers using it, stub to 501"
+> recommendation no longer applies to live code. This note closes #1373,
+> which tracked the doc drift.
+
# Executive Summary
The enterprise subsystem (~614 changed files, ~13,500 LoC of code + 11,141 lines of docs) is **complex but not over-complex** — most of the apparent weight is load-bearing. However, two parallel surveys (one over the 47 enterprise docs, one over the code surface) identified **~2,800 lines of preventable bloat** that can be removed with zero schema changes and zero customer-visible behavior changes.
@@ -41,11 +49,11 @@ The enterprise subsystem (~614 changed files, ~13,500 LoC of code + 11,141 lines
**Recommended phased rollout:**
-| Phase | Effort | LoC saved | Risk | Customer impact |
-|---|---|---|---|---|
-| **Phase 1 — Dead code & doc dedup** | 1 day | ~2,100 | None | None |
-| **Phase 2 — Helper consolidation** | 2 days | ~400 | Low | None |
-| **Phase 3 — Optional refactors** | 1-2 weeks | ~1,800 | Medium | None |
+| Phase | Effort | LoC saved | Risk | Customer impact |
+| ----------------------------------- | --------- | --------- | ------ | --------------- |
+| **Phase 1 — Dead code & doc dedup** | 1 day | ~2,100 | None | None |
+| **Phase 2 — Helper consolidation** | 2 days | ~400 | Low | None |
+| **Phase 3 — Optional refactors** | 1-2 weeks | ~1,800 | Medium | None |
Phase 1 is recommended for the PR #655 closeout. Phases 2 and 3 can land as follow-up technical debt PRs.
@@ -80,12 +88,12 @@ The `docs/enterprise/` directory holds **47 files / 11,141 lines** across 36 num
The three-ledger concept is explained across **four documents** at conflicting detail levels:
-| Doc | Focus | Lines | Issue |
-|---|---|---|---|
-| `07-payout-pipeline.md` | Org earnings + payout flow | 189 | Repeats 18's invariants at 90% detail |
-| `09-wallet-and-ledger.md` | Wallet + funding ledger | 163 | Defers to 18 for invariants but re-explains them |
-| `18-three-ledger-discipline.md` | All three ledgers + reconciliation | 220 | Positioned at #18 — too late for the consumer who already read 07/09 |
-| `20-payment-legs.md` | Stackable legs | 118 | Adjacent concept, sometimes confused with ledger design |
+| Doc | Focus | Lines | Issue |
+| ------------------------------- | ---------------------------------- | ----- | -------------------------------------------------------------------- |
+| `07-payout-pipeline.md` | Org earnings + payout flow | 189 | Repeats 18's invariants at 90% detail |
+| `09-wallet-and-ledger.md` | Wallet + funding ledger | 163 | Defers to 18 for invariants but re-explains them |
+| `18-three-ledger-discipline.md` | All three ledgers + reconciliation | 220 | Positioned at #18 — too late for the consumer who already read 07/09 |
+| `20-payment-legs.md` | Stackable legs | 118 | Adjacent concept, sometimes confused with ledger design |
**Root cause:** PR #655 retrofitted the three-ledger model after 07, 09, 20 were already written; doc 18 was meant to be a capstone but reads like an internal contradiction.
@@ -117,12 +125,12 @@ Four customer scenarios (Wipro, LearnPro, IIT Madras, Rahul) appear in **three**
Four docs have outlived their usefulness:
-| Doc | Lines | Why deletable |
-|---|---|---|
-| `13-feature-flags-and-rollout.md` | 153 | Flags rotate within weeks; lives better as JSDoc in `lib/feature-flags.ts` |
-| `17-hierarchy.md` | 112 | 95% "deferred UI" — feature not shipped |
-| `19-harness-verdict.md` | 87 | Snapshot from 2026-05-15, stale within weeks |
-| `22-route-migration-table.md` | 129 | Pre-Arch-4 → Arch-4 map; irrelevant post-2026-07 |
+| Doc | Lines | Why deletable |
+| --------------------------------- | ----- | -------------------------------------------------------------------------- |
+| `13-feature-flags-and-rollout.md` | 153 | Flags rotate within weeks; lives better as JSDoc in `lib/feature-flags.ts` |
+| `17-hierarchy.md` | 112 | 95% "deferred UI" — feature not shipped |
+| `19-harness-verdict.md` | 87 | Snapshot from 2026-05-15, stale within weeks |
+| `22-route-migration-table.md` | 129 | Pre-Arch-4 → Arch-4 map; irrelevant post-2026-07 |
**Action — DELETE 13, 17, 19. ARCHIVE 22 to `docs/migrations/`.**
@@ -156,19 +164,19 @@ Three docs carry too little to justify their own file:
## Phase 1 — Docs Simplification Summary
-| # | Action | Δ files | Δ lines |
-|---|---|---|---|
-| 1 | Merge 07 + 09 + 18 → new 09-ledgers.md | -2 | -89 |
-| 2 | Delete 14-scenarios-and-examples.md | -1 | -212 |
-| 3 | Delete 13-feature-flags-and-rollout.md | -1 | -153 |
-| 4 | Delete 17-hierarchy.md (placeholder) | -1 | -112 |
-| 5 | Delete 19-harness-verdict.md (stale) | -1 | -87 |
-| 6 | Archive 22 → `docs/migrations/` | 0 | 0 |
-| 7 | Delete 11, 27, 32 (fold into siblings) | -3 | -279 |
-| 8 | Trim 00-overview.md intro | 0 | -150 |
-| 9 | Extract roles matrix from 04 | +1 | -170 net |
-| 10 | Excise compliance from 08 | 0 | -80 |
-| **Total** | | **-8 files** | **~-1,333 lines** |
+| # | Action | Δ files | Δ lines |
+| --------- | -------------------------------------- | ------------ | ----------------- |
+| 1 | Merge 07 + 09 + 18 → new 09-ledgers.md | -2 | -89 |
+| 2 | Delete 14-scenarios-and-examples.md | -1 | -212 |
+| 3 | Delete 13-feature-flags-and-rollout.md | -1 | -153 |
+| 4 | Delete 17-hierarchy.md (placeholder) | -1 | -112 |
+| 5 | Delete 19-harness-verdict.md (stale) | -1 | -87 |
+| 6 | Archive 22 → `docs/migrations/` | 0 | 0 |
+| 7 | Delete 11, 27, 32 (fold into siblings) | -3 | -279 |
+| 8 | Trim 00-overview.md intro | 0 | -150 |
+| 9 | Extract roles matrix from 04 | +1 | -170 net |
+| 10 | Excise compliance from 08 | 0 | -80 |
+| **Total** | | **-8 files** | **~-1,333 lines** |
**Post-simplification:** 39 docs, ~9,800 lines (12% reduction). Zero customer impact.
@@ -198,10 +206,10 @@ The enterprise code surface spans ~13,500 LoC. Three categories of preventable b
### A3. Dead feature flags
-| Flag | Status |
-|---|---|
-| `ENABLE_TDS_ADMIN_VIEW` | Feature shipped; flag now always-true in deployments |
-| `ENABLE_HRIS` | No implementation exists; pre-scaffolding never wired |
+| Flag | Status |
+| ----------------------- | ----------------------------------------------------- |
+| `ENABLE_TDS_ADMIN_VIEW` | Feature shipped; flag now always-true in deployments |
+| `ENABLE_HRIS` | No implementation exists; pre-scaffolding never wired |
**Action — DELETE both flags** from `lib/feature-flags.ts` and audit callers.
@@ -233,10 +241,9 @@ const ROLE_CAPABILITIES: Record> = {
// ...
};
-export async function requireCapability(
- orgId: string,
- capability: Capability,
-) { /* single predicate */ }
+export async function requireCapability(orgId: string, capability: Capability) {
+ /* single predicate */
+}
```
Then `requireOrgOwner = requireCapability(..., "admin")` and `requireOrgBillingAdminOrOwner = requireCapability(..., "finance")`.
@@ -287,16 +294,16 @@ One huge file with subscription/one-off branching, slot locking, wallet vs inten
## Phase 2 — Code Simplification Summary
-| # | Action | Files | Δ LoC | Priority |
-|---|---|---|---|---|
-| 1 | Delete `payout-service.ts` | 1 file deleted | -910 | HIGH |
-| 2 | Stub SCIM to 501 | 4 files → 1 file | -484 | MEDIUM |
-| 3 | Delete `ENABLE_TDS_ADMIN_VIEW` flag | scattered | -20 | LOW |
-| 4 | Delete `ENABLE_HRIS` flag | scattered | -20 | LOW |
-| 5 | Unify role predicates → capability matrix | 2 files refactored | -200 | MEDIUM |
-| 6 | Split SlotAllocationService | 3 files → 5 files | 0 net | OPTIONAL |
-| 7 | Refactor checkout into handlers | 1 file → 5 files | 0 net | DEFER |
-| **Phase 1 total (high+medium)** | | | **~-1,614** | |
+| # | Action | Files | Δ LoC | Priority |
+| ------------------------------- | ---------------------------------------------------------------------------- | ------------------ | ----------- | -------- |
+| 1 | Delete `payout-service.ts` | 1 file deleted | -910 | HIGH |
+| 2 | ~~Stub SCIM to 501~~ (superseded — SCIM 2.0 shipped in full, see note above) | 4 files → 1 file | -484 | MEDIUM |
+| 3 | Delete `ENABLE_TDS_ADMIN_VIEW` flag | scattered | -20 | LOW |
+| 4 | Delete `ENABLE_HRIS` flag | scattered | -20 | LOW |
+| 5 | Unify role predicates → capability matrix | 2 files refactored | -200 | MEDIUM |
+| 6 | Split SlotAllocationService | 3 files → 5 files | 0 net | OPTIONAL |
+| 7 | Refactor checkout into handlers | 1 file → 5 files | 0 net | DEFER |
+| **Phase 1 total (high+medium)** | | | **~-1,614** | |
---
@@ -349,6 +356,7 @@ Dormant but cheap. Gated on `paymentGateway` schema field, doesn't intrude on ho
**Effort:** 1 day. **Risk:** None.
Actions:
+
1. Delete `lib/payments/payouts/payout-service.ts` (after grep verifies zero production callers)
2. Stub `lib/scim/*` to a 501 handler
3. Delete `ENABLE_TDS_ADMIN_VIEW` and `ENABLE_HRIS` from `lib/feature-flags.ts`
@@ -365,6 +373,7 @@ Actions:
**Effort:** 2 days. **Risk:** Low.
Actions:
+
1. Introduce `lib/auth/capabilities.ts` with `requireCapability()` + role→capability matrix
2. Refactor `requireOrgAccess`, `requireOrgOwner`, `requireOrgBillingAdminOrOwner` to thin wrappers
3. Migrate ~70 route handlers (mechanical, no behavior change)
@@ -377,6 +386,7 @@ Actions:
**Effort:** 1-2 weeks. **Risk:** Medium to High.
Trigger conditions:
+
- `SlotAllocationService` split → defer until the next slot-related feature touches the file
- `checkout.ts` modularization → defer until per-type variance increases (currently stable)
@@ -386,17 +396,17 @@ Don't do these speculatively. Wait for a real feature to justify.
# Decision Matrix
-| Proposal | Schema-locked? | Algorithm change? | Customer impact | LoC | Recommended for PR #655? |
-|---|---|---|---|---|---|
-| Delete `payout-service.ts` | ✅ no schema change | ✅ pure dead-code removal | None | -910 | **YES** |
-| Stub SCIM | ✅ no schema change | ✅ runtime swap | None (no users) | -484 | **YES** |
-| Delete dead flags | ✅ no schema change | ✅ env var removal | None | -40 | **YES** |
-| Merge ledger docs | ✅ no code change | N/A | None | -89 | **YES** |
-| Delete 7 stale/cosmetic docs | ✅ no code change | N/A | None | -1,113 | **YES** |
-| Trim/archive 4 docs | ✅ no code change | N/A | None | -250 | **YES** |
-| Unify role predicates | ✅ no schema change | ✅ refactor | None | -200 | Phase 2 |
-| Split SlotAllocationService | ✅ no schema change | ✅ refactor | None | 0 net | Phase 3 |
-| Modularize checkout.ts | ✅ no schema change | ✅ refactor | None | 0 net | Phase 3 (defer) |
+| Proposal | Schema-locked? | Algorithm change? | Customer impact | LoC | Recommended for PR #655? |
+| ---------------------------- | ------------------- | ------------------------- | --------------- | ------ | ------------------------ |
+| Delete `payout-service.ts` | ✅ no schema change | ✅ pure dead-code removal | None | -910 | **YES** |
+| ~~Stub SCIM~~ (superseded) | ✅ no schema change | ✅ runtime swap | None (no users) | -484 | **NO — SCIM shipped** |
+| Delete dead flags | ✅ no schema change | ✅ env var removal | None | -40 | **YES** |
+| Merge ledger docs | ✅ no code change | N/A | None | -89 | **YES** |
+| Delete 7 stale/cosmetic docs | ✅ no code change | N/A | None | -1,113 | **YES** |
+| Trim/archive 4 docs | ✅ no code change | N/A | None | -250 | **YES** |
+| Unify role predicates | ✅ no schema change | ✅ refactor | None | -200 | Phase 2 |
+| Split SlotAllocationService | ✅ no schema change | ✅ refactor | None | 0 net | Phase 3 |
+| Modularize checkout.ts | ✅ no schema change | ✅ refactor | None | 0 net | Phase 3 (defer) |
---
@@ -451,7 +461,7 @@ After Phase 1:
- [ ] `npx tsc --noEmit` clean
- [ ] `npx jest` — all suites pass (currently 61 suites / 990 tests; expect same count post-deletion, minus SCIM tests if any were present)
- [ ] Manual smoke: SPONSOR org create → invite LEARNER → book CLASS → engagementsUsed increments correctly
-- [ ] Manual smoke: hit `/api/organizations/[orgId]/scim/Users` → expect 501
+- [ ] ~~Manual smoke: hit `/api/organizations/[orgId]/scim/Users` → expect 501~~ (superseded — SCIM shipped; verify Users CRUD, bearer-token auth, group mapping, deprovisioning and `ScimToken.expiresAt` enforcement instead)
---
diff --git a/docs/enterprise/explainers/complete-guide.md b/docs/enterprise/explainers/complete-guide.md
index 8ef84e63b..db9a89c40 100644
--- a/docs/enterprise/explainers/complete-guide.md
+++ b/docs/enterprise/explainers/complete-guide.md
@@ -1299,7 +1299,7 @@ The chain is queryable end-to-end: you can ask "where did this ₹999 come from?
| `EARNINGS_LEDGER_DRIFT` | `OrganizationEarnings` projection == CONSULTANT/ORG payable legs |
| `PROGRAM_ASSIGNMENT_ENGAGEMENTS_DRIFT` | Per-assignment engagement counts |
| `ACTIVE_SEAT_COUNT_DRIFT` | `seatsUsed` == active assignments |
-| `PAYMENT_LEG_SUM_MISMATCH` | PaymentLegs sum to `Payment.amount` |
+| `PAYMENT_LEG_SUM_MISMATCH` | PaymentLegs sum to `Payment.amount`, excluding referral credits (#1347) |
| `ORG_PAYOUT_TOTAL_MISMATCH` | Org payout legs sum to claimed earnings |
The #772 cutover validated `ok: true` with **0 findings** on a full reseed.
diff --git a/docs/finances/07-tax-compliance-marketplace-obligations.md b/docs/finances/07-tax-compliance-marketplace-obligations.md
index 89fb414e7..43b472acb 100644
--- a/docs/finances/07-tax-compliance-marketplace-obligations.md
+++ b/docs/finances/07-tax-compliance-marketplace-obligations.md
@@ -10,21 +10,21 @@
### Flow 1: Consultee → Platform (Checkout)
-| Question | Indian Buyer | International Buyer |
-|----------|-------------|-------------------|
-| What do we charge? | Plan price + 18% GST | Plan price only (0% tax) |
-| Which gateway? | Razorpay (domestic) | Razorpay IBT |
-| What currency? | INR | INR (Razorpay converts for us) |
+| Question | Indian Buyer | International Buyer |
+| ------------------ | -------------------- | ------------------------------ |
+| What do we charge? | Plan price + 18% GST | Plan price only (0% tax) |
+| Which gateway? | Razorpay (domestic) | Razorpay IBT |
+| What currency? | INR | INR (Razorpay converts for us) |
**Code's job**: Detect buyer country → apply correct tax → route to gateway. ✅ Built.
### Flow 2: Platform → Consultant (Payout)
-| Question | Answer |
-|----------|--------|
-| How much do they get? | 80% of original price (before tax) |
-| Do we deduct anything? | Only if we've paid them > ₹50K total this financial year (Apr–Mar) |
-| How much to deduct? | 10% if they gave us their PAN, 20% if they didn't |
+| Question | Answer |
+| --------------------------------- | ------------------------------------------------------------------------------ |
+| How much do they get? | 80% of original price (before tax) |
+| Do we deduct anything? | Only if we've paid them > ₹50K total this financial year (Apr–Mar) |
+| How much to deduct? | 10% if they gave us their PAN, 20% if they didn't |
| Where does the deducted money go? | We deposit it to the government (not our money, not theirs — it's prepaid tax) |
**Code's job**: Track cumulative FY payments → deduct TDS if over ₹50K → send net amount to Razorpay. ✅ Built.
@@ -39,7 +39,7 @@ This is NOT code — it's CA/accountant work. Our code provides the data.
### Is GST Registration Mandatory?
-**YES.** Under **Section 24(x) of the CGST Act**, every e-commerce operator (ECO) must register under GST irrespective of turnover. The normal Rs 20 lakh threshold does NOT apply. (Note: Section 24(ix) applies to suppliers selling *through* an ECO; Section 24(x) applies to the ECO itself.)
+**YES.** Under **Section 24(x) of the CGST Act**, every e-commerce operator (ECO) must register under GST irrespective of turnover. The normal Rs 20 lakh threshold does NOT apply. (Note: Section 24(ix) applies to suppliers selling _through_ an ECO; Section 24(x) applies to the ECO itself.)
The definition in **Section 2(45)** is broad: "any person who owns, operates or manages digital or electronic facility or platform for electronic commerce." Familiarise qualifies.
@@ -51,24 +51,24 @@ Consulting/professional services are **NOT** in the Section 9(5) notified list (
### TCS (Tax Collected at Source) — GST
-| Parameter | Value |
-|-----------|-------|
-| TCS Rate | **0.5%** (reduced from 1% effective July 10, 2024) |
-| Intra-state split | 0.25% CGST + 0.25% SGST |
-| Inter-state | 0.5% IGST |
-| Calculated on | Net value of taxable supplies (minus returns/cancellations) |
-| Filing | **GSTR-8** by 10th of following month |
-| Annual statement | By December 31 following the FY |
-| Legal basis | **Section 52 of CGST Act** |
+| Parameter | Value |
+| ----------------- | ----------------------------------------------------------- |
+| TCS Rate | **0.5%** (reduced from 1% effective July 10, 2024) |
+| Intra-state split | 0.25% CGST + 0.25% SGST |
+| Inter-state | 0.5% IGST |
+| Calculated on | Net value of taxable supplies (minus returns/cancellations) |
+| Filing | **GSTR-8** by 10th of following month |
+| Annual statement | By December 31 following the FY |
+| Legal basis | **Section 52 of CGST Act** |
-The consultant gets credit in their electronic cash ledger.
+The consultant gets credit in their electronic cash ledger. The "Calculated on" row above is the correct base — TCS under Section 52 is 0.5% of the **net taxable value** of supplies (gross minus returns and cancellations), which is **GST-exclusive**, never the gross amount inclusive of GST. **Model decision (2026-09-03):** [ADR 26](../enterprise/70-design-decisions/26-gst-principal-model.md) locked the platform in as the Principal supplier of record for GST, under which this table does not apply at all — the platform charges GST on the full price and issues its own tax invoice, so there is no "supply by a registered consultant through an e-commerce operator" event to collect TCS on. This section stays in the document as regulatory reference for the facilitator reading that was considered and not chosen; the dormant `GstTcsBatch`/`GstTcsAdjustment` schema is CA-gated, not wired.
### GST on Platform Commission
-| Item | Rate | SAC Code |
-|------|------|----------|
+| Item | Rate | SAC Code |
+| ------------------------ | ------- | ---------------------------- |
| Platform commission/fees | **18%** | 9962 (retail trade services) |
-| Educational services | **18%** | 999293 |
+| Educational services | **18%** | 999293 |
Commission invoices to consultants should use SAC 9962 for marketplace commission.
@@ -78,34 +78,34 @@ Commission invoices to consultants should use SAC 9962 for marketplace commissio
### Section 194-O (TDS by E-Commerce Operator)
-| Parameter | Value |
-|-----------|-------|
-| TDS Rate (from Oct 1, 2024) | **0.1%** (reduced from 1%) |
-| Threshold (Individual/HUF) | Rs 5 lakh gross sales/year (if PAN/Aadhaar furnished) |
-| Threshold (Companies/Firms/LLP) | **No threshold** — TDS from first rupee |
-| No PAN/Aadhaar rate | **5%** (per Section 206AA) |
-| Calculated on | Gross amount (including GST, shipping charges) |
-| Filing | Quarterly in **Form 26Q** (residents) or **27Q** (non-residents) |
+| Parameter | Value |
+| ------------------------------- | ------------------------------------------------------------------------------------------------- |
+| TDS Rate (from Oct 1, 2024) | **0.1%** (reduced from 1%) |
+| Threshold (Individual/HUF) | Rs 5 lakh gross sales/year (if PAN/Aadhaar furnished) |
+| Threshold (Companies/Firms/LLP) | **No threshold** — TDS from first rupee |
+| No PAN/Aadhaar rate | **5%** (per Section 206AA) |
+| Calculated on | Gross amount (including GST, shipping charges) |
+| Filing | Quarterly in **Form 140** (formerly 26Q, residents) or **Form 144** (formerly 27Q, non-residents) |
### Section 194J (Professional Services TDS)
-| Parameter | FY 2025-26 |
-|-----------|-----------|
-| Threshold | Rs 50,000/year per consultant |
-| Rate (Professional services) | **10%** |
-| Rate (Technical services) | **2%** |
-| No PAN rate | **20%** |
+| Parameter | FY 2025-26 |
+| ---------------------------- | ----------------------------- |
+| Threshold | Rs 50,000/year per consultant |
+| Rate (Professional services) | **10%** |
+| Rate (Technical services) | **2%** |
+| No PAN rate | **20%** |
### TDS Filing Calendar
-| Due Date | Action | Form |
-|----------|--------|------|
-| 7th of each month | TDS deposit | Challan 281 |
-| July 31 | Q1 return (Apr–Jun) | 26Q |
-| October 31 | Q2 return (Jul–Sep) | 26Q |
-| January 31 | Q3 return (Oct–Dec) | 26Q |
-| May 31 | Q4 return (Jan–Mar) | 26Q |
-| Within 15 days of quarterly filing due date | Issue TDS certificate | Form 16A |
+| Due Date | Action | Form |
+| ------------------------------------------- | --------------------- | ----------------------- |
+| 7th of each month | TDS deposit | Challan 281 |
+| July 31 | Q1 return (Apr–Jun) | Form 140 |
+| October 31 | Q2 return (Jul–Sep) | Form 140 |
+| January 31 | Q3 return (Oct–Dec) | Form 140 |
+| May 31 | Q4 return (Jan–Mar) | Form 140 |
+| Within 15 days of quarterly filing due date | Issue TDS certificate | Form 131 (formerly 16A) |
Late filing penalty: Rs 200/day (capped at total TDS amount).
@@ -119,11 +119,11 @@ Late filing penalty: Rs 200/day (capped at total TDS amount).
> **WARNING**: Commission/brokerage income may be excluded from Section 44AD presumptive taxation. Persons earning commission or brokerage income, or carrying on agency businesses, are specifically excluded from 44AD in some interpretations.
-| Parameter | Detail |
-|-----------|--------|
-| Turnover limit | Rs 3 crore (if 95%+ digital receipts) or Rs 2 crore |
-| Deemed profit | 6% (digital) or 8% (cash) of turnover |
-| Lock-in | 5 consecutive years once opted |
+| Parameter | Detail |
+| ----------------- | --------------------------------------------------------------- |
+| Turnover limit | Rs 3 crore (if 95%+ digital receipts) or Rs 2 crore |
+| Deemed profit | 6% (digital) or 8% (cash) of turnover |
+| Lock-in | 5 consecutive years once opted |
| NOT available for | Companies, LLPs, persons earning commission/brokerage (debated) |
**Impact**: If a CA rules that marketplace commission income disqualifies us from 44AD, the "0% tax up to Rs 50L" advantage of Sole Proprietorship in the CFO Master Plan shrinks significantly. **This needs urgent CA verification before finalizing entity structure.**
@@ -156,12 +156,12 @@ Late filing penalty: Rs 200/day (capped at total TDS amount).
### International Consultant Payouts
-| Method | Speed | Cost | Notes |
-|--------|-------|------|-------|
-| Wise | 1–3 days | ~1.6–1.7% + $2 | Good UI, mid-market FX rate |
-| PayPal | 1–3 days | Up to 4.4% + FX markup | Widest reach, highest cost |
-| Payoneer | 2–5 days | 2% FX markup | Popular for freelancer payouts |
-| SWIFT/Wire | 3–7 days | Rs 1,000+ per transfer | Costliest, most traditional |
+| Method | Speed | Cost | Notes |
+| ---------- | -------- | ---------------------- | ------------------------------ |
+| Wise | 1–3 days | ~1.6–1.7% + $2 | Good UI, mid-market FX rate |
+| PayPal | 1–3 days | Up to 4.4% + FX markup | Widest reach, highest cost |
+| Payoneer | 2–5 days | 2% FX markup | Popular for freelancer payouts |
+| SWIFT/Wire | 3–7 days | Rs 1,000+ per transfer | Costliest, most traditional |
For Section 195 TDS on payments to non-resident consultants, rates vary by DTAA (Double Taxation Avoidance Agreement). Requires 15CA/15CB certificates for outward remittances.
@@ -173,12 +173,12 @@ For Section 195 TDS on payments to non-resident consultants, rates vary by DTAA
**Almost certainly NO**, as long as we use a licensed PA (Razorpay) rather than directly handling payment flows.
-| Scenario | PA License Needed? |
-|----------|-------------------|
-| Use Razorpay to collect payments, they settle to our account | **No** — we are a merchant |
-| Use Razorpay Route to split payments to sellers | **No** — Razorpay is the PA |
-| Collect payments into our own pool/escrow and distribute | **Possibly YES** |
-| Directly handle card data or bank details | **YES** |
+| Scenario | PA License Needed? |
+| ------------------------------------------------------------ | --------------------------- |
+| Use Razorpay to collect payments, they settle to our account | **No** — we are a merchant |
+| Use Razorpay Route to split payments to sellers | **No** — Razorpay is the PA |
+| Collect payments into our own pool/escrow and distribute | **Possibly YES** |
+| Directly handle card data or bank details | **YES** |
PA license requirements (for reference): Rs 15 crore net worth at application, Rs 25 crore within 3 years, escrow account with Scheduled Commercial Bank.
@@ -188,14 +188,14 @@ PA license requirements (for reference): Rs 15 crore net worth at application, R
### From Day 1
-| Obligation | Rate | Filing |
-|------------|------|--------|
-| GST Registration (as ECO, no turnover threshold) | N/A | Must register before launch |
-| TCS collection on net taxable supplies | 0.5% | GSTR-8 by 10th monthly |
-| TDS u/s 194-O on gross e-commerce payments | 0.1% | Form 26Q quarterly |
-| TDS u/s 194J on consultant payouts > Rs 50K/yr | 10% | Form 26Q quarterly |
-| GST on platform commission | 18% | GSTR-1/GSTR-3B monthly |
-| Export zero-rating (international buyers) | 0% | Verify buyer location |
+| Obligation | Rate | Filing |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------- |
+| GST Registration (as ECO, no turnover threshold) | N/A | Must register before launch |
+| TCS collection on net taxable supplies — **CA-gated, not applicable today.** The platform bills as principal under ADR 26, so Section 52 TCS does not apply and no TCS is collected; this row is a facilitator-model reference that only becomes live if a chartered accountant overturns that decision. | 0.5% | GSTR-8 by 10th monthly (facilitator model only) |
+| TDS u/s 194-O on gross e-commerce payments | 0.1% | Form 140 quarterly |
+| TDS u/s 194J on consultant payouts > Rs 50K/yr | 10% | Form 140 quarterly |
+| GST on platform commission | 18% | GSTR-1/GSTR-3B monthly |
+| Export zero-rating (international buyers) | 0% | Verify buyer location |
### For International Transactions
@@ -214,33 +214,33 @@ PA license requirements (for reference): Rs 15 crore net worth at application, R
## The Jargon Decoder
-| Scary Term | What It Actually Means |
-|------------|----------------------|
-| GST (18%) | Sales tax. We add it on top of the price for Indian buyers. |
-| Zero-rated export | Fancy way of saying "no tax for international buyers" |
-| TDS (Section 194J) | When we pay consultants, we hold back 10% as their prepaid income tax and send it to the government. Only kicks in after ₹50K/year. |
-| PAN | Like a tax SSN. If consultant doesn't give us one, we deduct 20% instead of 10% (penalty rate). |
-| eFIRC | A receipt proving we received foreign money legally. Razorpay generates this automatically. We don't write code for it. |
-| LUT (Letter of Undertaking) | A form filed with GST authorities saying "we export services, don't charge us GST on those." One-time filing, not code. |
-| SAC Code (999293) | Category code for "consulting services" — goes on invoices. Already hardcoded. |
-| Form 26Q | Quarterly report to government: "here's all the TDS we deducted." Our admin API provides the data, CA files the form. |
-| FEMA | Foreign exchange law. As long as we use Razorpay (RBI-licensed), we're compliant. Not our problem in code. |
-| TCS | Tax Collected at Source — 0.5% the platform collects from supplier on behalf of government. Different from TDS. |
-| Section 194-O | E-commerce specific TDS — 0.1% on gross sales. Separate from 194J. |
-| PA-CB | Payment Aggregator — Cross Border license from RBI. Needed to process international payments. Razorpay has one. |
+| Scary Term | What It Actually Means |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| GST (18%) | Sales tax. We add it on top of the price for Indian buyers. |
+| Zero-rated export | Fancy way of saying "no tax for international buyers" |
+| TDS (Section 194J) | When we pay consultants, we hold back 10% as their prepaid income tax and send it to the government. Only kicks in after ₹50K/year. |
+| PAN | Like a tax SSN. If consultant doesn't give us one, we deduct 20% instead of 10% (penalty rate). |
+| eFIRC | A receipt proving we received foreign money legally. Razorpay generates this automatically. We don't write code for it. |
+| LUT (Letter of Undertaking) | A form filed with GST authorities saying "we export services, don't charge us GST on those." One-time filing, not code. |
+| SAC Code (999293) | The consumer invoice model's default classification code (`ConsumerInvoice.sacCode`), with **998311** as the alternative pending the CA's answer (#1369) — both carry 18% GST. Goes on invoices. |
+| Form 140 (formerly 26Q) | Quarterly report to government: "here's all the TDS we deducted." Our admin API provides the data, CA files the form. |
+| FEMA | Foreign exchange law. As long as we use Razorpay (RBI-licensed), we're compliant. Not our problem in code. |
+| TCS | Tax Collected at Source — 0.5% the platform would collect from supplier on behalf of government under the facilitator model. CA-gated and not applicable today because the platform bills as principal (ADR 26). Different from TDS. |
+| Section 194-O | E-commerce specific TDS — 0.1% on gross sales. Separate from 194J. |
+| PA-CB | Payment Aggregator — Cross Border license from RBI. Needed to process international payments. Razorpay has one. |
---
## Recommended Financial SaaS Stack
-| Need | Recommendation | Cost | Why |
-|------|---------------|------|-----|
-| Accounting | Zoho Books | Rs 1,249/mo | GST-compliant, auto-reconciliation with Razorpay, TDS management, multi-currency |
-| GST Filing | ClearTax or Zoho Books built-in | Varies | Auto GSTR-1/3B/8 filing, e-invoicing |
-| TDS Filing | RazorpayX (auto-TDS) + ClearTax | Included/varies | RazorpayX auto-deducts/deposits TDS, generates Form 16A |
-| Invoicing | Zoho Invoice (free up to 1,000/yr) or built-in | Free–low | GST-compliant invoices with SAC codes |
-| Reconciliation | Razorpay Dashboard + Zoho Books sync | Included | Auto-match payments to invoices |
-| International payouts | Wise Business (later) | ~1.6% per transfer | Best FX rates, API available, for paying international consultants |
+| Need | Recommendation | Cost | Why |
+| --------------------- | ---------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Accounting | Zoho Books | Rs 1,249/mo | GST-compliant, auto-reconciliation with Razorpay, TDS management, multi-currency |
+| GST Filing | ClearTax or Zoho Books built-in | Varies | Auto GSTR-1/3B filing, e-invoicing; GSTR-8 tooling is conditional on the facilitator model reversing ADR 26 and is not needed today |
+| TDS Filing | RazorpayX (auto-TDS) + ClearTax | Included/varies | RazorpayX auto-deducts/deposits TDS, generates Form 131 |
+| Invoicing | Zoho Invoice (free up to 1,000/yr) or built-in | Free–low | GST-compliant invoices with SAC codes |
+| Reconciliation | Razorpay Dashboard + Zoho Books sync | Included | Auto-match payments to invoices |
+| International payouts | Wise Business (later) | ~1.6% per transfer | Best FX rates, API available, for paying international consultants |
### Phased Approach
@@ -279,7 +279,7 @@ PA license requirements (for reference): Rs 15 crore net worth at application, R
- [ ] EU VAT registration (only if EU sales exceed thresholds)
- [ ] Australian GST (only if AU sales > AUD 75K/year)
- [ ] International consultant payouts (provider not yet selected; Section 195 withholding is unimplemented, see payout-service.ts)
-- [ ] Form 16A auto-generation for consultants (annual TDS certificate)
+- [ ] Form 131 (formerly 16A) auto-generation for consultants (annual TDS certificate)
### 🚫 NOT Our Problem
@@ -302,15 +302,16 @@ PA license requirements (for reference): Rs 15 crore net worth at application, R
These are **employment** obligations, not platform obligations. They have nothing to do with your SaaS code.
-| Obligation | What It Is | When Mandatory | Applies to Consultants? |
-|------------|-----------|----------------|------------------------|
-| **PF (EPF)** | Retirement savings — employer pays 12% of basic salary | 20+ employees | No — independent contractors |
-| **ESI** | Health insurance for employees earning < Rs 21,000/month — employer pays 3.25% | 10+ employees | No — independent contractors |
-| **Gratuity** | Bonus after 5 years continuous service — 15 days salary per year of service | 10+ employees | No — independent contractors |
+| Obligation | What It Is | When Mandatory | Applies to Consultants? |
+| ------------ | ------------------------------------------------------------------------------ | -------------- | ---------------------------- |
+| **PF (EPF)** | Retirement savings — employer pays 12% of basic salary | 20+ employees | No — independent contractors |
+| **ESI** | Health insurance for employees earning < Rs 21,000/month — employer pays 3.25% | 10+ employees | No — independent contractors |
+| **Gratuity** | Bonus after 5 years continuous service — 15 days salary per year of service | 10+ employees | No — independent contractors |
### Why Consultants Are Not Employees
Platform consultants are independent contractors because they:
+
- Set their own prices
- Set their own schedules
- Use their own expertise
@@ -335,14 +336,14 @@ These items are for your CA or legal advisor, not engineering.
### Before Launch (Priority)
-| # | Action | Impact | Estimated Cost |
-|---|--------|--------|---------------|
-| 1 | CA opinion: "Are we an e-commerce operator under Section 2(45)?" | Determines GST registration, TCS, GSTR-8 obligations | Rs 5–10K one-time |
-| 2 | CA opinion: "Which TDS section — 194J or 194-O or both?" | Different rates and thresholds | Part of same consultation |
-| 3 | CA opinion: "Does 44AD apply to marketplace commission income?" | Determines if Sole Prop tax advantage holds | Part of same consultation |
-| 4 | GST registration (if CA advises) | Must be done before first payment | Rs 2–5K |
-| 5 | LUT filing for export zero-rating | Must be done before first international transaction | Free (online filing) |
-| 6 | Monthly CA retainer for GST filing | GSTR-1, GSTR-3B, GSTR-8 (if applicable) | Rs 2–5K/month |
+| # | Action | Impact | Estimated Cost |
+| --- | ---------------------------------------------------------------- | ---------------------------------------------------- | ------------------------- |
+| 1 | CA opinion: "Are we an e-commerce operator under Section 2(45)?" | Determines GST registration, TCS, GSTR-8 obligations | Rs 5–10K one-time |
+| 2 | CA opinion: "Which TDS section — 194J or 194-O or both?" | Different rates and thresholds | Part of same consultation |
+| 3 | CA opinion: "Does 44AD apply to marketplace commission income?" | Determines if Sole Prop tax advantage holds | Part of same consultation |
+| 4 | GST registration (if CA advises) | Must be done before first payment | Rs 2–5K |
+| 5 | LUT filing for export zero-rating | Must be done before first international transaction | Free (online filing) |
+| 6 | Monthly CA retainer for GST filing | GSTR-1, GSTR-3B, GSTR-8 (if applicable) | Rs 2–5K/month |
### Immediate Non-Code Tasks
diff --git a/docs/guides/cron-setup.md b/docs/guides/cron-setup.md
index 69920a6b0..a62fd924f 100644
--- a/docs/guides/cron-setup.md
+++ b/docs/guides/cron-setup.md
@@ -4,6 +4,24 @@
This document explains how to set up automated cleanup of abandoned payments in the system.
+## Running the Netlify scheduled ticker locally
+
+`netlify/functions/cron-tick.mts` is the scheduled function that drives the ten latency-sensitive `/api/cleanup/*` sweeps every five minutes in production, because GitHub Actions was measured delivering a sub-hourly schedule roughly once every hundred minutes rather than on its declared cadence (ADR 22, ADR 27). It needs two environment variables to do anything: `CRON_SECRET`, the same bearer token every `/api/cleanup/*` route already requires, and either `URL` (which Netlify sets automatically in every deployed context) or its local override, `CRON_TICK_BASE_URL`, pointed at wherever the Next app is actually listening.
+
+Netlify never fires a scheduled function on its declared cadence in local development, and a scheduled function cannot be invoked directly by URL either, so `netlify dev` alone will not produce a tick. Start `next dev` (or `netlify dev`, which manages one for you) with `CRON_TICK_BASE_URL` pointed at wherever it is listening, then invoke the function once through the CLI and read the same `{ event: "cron-tick", ok, lockHeld, failed, durationMs }` body it logs in production:
+
+```bash
+CRON_SECRET=your-local-secret \
+CRON_TICK_BASE_URL=http://localhost:8888 \
+netlify dev
+```
+
+```bash
+netlify functions:invoke cron-tick
+```
+
+A `lockHeld` entry for a target means `withCronLock` is already held by another run of that job — expected under a concurrent GitHub Actions run, and not a failure. A `failed` entry means the route answered something other than `200`, `207` or `409`, which is worth investigating the same way any other cleanup-route failure is.
+
## Cleanup Endpoint
**URL**: `/api/cleanup/abandoned-payments`
diff --git a/docs/maintenance/04-cron-jobs-reference.md b/docs/maintenance/04-cron-jobs-reference.md
index 9cb4b685a..046070386 100644
--- a/docs/maintenance/04-cron-jobs-reference.md
+++ b/docs/maintenance/04-cron-jobs-reference.md
@@ -20,14 +20,24 @@ Building that guard immediately turned up a second, larger instance of the same
Two things now prevent a repeat. The Supabase clients and storage primitives a job needs live in `lib/supabase-storage-core.ts`, which carries no marker, and `lib/supabase.ts` re-exports them so application code is unchanged and still gets its client-import guard. And `__tests__/maintenance/workflow-import-env.test.ts` re-derives every scheduled workflow's import graph on each CI run, failing when one reaches a `server-only` module or when a job that reaches the Supabase client module is not given the two environment variables that module throws without.
+## What changed in #1356
+
+The 2026-09-03 financial audit re-measured GitHub Actions' sub-hourly schedules and confirmed the finding ADR 22 first recorded: an every-minute schedule delivers roughly once every hundred minutes rather than once a minute, because GitHub throttles scheduled workflows rather than dropping them outright. `netlify/functions/cron-tick.mts` closes that gap for the ten sweeps where the delay matters most. It is a Netlify scheduled function that fires every five minutes and POSTs each of the following, relative to `/api/cleanup/`, with a `CRON_SECRET` bearer token and a six-second per-target timeout: `sweep-stuck-webhook-events`, `cascade-refund-earnings`, `reconcile-refunds`, `abandoned-payments`, `reconcile-payment-status`, `reconcile-orphaned-confirmations`, `sweep-orphaned-topup-captures`, `dispatch-outbound-webhooks`, `sync-payment-earnings`, and `release-earnings`. ADR 27 records why this is a scheduler fix rather than a new outbox table: the durable state an outbox exists to provide already lives on the domain rows — `Payment`, `Appointment`, `Refund`, `WalletTopUp`, `WebhookEvent`, `OutboundWebhookDelivery`, `FailedEmail` — that these sweeps already walk.
+
+Every tick request carries a `?limit=`, and all ten routes above read it as an optional cap on the batch a single run may touch, defaulting to today's unbounded behaviour when the parameter is absent, so a nightly GitHub Actions run still processes the whole backlog while a five-minute tick stays inside its own budget. The default the ticker sends is fifty, but a target may override it: `abandoned-payments` is sent ten, because its per-row cost includes a gateway cancel round trip rather than a database write alone, and at fifty it could not finish inside the six-second per-target timeout (#1459). Whatever a smaller bite leaves behind is picked up by the unbounded GitHub Actions run.
+
+A tick and a GitHub Actions run of the same job cannot both proceed: both go through the same `withCronLock` every entrypoint already shares, so the loser answers 409. The ticker records a 409 as `lockHeld`, not a failure, because the run that lost the lock is a run that did not need to happen — the winner is already doing the same work. Only a response outside `200`, `207` and `409` counts as `failed`. `docs/guides/cron-setup.md` covers running the ticker locally.
+
+GitHub Actions is unchanged by this: it still owns every daily and weekly business cron, and for the ten sweeps above it becomes the backstop that runs regardless of ticker health rather than the primary schedule.
+
## The fleet at a glance
| Property | Count |
| --------------------------------------- | ----- |
| Scheduled workflows | 67 |
| Locked via `withCronLock` | 63 |
-| — fail-closed | 28 |
-| — fail-open | 35 |
+| — fail-closed | 29 |
+| — fail-open | 34 |
| Locked by a bespoke Redis lock | 2 |
| Deliberately unlocked | 2 |
| On the financial list | 20 |
@@ -37,7 +47,7 @@ Two things now prevent a repeat. The Supabase clients and storage primitives a j
Every scheduled workflow appears exactly once, grouped by the part of the product it serves. The columns mean the following.
-**Schedule** is the raw cron expression in UTC, exactly as GitHub receives it. Treat it as an upper bound rather than a promise: GitHub throttles scheduled workflows under load, and a job asking for every minute has been measured delivering roughly every 2.75 hours. Minutes are deliberately staggered across the fleet so that simultaneous starts do not stampede the Supavisor connection pool, which `scripts/ci/check-workflow-hygiene.ts` enforces.
+**Schedule** is the raw cron expression in UTC, exactly as GitHub receives it. Treat it as an upper bound rather than a promise, not the delivered cadence (ADR 22): GitHub throttles scheduled workflows under load, and a job asking for every minute has been measured delivering roughly once every hundred minutes. For the ten money sweeps the Netlify ticker drives — see [What changed in #1356](#what-changed-in-1356) below — the schedule column is no longer the cadence that actually holds; the ticker's five-minute interval is (ADR 27). Minutes are deliberately staggered across the fleet so that simultaneous starts do not stampede the Supavisor connection pool, which `scripts/ci/check-workflow-hygiene.ts` enforces.
**Entrypoint** is the file the workflow executes. Where a second path appears beneath it, the first is a thin `jobs/**` wrapper holding the GitHub Actions plumbing — output variables, notice annotations, Sentry bootstrap — and the second is the `scripts/**` core holding the actual logic. The lock normally lives on the core so that every entry point inherits it, including the HTTP routes under `app/api/cleanup/`.
@@ -51,34 +61,42 @@ Every scheduled workflow appears exactly once, grouped by the part of the produc
These jobs move bookings through their lifecycle and hand back the slots that nobody paid for. They are the fleet's most visible half: when one of them stops, consultees see availability that does not exist and consultants see sessions that never close.
-| Workflow | Schedule (UTC) | Entrypoint | Lock | Financial | Mutates | During maintenance |
-| -------------------------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------ | --------- | ---------------------------------------------------------------------------------------- | ------------------ |
-| **Auto-Complete Appointments**
`auto-complete-appointments` | `7 * * * *` | `jobs/appointments/auto-complete-appointments.ts`
→ `scripts/appointments/auto-complete-appointments.ts` | open | no | `Consultation`, `Subscription`, `Class`, `TrialSession` → COMPLETED; `ActivityLog`; Novu | Skips: OFFLINE |
-| **Cleanup Invalid Appointments**
`cleanup-invalid-appointments` | `12 * * * *` | `jobs/appointments/cleanup-invalid-appointments.ts`
→ `scripts/appointments/cleanup-invalid-appointments.ts` | open | no | Duplicate and invalid `Consultation`/`Subscription` cancelled, their slots released | Skips: OFFLINE |
-| **Cleanup Stale Pending Consultations**
`cleanup-stale-pending-consultations` | `37 * * * *` | `jobs/appointments/cleanup-stale-pending-consultations.ts`
→ `scripts/appointments/cleanup-stale-pending-consultations.ts` | open | no | Stale PENDING `Consultation` cancelled, reserved slots released | Skips: OFFLINE |
-| **Cleanup Tentative Slots**
`cleanup-tentative-slots` | `38 */2 * * *` | `jobs/appointments/cleanup-tentative-slots.ts`
→ `scripts/appointments/cleanup-tentative-slots.ts` | open | no | Tentative `SlotOfAppointment` reservations released | Skips: OFFLINE |
-| **Detect Consultant No-Shows**
`detect-consultant-no-shows` | `57 * * * *` | `jobs/appointments/detect-consultant-no-shows.ts`
→ `scripts/appointments/detect-consultant-no-shows.ts` | closed | no | `Consultation` no-show status, slot release, Novu notifications | Skips: OFFLINE |
-| **Expire Reschedule Proposals**
`expire-reschedule-proposals` | `45 * * * *` | `jobs/appointments/expire-reschedule-proposals.ts`
→ `scripts/appointments/expire-reschedule-proposals.ts` | open | no | Expired `RescheduleRequest` proposals | Skips: OFFLINE |
-| **Expire Stale Requests**
`expire-stale-requests` | `20 1 * * *` | `jobs/appointments/expire-stale-requests.ts`
→ `scripts/appointments/expire-stale-requests.ts` | open | no | Stale `Consultation` and `Subscription` requests expired | Skips: OFFLINE |
-| **Expire Unpaid Trials**
`expire-unpaid-trials` | `40 * * * *` | `jobs/trials/expire-unpaid-trials.ts`
→ `scripts/trials/expire-unpaid-trials.ts` | open | no | `TrialSession` expiry, which frees the held trial slot | Skips: OFFLINE |
-| **Reconcile Orphaned Meeting Sessions**
`reconcile-orphaned-sessions` | `25,55 * * * *` | `jobs/meetings/reconcile-orphaned-sessions.ts` | open | no | `MeetingSession` closure and slot state, reconciled against Stream calls | Skips: OFFLINE |
-| **Reconcile Slot Availability**
`reconcile-slot-availability` | `32 * * * *` | `jobs/appointments/reconcile-slot-availability.ts`
→ `scripts/appointments/reconcile-slot-availability.ts` | open | no | `SlotOfAppointment` availability re-derived from live bookings | Skips: OFFLINE |
-| **Send Appointment Reminders**
`send-appointment-reminders` | `47 * * * *` | `jobs/appointments/send-appointment-reminders.ts`
→ `scripts/appointments/send-appointment-reminders.ts` | open | no | Reads only; sends Novu reminders behind a Redis dedup key | Skips: OFFLINE |
+| Workflow | Schedule (UTC) | Entrypoint | Lock | Financial | Mutates | During maintenance |
+| -------------------------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------ | --------- | -------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| **Auto-Complete Appointments**
`auto-complete-appointments` | `7 * * * *` | `jobs/appointments/auto-complete-appointments.ts`
→ `scripts/appointments/auto-complete-appointments.ts` | open | no | `Consultation`, `Subscription`, `Class`, `TrialSession` → COMPLETED; `ActivityLog`; Novu | Skips: OFFLINE |
+| **Cleanup Invalid Appointments**
`cleanup-invalid-appointments` | `12 * * * *` | `jobs/appointments/cleanup-invalid-appointments.ts`
→ `scripts/appointments/cleanup-invalid-appointments.ts` | open | no | Duplicate and invalid `Consultation`/`Subscription` cancelled, their slots released | Skips: OFFLINE |
+| **Cleanup Stale Pending Consultations**
`cleanup-stale-pending-consultations` | `37 * * * *` | `jobs/appointments/cleanup-stale-pending-consultations.ts`
→ `scripts/appointments/cleanup-stale-pending-consultations.ts` | open | no | Stale PENDING `Consultation` cancelled, reserved slots released | Skips: OFFLINE |
+| **Cleanup Tentative Slots**
`cleanup-tentative-slots` | `38 */2 * * *` | `jobs/appointments/cleanup-tentative-slots.ts`
→ `scripts/appointments/cleanup-tentative-slots.ts` | open | no | Tentative `SlotOfAppointment` reservations released | Skips: OFFLINE |
+| **Detect Consultant No-Shows**
`detect-consultant-no-shows` | `57 * * * *` | `jobs/appointments/detect-consultant-no-shows.ts`
→ `scripts/appointments/detect-consultant-no-shows.ts` | closed | no | `Consultation` no-show status, slot release, Novu notifications | Skips: OFFLINE |
+| **Expire Reschedule Proposals**
`expire-reschedule-proposals` | `45 * * * *` | `jobs/appointments/expire-reschedule-proposals.ts`
→ `scripts/appointments/expire-reschedule-proposals.ts` | open | no | Expired `RescheduleRequest` proposals | Skips: OFFLINE |
+| **Expire Stale Requests**
`expire-stale-requests` | `20 1 * * *` | `jobs/appointments/expire-stale-requests.ts`
→ `scripts/appointments/expire-stale-requests.ts` | closed | no | Stale `Consultation` and `Subscription` requests expired, refunding SUCCEEDED payments through the refund front door | Skips: OFFLINE |
+| **Expire Unpaid Trials**
`expire-unpaid-trials` | `40 * * * *` | `jobs/trials/expire-unpaid-trials.ts`
→ `scripts/trials/expire-unpaid-trials.ts` | open | no | `TrialSession` expiry, which frees the held trial slot | Skips: OFFLINE |
+| **Reconcile Orphaned Meeting Sessions**
`reconcile-orphaned-sessions` | `25,55 * * * *` | `jobs/meetings/reconcile-orphaned-sessions.ts` | open | no | `MeetingSession` closure and slot state, reconciled against Stream calls | Skips: OFFLINE |
+| **Reconcile Slot Availability**
`reconcile-slot-availability` | `32 * * * *` | `jobs/appointments/reconcile-slot-availability.ts`
→ `scripts/appointments/reconcile-slot-availability.ts` | open | no | `SlotOfAppointment` availability re-derived from live bookings | Skips: OFFLINE |
+| **Send Appointment Reminders**
`send-appointment-reminders` | `47 * * * *` | `jobs/appointments/send-appointment-reminders.ts`
→ `scripts/appointments/send-appointment-reminders.ts` | open | no | Reads only; sends Novu reminders behind a Redis dedup key | Skips: OFFLINE |
## Money in
Everything that reconciles what a consultee paid against what the gateway believes. Every job here that changes state is fail-closed, because the gateway is the authority and acting twice on its record is how a refund gets issued twice; the deadline alerter is the one exception, and it only reads.
-| Workflow | Schedule (UTC) | Entrypoint | Lock | Financial | Mutates | During maintenance |
-| -------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- | ------ | --------- | --------------------------------------------------------------------------------------------------------------- | ------------------------- |
-| **Alert Dispute Deadlines**
`alert-dispute-deadlines` | `2 * * * *` | `jobs/disputes/alert-dispute-deadlines.ts`
→ `scripts/disputes/alert-dispute-deadlines.ts` | open | no | Reads only; logs deadline alerts | Skips: OFFLINE |
-| **Cascade Refund to Earnings**
`cascade-refund-earnings` | `1-59/15 * * * *` | `jobs/refunds/cascade-refund-earnings.ts`
→ `scripts/refunds/cascade-refund-earnings.ts` | closed | yes | `Refund.cascadedAt`, `PaymentLeg`, consultant and org earnings, payout clawback, ledger | Skips: OFFLINE + DEGRADED |
-| **Cleanup Abandoned Payments**
`cleanup-abandoned-payments` | `6-59/15 * * * *` | `jobs/payments/cleanup-abandoned-payments.ts`
→ `scripts/payments/cleanup-abandoned-payments.ts` | closed | yes | `Payment` → EXPIRED, tentative slots released, `Consultation`/`Subscription` deleted, referral credits restored | Skips: OFFLINE + DEGRADED |
-| **Handle Lost Disputes**
`handle-lost-disputes` | `8 */6 * * *` | `jobs/disputes/handle-lost-disputes.ts`
→ `scripts/disputes/handle-lost-disputes.ts` | closed | yes | Consultant and org earnings refund amounts, `TDSRecord` reversals | Skips: OFFLINE + DEGRADED |
-| **Reconcile Disputes**
`reconcile-disputes` | `28 */6 * * *` | `jobs/disputes/reconcile-disputes.ts`
→ `scripts/disputes/reconcile-disputes.ts` | closed | yes | `Dispute` status reconciled against gateway records | Skips: OFFLINE + DEGRADED |
-| **Reconcile Orphaned Confirmations**
`reconcile-orphaned-confirmations` | `13-59/30 * * * *` | `jobs/payments/reconcile-orphaned-confirmations.ts`
→ `scripts/payments/reconcile-orphaned-confirmations.ts` | closed | no | `SlotOfAppointment.isTentative` and `Consultation`/`Subscription` approval status | Skips: OFFLINE |
-| **Reconcile Payment Status**
`reconcile-payment-status` | `18-59/30 * * * *` | `jobs/payments/reconcile-payment-status.ts`
→ `scripts/payments/reconcile-payment-status.ts` | closed | yes | `Payment` status reconciled against gateway records | Skips: OFFLINE + DEGRADED |
-| **Reconcile Pending Refunds**
`reconcile-pending-refunds` | `11-59/15 * * * *` | `jobs/refunds/reconcile-pending-refunds.ts`
→ `scripts/refunds/reconcile-pending-refunds.ts` | closed | yes | `Refund` status reconciled against the gateway; Novu notices | Skips: OFFLINE + DEGRADED |
+| Workflow | Schedule (UTC) | Entrypoint | Lock | Financial | Mutates | During maintenance |
+| -------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- | ------ | --------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| **Alert Dispute Deadlines**
`alert-dispute-deadlines` | `2 * * * *` | `jobs/disputes/alert-dispute-deadlines.ts`
→ `scripts/disputes/alert-dispute-deadlines.ts` | open | no | Reads only; logs deadline alerts | Skips: OFFLINE |
+| **Cascade Refund to Earnings**
`cascade-refund-earnings` | `1-59/15 * * * *` | `jobs/refunds/cascade-refund-earnings.ts`
→ `scripts/refunds/cascade-refund-earnings.ts` | closed | yes | `Refund.cascadedAt`, `PaymentLeg`, consultant and org earnings, payout clawback, ledger | Skips: OFFLINE + DEGRADED |
+| **Cleanup Abandoned Payments**
`cleanup-abandoned-payments` | `6-59/15 * * * *` | `jobs/payments/cleanup-abandoned-payments.ts`
→ `scripts/payments/cleanup-abandoned-payments.ts` | closed | yes | `Payment` → EXPIRED, tentative slots released, `Consultation`/`Subscription` deleted, referral credits restored | Skips: OFFLINE + DEGRADED |
+| **Handle Lost Disputes**
`handle-lost-disputes` | `8 */6 * * *` | `jobs/disputes/handle-lost-disputes.ts`
→ `scripts/disputes/handle-lost-disputes.ts` | closed | yes | Consultant and org earnings refund amounts, `TDSRecord` reversals | Skips: OFFLINE + DEGRADED |
+| **Reconcile Disputes**
`reconcile-disputes` | `28 */6 * * *` | `jobs/disputes/reconcile-disputes.ts`
→ `scripts/disputes/reconcile-disputes.ts` | closed | yes | `Dispute` status reconciled against gateway records | Skips: OFFLINE + DEGRADED |
+| **Reconcile Orphaned Confirmations**
`reconcile-orphaned-confirmations` | `13-59/30 * * * *` | `jobs/payments/reconcile-orphaned-confirmations.ts`
→ `scripts/payments/reconcile-orphaned-confirmations.ts` | closed | no | `SlotOfAppointment.isTentative`, `Consultation`/`Subscription` approval status, and `Appointment.chatChannelEnsuredAt` | Skips: OFFLINE |
+| **Reconcile Payment Status**
`reconcile-payment-status` | `18-59/30 * * * *` | `jobs/payments/reconcile-payment-status.ts`
→ `scripts/payments/reconcile-payment-status.ts` | closed | yes | `Payment` status reconciled against gateway records | Skips: OFFLINE + DEGRADED |
+| **Reconcile Pending Refunds**
`reconcile-pending-refunds` | `11-59/15 * * * *` | `jobs/refunds/reconcile-pending-refunds.ts`
→ `scripts/refunds/reconcile-pending-refunds.ts` | closed | yes | `Refund` status reconciled against the gateway; Novu notices | Skips: OFFLINE + DEGRADED |
+
+`cleanup-abandoned-payments` cancels each abandoned payment's gateway intent before it expires the row, and the expiry no longer waits on that cancel succeeding. A cancel that fails is recorded in `errors` and counted in `errorCount`, so the run reports `success: false` and the HTTP twin at `/api/cleanup/abandoned-payments` answers 500 rather than the 200 it used to force; the payment still moves PENDING→EXPIRED through its CAS in the same transaction that hands back the referral credits and releases the hold. Skipping that write was how a Payment came to sit PENDING for ever beside a slot that had already been released — a row no later sweep could see, because nothing about it still looked abandoned (#1464). The Stripe arm also respects the #1386 fence: with `STRIPE_ENABLED` set to anything other than `true` the sweep makes no gateway call at all and logs one line per run saying so, and when the fence is open an intent Stripe cannot find, or one that is already terminal, counts as nothing to cancel rather than as a failure.
+
+`reconcile-disputes` only reaches a gateway for Stripe disputes, and Stripe is fenced off in production, so when `STRIPE_ENABLED` is anything other than `true` the sweep leaves those disputes alone and counts them as `skippedFenced` rather than failing the run on a gateway we deliberately turned off (#1459); Razorpay disputes were already routed to manual dashboard review and are counted separately. Its HTTP twin no longer forces a 200 either, so a run that genuinely failed now answers 500 like every other sweep.
+
+`reconcile-orphaned-confirmations` runs two passes per invocation, because a capture can fail in two independent places. The first is the original #830 sweep: it finds `SUCCEEDED` payments whose slots are still tentative and re-runs the confirmation under the webhook's own Serializable discipline. The second, added by #1356, repairs the post-capture chat leg — appointments that are paid and confirmed but whose `chatChannelEnsuredAt` is still `NULL`, limited to the last seven days and processed oldest first. It calls the same `ensureChannelsForAppointment` the live pipeline calls, so the two cannot drift, and it reports `channelsEnsured` and `channelsFailed` alongside the existing counters. A run in which any channel failed answers 207 rather than 200: the next run will retry it, but an operator should see that a buyer is currently without a conversation.
+
+That job also has an HTTP twin at `/api/cleanup/reconcile-orphaned-confirmations`, which accepts an optional `?limit=` (a positive integer up to 500) and applies it to both passes. The GitHub Actions entrypoint has minutes to spend and uses the defaults; a Netlify ticker calling the route on a short schedule does not, and passing a small limit lets it take a bounded bite of each backlog per invocation instead of exhausting the function budget on one of them. An unparseable value is refused with a `400 INVALID_LIMIT` and a value above the cap is clamped to it, which is the shared `parseLimitParam` behaviour every other ticker target already had; the route used to swallow a malformed bound and sweep the defaults instead, which hid a broken caller behind a run that looked healthy (#1459).
## Money out
@@ -90,10 +108,12 @@ The payout and earnings pipeline, which turns completed sessions into money leav
| **Handle Stuck Payouts**
`handle-stuck-payouts` | `52 */4 * * *` | `jobs/payouts/handle-stuck-payouts.ts`
→ `scripts/payouts/handle-stuck-payouts.ts` | closed | yes | `ConsultantPayout` stuck-state recovery, `SystemEvent`; queries RazorpayX and Stripe | Skips: OFFLINE + DEGRADED |
| **Process Payouts**
`process-payouts` | `0 21 * * 1` | `jobs/payouts/process-payouts.ts` | bespoke | yes | Consultant and org payout status, `ConsultantEarnings`, `TDSRecord`, ledger; submits RazorpayX and Stripe payouts | Skips: OFFLINE + DEGRADED |
| **Reconcile Payout Status**
`reconcile-payout-status` | `33 */6 * * *` | `jobs/payouts/reconcile-payout-status.ts`
→ `scripts/payouts/reconcile-payout-status.ts` | closed | yes | `ConsultantPayout` status and TDS fields, `ConsultantEarnings`, `TDSRecord`, ledger entries | Skips: OFFLINE + DEGRADED |
-| **Release Earnings from Hold**
`release-earnings` | `17 * * * *` | `jobs/earnings/release-earnings.ts`
→ `scripts/earnings/release-earnings.ts` | closed | yes | `ConsultantEarnings` released from hold | Skips: OFFLINE + DEGRADED |
+| **Release Earnings from Hold**
`release-earnings` | `17 * * * *` | `jobs/earnings/release-earnings.ts`
→ `scripts/earnings/release-earnings.ts` | closed | yes | `ConsultantEarnings` and `OrganizationEarnings` released from hold | Skips: OFFLINE + DEGRADED |
| **Release PENDING_TRUST Earnings**
`release-pending-trust-earnings` | `42 * * * *` | `jobs/cleanup/release-pending-trust-earnings.ts` | closed | yes | Consultant and org earnings released from PENDING_TRUST | Skips: OFFLINE, DEGRADED |
| **Sync Payment to Earnings**
`sync-payment-earnings` | `22 * * * *` | `jobs/earnings/sync-payment-earnings.ts`
→ `scripts/earnings/sync-payment-earnings.ts` | closed | yes | Creates consultant and org earnings plus the booking ledger rows | Skips: OFFLINE + DEGRADED |
+`release-earnings` walks both earnings tables in one run. It moves `ConsultantEarnings` and `OrganizationEarnings` rows that are still `PENDING` and whose `holdUntil` has passed to `READY`, which is the status the two batch builders select on, and it does each table in its own Serializable transaction so a serialization conflict on one cannot discard a claim the other has already made. The claim restates `status: PENDING` in its `WHERE`, so a row that a dispute freeze or a refund cascade moved between the read and the update is skipped rather than dragged forward. When the HTTP twin at `/api/cleanup/release-earnings` is called with `?limit=`, that bound applies to each table separately — a run capped at two hundred may release up to two hundred consultant rows and up to two hundred organisation rows — which is the same per-target budgeting the Netlify ticker uses elsewhere. The result reports the two counts separately: `releasedCount` keeps its original meaning of consultant earnings released, and `organizationEarningsReleased` carries the host-organisation figure, so the GitHub Actions outputs and dashboards that already read the first number are not silently re-based. Until #1471 the organisation arm was missing entirely, and because every scheduled entry point imports this one module, a hosting organisation's retained share could never reach a payout batch.
+
## Billing and contracts
Organisation billing runs on its own cycle engine, and these jobs advance it. They were the newest part of the fleet, and until the wave-5 sweep it showed in the maintenance column: six of the eight were self-contained `jobs/**` entrypoints written after the `abortIfMaintenance()` convention was established, and none of them had adopted it. All eight now call the guard.
@@ -113,12 +133,14 @@ Organisation billing runs on its own cycle engine, and these jobs advance it. Th
These jobs exist because a statute or a regulator says they must, and their deadlines are external. Skipping one for a maintenance window is cheap; skipping one for a week is not.
-| Workflow | Schedule (UTC) | Entrypoint | Lock | Financial | Mutates | During maintenance |
-| ----------------------------------------------------------------------- | -------------- | ----------------------------------------------- | ------ | --------- | -------------------------------------------------------------------------------- | ------------------------ |
-| **Consent Retention Sweeper**
`consent-retention-sweeper` | `0 21 * * 0` | `jobs/compliance/consent-retention-sweeper.ts` | open | no | Expired `ConsentArtifact` rows deleted, and only when `DPDP_SWEEPER_DELETE=true` | Skips: OFFLINE |
-| **DPDP DataBreach 72h Deadline Alerts**
`databreach-deadline-alerts` | `27 * * * *` | `jobs/compliance/databreach-deadline-alerts.ts` | open | no | Reads only; emails the DPDP officer inbox | Skips: OFFLINE |
-| **IRP IRN Uploader**
`irp-uploader` | `50 2 * * *` | `jobs/compliance/irp-uploader.ts` | closed | yes | `OrganizationInvoice` IRN fields; uploads invoices to the IRP | Skips: OFFLINE, DEGRADED |
-| **MSME Section 43B(h) Payment Alerts**
`msme-payment-alerts` | `30 4 * * *` | `jobs/compliance/msme-payment-alerts.ts` | open | no | Reads only; emails the finance inbox | Skips: OFFLINE |
+| Workflow | Schedule (UTC) | Entrypoint | Lock | Financial | Mutates | During maintenance |
+| ------------------------------------------------------------------------- | ------------------- | ------------------------------------------------ | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
+| **Consent Retention Sweeper**
`consent-retention-sweeper` | `0 21 * * 0` | `jobs/compliance/consent-retention-sweeper.ts` | open | no | Expired `ConsentArtifact` rows deleted, and only when `DPDP_SWEEPER_DELETE=true` | Skips: OFFLINE |
+| **DPDP DataBreach 72h Deadline Alerts**
`databreach-deadline-alerts` | `27 * * * *` | `jobs/compliance/databreach-deadline-alerts.ts` | open | no | Reads only; emails the DPDP officer inbox | Skips: OFFLINE |
+| **IRP IRN Uploader**
`irp-uploader` | `50 2 * * *` | `jobs/compliance/irp-uploader.ts` | closed | yes | `OrganizationInvoice` IRN fields; uploads invoices to the IRP | Skips: OFFLINE, DEGRADED |
+| **GST Outward-Supplies Register Export**
`gst-outward-register-export` | `40 1 3 * *` | `jobs/compliance/gst-outward-register-export.ts` | closed | yes | Mints any missing `ConsumerInvoice` for the period, then stamps `gstr1ExportedAt` on the invoices and credit notes it reported | Skips: OFFLINE, DEGRADED |
+| **MSME Section 43B(h) Payment Alerts**
`msme-payment-alerts` | `30 4 * * *` | `jobs/compliance/msme-payment-alerts.ts` | open | no | Reads only; emails the finance inbox | Skips: OFFLINE |
+| **TDS quarterly return draft**
`tds-return-draft` | `20 1 5 1,4,7,10 *` | `jobs/compliance/tds-26q-draft-export.ts` | open | no | Reads only; writes the return CSV to the private `org-invoices` bucket | Skips: OFFLINE |
## Stream and recordings
@@ -173,12 +195,20 @@ The three that remain are deliberate.
The same sweep closed the other half of the hole. The forty-odd HTTP twins under `app/api/cleanup/` import these job cores directly and had no guard at all, so an ops trigger ran the job straight through an OFFLINE window. They cannot call `abortIfMaintenance()`, whose `process.exit(0)` would take the Next instance down with the request, so they call `assertNotInMaintenance()` instead: the same phase rule, surfaced as a `MaintenanceActiveError` the handler answers with 503.
+The GST outward-supplies register export joined that cohort in #1370. Its twin lives at `app/api/cleanup/gst-outward-register-export` and imports `runGstOutwardRegisterExport` from the job module, which is where the fail-closed `gst-outward-register-export` lock is taken, so an HTTP call that overlaps the scheduled run answers 409 instead of racing the gapless invoice series. The one thing the twin does differently is that it does not write the CSV: a serverless filesystem is read-only and nothing would collect the file, so the HTTP path heals the missing invoices, stamps `gstr1ExportedAt` and reports the counts, while the Actions run remains the way a CA actually obtains the file.
+
+Two more joined it in #1407, closing the last gaps in the "every job has an HTTP twin" rule. `app/api/cleanup/settle-invoice-accruals` imports `runSettleInvoiceAccruals` from `jobs/billing/settle-invoice-accruals.ts`, and `app/api/cleanup/tds-return-draft` imports `runTdsReturnDraftExport` from `jobs/compliance/tds-26q-draft-export.ts`. In both cases the exported function is where the cron lock is taken — fail-closed on the accrual rollup, because two overlapping runs would each roll the same accrual set into an invoice, and fail-open on the return draft, because that export only reads. Neither exported core calls `abortIfMaintenance()`; the maintenance guard stays on the entry points, so the Actions run exits the process and the route answers 503.
+
+The TDS job needed one structural change to make this possible. Its `main()` used to run at import, which meant that merely importing the module from a route would have fired the quarterly export; it is now behind the usual `require.main === module` guard, the shape the other ten job modules already use. The twin runs with the same defaults as the schedule — the quarter that closed, not the quarter containing today — writes the same full-PAN CSV to the private finance bucket, and returns the storage path instead of a GitHub artifact, since there is no artifact store on the HTTP path.
+
## Locking
`withCronLock` (`lib/cron/with-cron-lock.ts`) provides distributed mutual exclusion keyed `cron:lock:`, with a fifteen-minute TTL by default and thirty-five minutes for the payout and reconcile family. It exists because the same job can be entered three ways — the schedule, a manual `workflow_dispatch`, and an authenticated HTTP call — and jobs whose side effects are only partially idempotent must not run twice concurrently.
It is a mutual-exclusion tool and nothing more. Data correctness comes from compare-and-set transitions and unique constraints, never from this lock, because Redis and PostgreSQL are separate failure domains and the lock can be lost without the database noticing. ADR 13 records that reasoning in full.
+Every scheduled workflow also declares a workflow-level `concurrency: { group: ${{ github.workflow }}, cancel-in-progress: false }`, a second and redundant guard at the Actions layer that queues an overlapping run rather than killing one mid-flight; `withCronLock` remains the correctness guard, and `__tests__/maintenance/cron-lock-registry.test.ts` asserts the concurrency block is present on every scheduled entry so the two guards cannot drift apart. GitHub Actions allows one running and one pending run per concurrency group by default, and a newer run replaces the pending one rather than queuing behind it; the twelve workflows that also accept `workflow_dispatch` add `queue: max` so a second manual trigger cannot silently displace one already waiting, up to a hundred pending runs.
+
Four scheduled workflows do not use it, each for a stated reason.
| Workflow | Mechanism | Why not `withCronLock` |
diff --git a/docs/payments/01-architecture.md b/docs/payments/01-architecture.md
index c1e26b606..d0a43ae1d 100644
--- a/docs/payments/01-architecture.md
+++ b/docs/payments/01-architecture.md
@@ -19,7 +19,17 @@
## Overview
-The payment system uses **Razorpay** as the sole active payment gateway, with Stripe retained as a secondary rail for Connect transfers. `DODO_PAYMENTS` exists in the `PaymentGateway` enum as a post-MVP placeholder with no implementation behind it; `POST_MVP_GATEWAY_STUBS` in `lib/payments/constants.ts` is the list, and `assertGatewayUsable` refuses one at runtime. The gateway comparison that led here is recorded in [gateways/gateway-evaluation-mar-2026.md](./gateways/gateway-evaluation-mar-2026.md). It handles four appointment types:
+The payment system uses **Razorpay** as the sole active payment gateway. Stripe is implemented but fenced off, and `DODO_PAYMENTS` exists in the `PaymentGateway` enum as a post-MVP placeholder with no implementation behind it. `POST_MVP_GATEWAY_STUBS` in `lib/payments/constants.ts` is the placeholder list, and `assertGatewayUsable` in `lib/payments/validation/gateway-guards.ts` refuses both a placeholder and a fenced-off gateway at runtime. The gateway comparison that led here is recorded in [gateways/gateway-evaluation-mar-2026.md](./gateways/gateway-evaluation-mar-2026.md).
+
+| Gateway | Status | How it is gated |
+| ----------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Razorpay** | Live, primary | No flag. `routeGateway` selects it for every buyer country, domestic directly and international over IBT. |
+| **Stripe** | Implemented, fenced off | `STRIPE_ENABLED=true` on the server and `NEXT_PUBLIC_STRIPE_ENABLED=true` in the checkout UI. Auto-routing never selects it; only an explicit request reaches it, and `assertGatewayUsable` throws a `DisabledGatewayError` when the flag is unset. Refunds of existing Stripe payments are deliberately outside the fence. |
+| **Dodo Payments** | Schema placeholder | Listed in `POST_MVP_GATEWAY_STUBS`. Any use throws `UnsupportedGatewayError`. |
+
+Stripe is retained as a contingency rail in case RBI rules make Razorpay unusable for a class of collections, and for Connect transfers if international payouts are ever turned on. It is not a live payment method, so no customer should ever see the Stripe button.
+
+The system handles four appointment types:
| Type | Description | Slot Handling |
| ---------------- | -------------------- | ---------------------------------- |
@@ -963,12 +973,17 @@ AppointmentStatus:
### Gateway Support Matrix
-| Feature | Stripe | Razorpay |
-| ------------------- | ------ | ------------------- |
-| Dispute Webhooks | Yes | Yes |
-| List Disputes API | Yes | No (Dashboard only) |
-| Submit Evidence API | Yes | No (Dashboard only) |
-| Retrieve Dispute | Yes | No |
+The matrix below covers the dispute surface, where the two gateways differ most, and the settlement currency, where they deliberately do not differ at all.
+
+| Feature | Stripe | Razorpay |
+| -------------------- | ------------------------------- | ------------------------------- |
+| Dispute Webhooks | Yes | Yes |
+| List Disputes API | Yes | No (Dashboard only) |
+| Submit Evidence API | Yes | No (Dashboard only) |
+| Retrieve Dispute | Yes | No |
+| Settlement currency | INR only, enforced at order creation | INR only, enforced at order creation |
+
+Settlement is INR-only by design, per [ADR 15](../enterprise/70-design-decisions/15-currency-as-enum-with-display-fields.md): every stored amount is an integer count of INR paise and the double-entry ledger is INR-denominated. That is enforced rather than assumed. `assertInrSettlement`, in `lib/payments/validation/currency-guards.ts`, is the first statement of both `createRazorpayOrder` and `createStripeCheckoutSession`, and it throws a `PaymentError` with code `NON_INR_SETTLEMENT` for anything else. The assertion sits at the gateway boundary rather than at each caller because callers read a currency out of the database — an organisation's billing account, an invoice's display currency, an overage event — and any one of them forwarding a stale non-INR value would otherwise mint an order denominated in that currency's own subunit while the platform recorded rupees. An international buyer is still served an INR order; their card issuer performs the conversion. See [multi-currency/01-architecture.md](./multi-currency/01-architecture.md) for the display-side story.
---
diff --git a/docs/payments/05-b2c-b2b-funding-seam.md b/docs/payments/05-b2c-b2b-funding-seam.md
index 8211601fb..11038a6c1 100644
--- a/docs/payments/05-b2c-b2b-funding-seam.md
+++ b/docs/payments/05-b2c-b2b-funding-seam.md
@@ -66,7 +66,17 @@ Each `Payment` carries zero or more `PaymentLeg` rows (append-only; `prisma/sche
Legs are **append-only** — a refund never mutates the original leg; it upserts a negative `*_REVERSAL` sibling (`lib/payments/operations/refund.ts:778`). The `@@unique([paymentId, source])` constraint means one reversal leg per source; subsequent partial refunds decrement the existing reversal leg via `update: { amountPaise: { decrement: reverse } }`.
-Invariant: `sum(non-reversal legs.amountPaise) == Payment.amount` when legs are present (LICENSE legs contribute 0).
+Invariant: `sum(non-reversal, non-REFERRAL_CREDIT legs.amountPaise) == Payment.amount` when legs are present (LICENSE legs contribute 0). The referral credit sits outside the sum because `Payment.amount` is the post-credit gateway charge, so the credit has already been deducted from it and counting the leg as well would demand it twice (#1347). See [payment legs §3](../enterprise/10-money-and-ledger/09-payment-legs.md#3-invariants).
+
+### Programme overage across the rails (#1458)
+
+A booking that breaches its programme's cap does not settle the same way on every rail, because the rails collect at different moments.
+
+On the **INVOICE** rail the org has not paid anything yet, so the marginal is carved out of the base `INVOICE_ACCRUAL` leg into an `OVERAGE_INVOICE_ACCRUAL` leg and billed at the month-end rollup. On the **WALLET** rail the debit taken when the booking committed is the whole nominal price, so the overage is collected the moment the booking commits: no `OVERAGE_INVOICE_ACCRUAL` leg is written, `Payment.amount` is left exactly at the wallet debit, and the `OverageEvent` is recorded as `CHARGED` and settled against the payment whose `WALLET` leg collected it. Writing a leg there would have broken the leg-sum invariant above and, worse, incrementing `Payment.amount` on top of it made a later cancellation refund the organisation more than its wallet was ever debited.
+
+`CHARGE_MEMBER` is **not available on a WALLET-funded billing account**. Charging the member requires carving the over-cap portion back out of the parent payment, which on this rail would mean crediting the wallet mid-transaction — the credit-back that #715 has never built. The combination is refused when a programme is created or patched, and checkout keeps a fail-closed refusal (`OVERAGE_CHARGE_MEMBER_UNSUPPORTED`, HTTP 409) for any programme configured before that guard existed.
+
+`PROGRAM_CAP_EXHAUSTED` is the contract for the per-cycle overage ceiling. The settlement code throws it as an HTTP 402 with a machine-readable code, the checkout transaction's catch rethrows it unchanged because that code is registered in `BUSINESS_ERROR_CODES`, and the route answers 402 with a toast telling the buyer that the organisation's programme budget for this cycle is used up. It is a modelled outcome, so Sentry records it as expected volume rather than a fault; the two overage funding refusals above are deliberately not modelled, because they mean a programme was configured in a shape no rail can collect on.
---
diff --git a/docs/payments/06-high-level-design.md b/docs/payments/06-high-level-design.md
new file mode 100644
index 000000000..48ce9dc18
--- /dev/null
+++ b/docs/payments/06-high-level-design.md
@@ -0,0 +1,169 @@
+# Money subsystem — high-level design in four diagrams
+
+This page is the map a newcomer should read before any other payments document. It shows where money truth is written, what is allowed to lag behind it, and which mechanism closes each gap. Everything drawn here runs inside one Next.js application against one Postgres database and one Redis instance. There are no services, no queues and no message brokers; the domain rows themselves carry every pending obligation, and scheduled sweeps read those rows to finish the work (ADR 14, ADR 22 and ADR 27 explain why that posture was chosen over a broker).
+
+The diagrams describe the code as it stands after the 2026-09-03 finance train (PRs #1385, #1386, #1389, #1390, #1391, #1393, #1392 and #1414). Where a box only exists because of one of those PRs, the PR number is written on it. The verdict record that motivated the train lives in [audits/2026-09-03-finance-verdicts.md](./audits/2026-09-03-finance-verdicts.md).
+
+## 1. B2C: a consultee pays for a session
+
+The first diagram follows a single booking from the checkout request to the moment every side effect exists. The synchronous part is one Serializable database transaction taken under a Redis slot lock; it writes the Payment, its funding legs and the appointment hold together, so either all three exist or none does. The gateway then calls back asynchronously, and the webhook row is saved before the request is acknowledged, which makes the inbound event durable: the platform can redrive the persisted row without requiring Razorpay to resend it. One writer, running in one transaction, moves the money state and posts the ledger. Everything after that commit is best effort and is re-driven by the sweeps at the bottom.
+
+```mermaid
+flowchart TB
+ U["Consultee (browser)"]
+ subgraph Sync["Synchronous request — one Serializable DB transaction, Redis slot lock held"]
+ CO["POST /api/checkout
price → discount → 18% GST → referral credits"]
+ PAY["Payment PENDING (amount = gateway charge)
+ PaymentLegs (Σ non-credit legs = amount, DB trigger, #1385)"]
+ APPT["Appointment PENDING_PAYMENT
slot hold via CAS + GiST exclusion"]
+ end
+ RZP[("Razorpay")]
+ subgraph Inbox["Webhook inbox — at-least-once, persisted before the 200"]
+ WE["WebhookEvent row
(x-razorpay-event-id unique, deferCount #1391)"]
+ end
+ subgraph Writer["Single writer (ADR 21) — one DB transaction"]
+ HS["handlePaymentSuccess"]
+ P2["Payment SUCCEEDED + gatewayPaymentId (#1391)"]
+ A2["Appointment CONFIRMED (CAS in WHERE)"]
+ EARN["Earnings rows (consultant / platform split from the RateCard snapshot)"]
+ LED["LedgerTransaction + LedgerEntry rows
(double entry; trigger rejects an unbalanced transaction)"]
+ AUD["SystemEvent audit row"]
+ end
+ subgraph After["Best effort after commit — idempotent, may fail"]
+ INV["ConsumerInvoice FAM-FY-SEQ tax invoice (#1393)"]
+ CH["Stream chat channel"]
+ MAIL["Emails / Novu"]
+ end
+ subgraph Sweeps["State-as-outbox sweeps — Netlify ticker every 5 min (#1390), GitHub Actions as backstop"]
+ S1["sweep-stuck-webhook-events"]
+ S2["reconcile-orphaned-confirmations + channel ensure-step (#1391)"]
+ S3["reconcile-payment-status (DB ↔ gateway)"]
+ S4["abandoned-payments (expire PENDING)"]
+ S5["gst-outward-register healer (missing invoices, #1393)"]
+ end
+ U --> CO --> PAY --> APPT
+ PAY -- "order_id (INR asserted, #1414)" --> RZP
+ U -- "pays" --> RZP -- "payment.captured" --> WE --> HS
+ HS --> P2 --> A2 --> EARN --> LED --> AUD
+ AUD -.-> INV
+ AUD -.-> CH
+ AUD -.-> MAIL
+ WE -. "deferred / crashed mid-way" .-> S1 --> HS
+ P2 -. "SUCCEEDED but no channel" .-> S2 --> CH
+ P2 -. "SUCCEEDED but no invoice" .-> S5 --> INV
+ RZP <-. "status drift" .-> S3
+ PAY -. "never paid" .-> S4
+```
+
+Three guarantees follow from this shape. The buyer's money state is exact at the moment the writer commits, because the Payment, the appointment, the earnings and the ledger entries are in the same transaction. Side effects are eventually consistent and are retried by the listed sweeps where a sweep exists; the five-minute ticker cadence is the normal retry interval, not a hard completion bound. Every sweep is idempotent, so a sweep and a webhook retry racing each other cannot double-post anything.
+
+## 2. B2C: refunds and consultant payouts
+
+The second diagram covers money leaving the platform on the consumer side. A refund is two-phase: the Refund row reserves the amount before the gateway is called, the gateway call carries the Refund id as its idempotency key, and the ledger reversal, the earnings clawback and the credit note are written only when the gateway confirms. A consultant payout releases earnings after the hold period, batches them, and writes the TDS record only when the RazorpayX webhook says the money moved.
+
+```mermaid
+flowchart LR
+ subgraph Refund["Refund — two-phase, one front door"]
+ RQ["Refund quote (cancellation policy in basis points)"]
+ RR["Refund row PENDING (reserves the amount)"]
+ RG["Gateway refund
X-Refund-Idempotency = Refund.id"]
+ RW["refund.processed webhook (found by gatewayPaymentId, #1391)"]
+ RL["Ledger reversal + earnings clawback
+ ConsumerCreditNote FAM-CN-FY-SEQ (#1393)"]
+ RS["reconcile-refunds / cascade-refund-earnings sweeps"]
+ end
+ subgraph Payout["Consultant payout"]
+ REL["release-earnings (after the hold period)"]
+ PB["ConsultantPayout batch (BATCHED)"]
+ RX[("RazorpayX")]
+ PW["payout webhook → PAID
TDSRecord written here (s.194-O, 0.1%)"]
+ TR["tds-return-draft, quarterly (#1389)
Form 140 CSV; full PAN only in the private bucket"]
+ end
+ RQ --> RR --> RG --> RW --> RL
+ RR -. "stuck" .-> RS --> RG
+ REL --> PB --> RX --> PW --> TR
+```
+
+The refund path has a single front door on purpose. Every rail that can return money to a buyer, whether a cancellation, a dispute, a removed event seat or an admin action, must produce a Refund row first, so the reserve, the idempotency key and the credit note are never skipped.
+
+## 3. B2B: an organisation funds its members
+
+The third diagram shows what changes when an organisation pays. The checkout, the price derivation, the GST calculation, the single writer and the ledger are the same code as the consumer path. What differs is the funding leg: a wallet, a licence seat, an invoice accrual or an overage charge replaces the card, and for wallet and licence legs no gateway call happens at all. Accrued legs roll up into one organisation invoice per month, and organisations that sell on the platform receive payouts with their own TDS records.
+
+```mermaid
+flowchart TB
+ subgraph Org["Organisation"]
+ BA["BillingAccount
rails: WALLET (prepaid) | INVOICE (net terms) | PO; currency INR only (#1414)"]
+ POOL["Seat pool / credit pool → allocations per member"]
+ OVR["Overage policy: BLOCK | CHARGE_MEMBER | CHARGE_ORG (circuit breaker)"]
+ end
+ subgraph Fund["Funding"]
+ TOP["Wallet top-up → Razorpay order → capture webhook → wallet ledger entries"]
+ PO["PurchaseOrder (remainingAmountPaise)"]
+ end
+ subgraph Book["Member books — org-funded checkout"]
+ MC["Same checkout, same price derivation, same GST
PaymentLeg source = WALLET / LICENSE / INVOICE_ACCRUAL / OVERAGE"]
+ MP["Payment SUCCEEDED without a gateway call for wallet and licence legs
same single writer, same ledger, same earnings"]
+ end
+ subgraph Bill["Monthly billing"]
+ ROLL["consolidated-invoice-rollup
INVOICE_ACCRUAL legs → one OrganizationInvoice"]
+ OINV["OrganizationInvoice PDF (GST heads; IRN later)
dunning; PO balance decrement in the same currency"]
+ OPAY["Organisation pays → capture → invoice PAID"]
+ end
+ subgraph OrgPayout["Org-side revenue share (partner organisations that sell)"]
+ OP["OrganizationPayout batch → RazorpayX"]
+ OT["TDSRecord at COMPLETED, organisation as deductee (#1389)"]
+ end
+ subgraph CA["Compliance exports for the CA"]
+ REG["gst-outward-register, monthly (#1393)
consumer + org invoices + credit notes"]
+ TDS["tds-return-draft, quarterly (#1389)
consultant + organisation deductees"]
+ end
+ BA --> POOL --> OVR
+ TOP --> BA
+ PO --> BA
+ POOL --> MC --> MP
+ OVR --> MC
+ MP --> ROLL --> OINV --> OPAY
+ PO -. "gates" .-> OINV
+ MP --> OP --> OT --> TDS
+ OINV --> REG
+```
+
+The three axes that make enterprise finance look complicated, namely the organisation's shape, its funding source and the programme type, are product facts rather than engineering choices. The code keeps them orthogonal so that a new combination is a configuration, not a new code path.
+
+## 4. Cross-cutting: truth, audit, schedulers and reconciliation
+
+The last diagram separates the four layers that the first three diagrams mix together. Money truth is strongly consistent and guarded by the database itself. The audit trail is a set of append-only rows written inside the same transactions, so it cannot disagree with the money. The schedulers are the only asynchronous machinery, and they do nothing but call HTTP routes that already exist. Reconciliation has exactly four purposes, and every scheduled money job maps to one of them.
+
+```mermaid
+flowchart LR
+ subgraph Truth["Money truth — strongly consistent, one transaction"]
+ T1["Payment / Refund / Payout rows
status moves only through the CAS-in-WHERE helpers"]
+ T2["Double-entry journal: LedgerTransaction + LedgerEntry
balances are derived; walletBalance is a reconciled cache"]
+ T3["DB guards: leg-sum trigger, ledger-balanced trigger, CHECK sidecars"]
+ end
+ subgraph Audit["Audit trail — append-only rows"]
+ A1["OrgAuditLog (who did what inside an organisation)"]
+ A2["SystemEvent / recordSystemError (operations timeline)"]
+ A3["SystemJobExecution (every cron run, its lock, its outcome)"]
+ A4["WebhookEvent (raw inbound payload, retries)"]
+ end
+ subgraph Sched["Schedulers — no broker"]
+ G["GitHub Actions cron
nightly and backstop runs (sub-hourly schedules fire only every ~100 min)"]
+ N["Netlify scheduled function cron-tick.mts (#1390)
every 5 min, ten money routes, bounded by ?limit"]
+ R["app/api/cleanup/* routes
CRON_SECRET + withCronLock (fail-closed for money jobs)"]
+ end
+ subgraph Recon["Reconciliation — four purposes"]
+ R1["DB ↔ gateway status"]
+ R2["DB ↔ journal caches"]
+ R3["crash-gap re-drives"]
+ R4["time expiry"]
+ end
+ G --> R
+ N --> R
+ R --> Recon
+ Recon --> Truth
+ Truth --> Audit
+```
+
+## When this design should change
+
+A message broker earns its place when a second, independently deployed consumer needs the same events, when inbound webhooks sustain tens of events per second, or when the application leaves a serverless host and can run a consumer process around the clock. None of those conditions holds today, and the first step when one does is an HTTP queue such as QStash driving the same cleanup routes (issue #866), not Kafka. Until then, the cost of this design is readability rather than correctness: a reader has to know the sweeps exist, which is why ADR 27 lists every one of them.
diff --git a/docs/payments/07-b2c-tax-invoice.md b/docs/payments/07-b2c-tax-invoice.md
new file mode 100644
index 000000000..51d243d61
--- /dev/null
+++ b/docs/payments/07-b2c-tax-invoice.md
@@ -0,0 +1,132 @@
+# B2C Tax Invoices and Credit Notes
+
+> How a personal buyer gets the statutory tax invoice for their booking, how a refund reverses it with a credit note, and how both reach the monthly GSTR-1 working file. Introduced by #1365 and #1370.
+
+---
+
+## Why this exists
+
+The platform bills as the principal supplier for GST, which ADR 26 records as a locked decision. Checkout charges 18% on the discounted price through `lib/payments/pricing/derive-checkout-amount.ts` and `lib/payments/tax/tax-engine.ts`, and settlement credits `GST_PAYABLE` in `lib/payments/payouts/earnings-service.ts`. Every one of those charges is our own outward supply, so every one of them needs a document that satisfies CGST Rule 46.
+
+Organizations already had that document: an `OrganizationInvoice` with its own gapless per-org series, its own IRP e-invoice fields and its own dunning lifecycle. Personal buyers had nothing. Between the v0 lockdown in #768 and this change, a consumer who paid 18% GST received a payment confirmation and no invoice at all, and there was no register from which the platform's own outward supplies could be filed.
+
+This change adds the document trail and nothing else. It posts no ledger entries, it derives no tax from a rate, and it builds no IRN. Those exclusions are deliberate and are listed in full at the end of this page.
+
+## What is minted, and when
+
+Two models carry the documents, both defined in the invoicing section of `prisma/schema.prisma`.
+
+| Model | What it is | Keyed by |
+| -------------------- | -------------------------------------------------------------------- | --------------------------------------- |
+| `ConsumerInvoice` | The Rule 46 tax invoice for one successful consumer payment. | `paymentId`, unique. |
+| `ConsumerCreditNote` | The section 34 credit note that reverses part or all of one invoice. | `refundId` or `disputeId`, both unique. |
+
+`mintConsumerInvoice` in `lib/payments/billing/consumer-invoice.ts` is called from two places, because a payment reaches its confirmed state by two different routes. The capture webhook calls it from `lib/payments/webhooks/handlers.ts` once the booking is confirmed, and the instant-confirm branch of `lib/payments/operations/checkout.ts` calls it for mock, zero-amount and org-sponsored checkouts, which never see a webhook at all.
+
+Both call sites wrap the mint in a try/catch that reports to Sentry at warning level and never rethrows. A confirmed booking must not roll back because a document could not be produced, and the monthly register export re-attempts anything that was missed.
+
+The mint is a silent no-op, returning a null id rather than throwing, in each of these cases:
+
+- the payment is not `SUCCEEDED`, or has been soft-deleted;
+- the payment is org-funded, meaning it carries `billableToOrgInvoiceId` or any payment leg sourced from `WALLET`, `LICENSE`, `INVOICE_ACCRUAL` or `OVERAGE_INVOICE_ACCRUAL`. Those supplies are invoiced to the organization on the org series instead, and giving them a second document would double-count the same supply;
+- `getPlatformSupplier()` returns null because `PLATFORM_GSTIN` is unset or malformed. The process logs this once. Issuing a legal-looking invoice with a fabricated GSTIN is worse than issuing none;
+- the reconstructed total is zero or less.
+
+The idempotency probe on `paymentId` runs before any sequence number is allocated. That ordering is load-bearing: a webhook redelivery that allocated a number first and then discovered the invoice already existed would leave a permanent gap in a gapless statutory series.
+
+## Numbering
+
+Consumer documents run on a platform-wide series, not a per-buyer one, because the supplier is the platform and the series belongs to the supplier. Two counter tables hold the sequences, `platform_invoice_counters` and `platform_credit_note_counters`, and each allocation is an atomic upsert that returns the pre-increment value, exactly as the org counters do.
+
+| Document | Format | Example | Ceiling |
+| ----------- | ------------------------- | ------------------ | ----------------------- |
+| Invoice | `--` | `FAM-2026-00001` | 99,999 per fiscal year. |
+| Credit note | `-CN--` | `FAM-CN-2026-0001` | 9,999 per fiscal year. |
+
+`PREFIX` comes from the optional `PLATFORM_INVOICE_PREFIX` environment variable and defaults to `FAM`. It passes through `fitPrefixToRule46`, which caps the whole number at the sixteen characters Rule 46(b) allows. The credit-note series is separate from the invoice series because Rule 53 requires it to be. Both use `indianFiscalYear`, so a document issued in March lands in the previous fiscal year, reckoned in IST.
+
+## Place of supply
+
+Section 12(2)(b) of the IGST Act says that where the recipient's address is not on record, a B2C supply is made at the **supplier's** location. That is the opposite of the rule the B2B path follows: `deriveGstBreakdown` falls back to IGST on an unknown buyer state and records `IGST_STATE_UNKNOWN`, because a registered buyer is expected to have a state and a missing one is a defect worth surfacing. For a consumer, a missing state is the statutory norm.
+
+`deriveConsumerInvoiceTax` is a pure function that implements this. It never re-derives tax from a rate; the taxable value is the charged total minus the charged tax, so the document agrees with the `GST_PAYABLE` credit to the paise.
+
+The supplier's own state is settled before that derivation runs. `resolveSupplierStateCode` reads the first two digits of `PLATFORM_GSTIN`, which are the state of registration by law, and falls back to `SUPPLIER_STATE_CODE` only when the GSTIN carries none. The same resolved value is handed to the derivation and stored on the row, so the heads on the document can never disagree with the state printed beside them. When the GSTIN and the environment variable name different states the mint fails closed exactly as a missing GSTIN does: no document is issued, a Sentry warning and a `SystemEvent` name both values, and the monthly register healer re-attempts the payment once the configuration is fixed.
+
+| Buyer state | Result | `placeOfSupplySource` |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| Same as the supplier's | CGST and SGST, split with CGST floored and SGST absorbing the odd paise | `DECLARED_AT_CHECKOUT` or `PROFILE_ON_RECORD` |
+| A different state | IGST for the whole tax | `DECLARED_AT_CHECKOUT` or `PROFILE_ON_RECORD` |
+| Absent or unresolvable | Placed at the supplier's own state, so CGST and SGST | `SUPPLIER_DEFAULT_12_2_B` |
+| Outside India | Delegated to `deriveGstBreakdown` for the LUT gate, then mapped back with the amounts kept anchored to what was charged | Either, depending on whether a state was given |
+
+Where the source is `SUPPLIER_DEFAULT_12_2_B`, the rendered PDF carries the footnote "Place of supply determined under s.12(2)(b) IGST Act (no address of the recipient on record)", so a reader can tell a defaulted place of supply from a declared one.
+
+## Capturing the buyer's state
+
+Checkout can ask for the buyer's state, but it never insists. `app/checkout/components/BillingStateSelect.tsx` is mounted on the consultation, subscription, webinar and class checkout pages, labelled "Billing state (for GST)", and it submits the two-digit numeric code that the GST portal, the invoice and `lib/compliance/gst.ts` all compare on. Leaving it blank is a correct answer, not an incomplete one, because the statutory default applies.
+
+The declared value is written to `Payment.consumerStateCode` in the same transaction that creates the payment, and to `ConsulteeProfile.billingStateCode` when it differs from what the profile already held, so a repeat buyer is never asked twice. `/api/checkout/context` returns the remembered value and the checkout pages pre-fill the picker with it.
+
+At mint time the resolution order is the declaration on the payment, then the profile, then the statutory default, and `placeOfSupplySource` records which of the three applied.
+
+## Credit notes on refund
+
+A refund never deletes or rewrites the invoice. `mintConsumerCreditNote` issues a section 34 credit note beside it, and the pair is what reconciles.
+
+The reversal is strictly proportional over the tax-inclusive total and it keeps the same tax head the invoice used, because a credit note may not move a supply from one head to another.
+
+The cap is cumulative rather than per-note. `mintConsumerCreditNote` sums the `totalPaise` of every note already issued against the invoice, inside the same transaction, and credits at most the remainder. This matters because a partial refund and a later lost chargeback are two different idempotency keys against one invoice, so neither one's probe short-circuits the other; without the cumulative cap the pair could reverse more than the platform ever charged and understate the period's output tax. When the invoice is already credited in full the note is refused, a `SystemEvent` is recorded so an operator sees it, and the caller receives a null identifier.
+
+The heads are prorated from the invoice's total tax and then split again by the same floor-CGST rule the invoice itself used, rather than each head being prorated on its own. Flooring three heads independently leaves the stored row short of its own total by a paise or two, which the register reports as a reconciliation warning. Prorating once and letting the taxable value absorb the residual makes the identity `taxable + CGST + SGST + IGST == total` hold by construction, and no head on a note can exceed the corresponding head on the invoice.
+
+It is called from two places, mirroring the org-side `mintRefundCreditNote` it sits beside: Step 7.5 of the refund cascade in `lib/payments/operations/refund.ts`, and the lost-chargeback branch of `app/api/webhooks/utils.ts`. Both are idempotent on their own trigger, so a webhook redelivery or a cron retry re-reads the existing note.
+
+## Downloading a document
+
+| Route | Returns |
+| -------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `GET /api/payments/[paymentId]/invoice/pdf` | A 302 to a 24-hour signed URL for the tax invoice. |
+| `GET /api/payments/[paymentId]/credit-note/[creditNoteId]/pdf` | The same, for a credit note that belongs to that payment's invoice. |
+
+Both routes authorise the payment's own buyer or an ADMIN/STAFF operator, apply the `moneyOpsLimiter` bucket per actor, and return 503 with code `SUPPLIER_GSTIN_UNCONFIGURED` when `PLATFORM_GSTIN` is missing, or 404 with code `INVOICE_NOT_ISSUED` when no document exists. The PDF is rendered on the first request, uploaded to the existing private `org-invoices` bucket under a `consumer//.pdf` path, cached on the row for twenty-four hours, and re-signed without re-rendering on subsequent hits.
+
+The documents render from the snapshot stored on the row rather than from live supplier and buyer records, because a tax invoice must keep saying what it said on the day it was issued.
+
+Both PDFs register Noto Sans Devanagari from `public/fonts/` and apply it to the buyer's name and address only. Helvetica, which the org documents use throughout, has no Devanagari coverage, so a buyer writing in Hindi or Marathi would otherwise see their own name as a row of boxes. The font is read from a copy traced into the deployment bundle by `outputFileTracingIncludes` in `next.config.mjs`, never fetched over the network, and registration falls back to Helvetica if the file is absent rather than failing the download.
+
+The invoice number and a download link appear on the admin payment list and detail pages, and on the consultee's own payments tab. An empty cell there means the payment was org-funded, which is the correct answer rather than a missing document.
+
+## The outward-supplies register
+
+`jobs/compliance/gst-outward-register-export.ts` runs on the third of each month for the previous IST calendar month, well ahead of the eleventh-of-the-month GSTR-1 deadline. `GST_REGISTER_PERIOD_START` and `GST_REGISTER_PERIOD_END` override the period and must be set together; the workflow exposes them as dispatch inputs.
+
+It does four things in order. First it heals: any `SUCCEEDED`, non-deleted payment in the period with no consumer invoice is minted, each in its own short transaction, and a non-zero count is warned about because it means the checkout mint path missed something. Then it reads every `ConsumerInvoice`, issued `OrganizationInvoice`, `ConsumerCreditNote` and issued `CreditNote` in the period and shapes them into one register through the pure builder in `lib/compliance/gst-outward-register.ts`. Then it writes the CSV to `GST_REGISTER_CSV_OUT`, which the workflow uploads as a ninety-day artifact. Finally it stamps `gstr1ExportedAt` on everything it reported, in one transaction, guarded on the stamp being null so a second run in the same month reports the same documents again without moving anyone's first-reported timestamp.
+
+The CSV header is fixed, because the CA's import template depends on it:
+
+```
+doc_type,doc_number,doc_date,buyer_type,buyer_gstin,place_of_supply,taxable_paise,cgst_paise,sgst_paise,igst_paise,total_paise,sac_code,original_invoice_number,payment_id
+```
+
+The builder raises a warning for any document with no place of supply, any document whose tax heads do not reconcile to the total minus the taxable value, and any B2C document of ₹50,000 or more that lacks the recipient's address and state.
+
+The job is fail-closed on its cron lock and is on the financial job list, unlike the read-only compliance drafts beside it. Its healer allocates numbers from a gapless statutory series, and two concurrent runs would both see a payment as un-invoiced, both take a number, and one would lose the unique constraint, leaving a gap that cannot be filled. Not producing the register is recoverable; a gap in the series is not.
+
+## The ₹50,000 flag
+
+Rule 46 requires a B2C invoice of ₹50,000 or more to carry the recipient's name, address and state. The mint still issues the invoice when those are missing, because withholding a buyer's document is a worse outcome than issuing an incomplete one, and sets `needsBuyerAddress` on the row. The register turns that flag into a warning line so finance can chase the address before filing.
+
+## What this deliberately does not do
+
+- **It posts nothing to the ledger.** Output tax is already credited to `GST_PAYABLE` at settlement. A second posting from the document trail would double-count the liability.
+- **It derives no tax from a rate.** The heads are split out of the tax the buyer actually paid. A rate-recomputed figure would drift from the settled amount the first time a discount or a rounding boundary moved.
+- **It builds no IRN.** B2C is outside the e-invoicing scope; the IRP fields on `OrganizationInvoice` have no counterpart here.
+- **It does not handle GST-TCS under section 52.** That remains with `jobs/compliance/gstr8-draft-export.ts`.
+- **It does not block checkout.** The billing-state picker is optional by design, because the statutory default already produces a correct invoice.
+
+## Related
+
+- [B2C ↔ B2B funding seam](./05-b2c-b2b-funding-seam.md)
+- [Invoicing (B2B)](../enterprise/10-money-and-ledger/08-invoicing.md)
+- [Cron jobs reference](../maintenance/04-cron-jobs-reference.md)
diff --git a/docs/payments/README.md b/docs/payments/README.md
index 8f60f7b04..d62e26172 100644
--- a/docs/payments/README.md
+++ b/docs/payments/README.md
@@ -8,12 +8,15 @@ Complete documentation for the Familiarise payment system — checkout, gateways
## Overview
-| # | Document | Description |
-| --- | -------------------------------------------------------- | ------------------------------------------------------- |
-| 01 | [Architecture](./01-architecture.md) | System design, database models, complete data flow |
-| 02 | [Setup](./02-setup.md) | Payment gateway configuration, environment variables |
-| 03 | [Status Enums Reference](./03-status-enums-reference.md) | All payment, refund, dispute, and booking status values |
-| 04 | [Abandoned Solutions](./04-abandoned-solutions.md) | Previous approaches and why they were abandoned |
+| # | Document | Description |
+| --- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| 01 | [Architecture](./01-architecture.md) | System design, database models, complete data flow |
+| 02 | [Setup](./02-setup.md) | Payment gateway configuration, environment variables |
+| 03 | [Status Enums Reference](./03-status-enums-reference.md) | All payment, refund, dispute, and booking status values |
+| 04 | [Abandoned Solutions](./04-abandoned-solutions.md) | Previous approaches and why they were abandoned |
+| 05 | [B2C/B2B Funding Seam](./05-b2c-b2b-funding-seam.md) | Where the consumer and organisation funding paths meet and diverge |
+| 06 | [High-Level Design](./06-high-level-design.md) | Four Mermaid diagrams: B2C payment, refunds and payouts, B2B funding, cross-cutting layers |
+| 07 | [B2C Tax Invoices](./07-b2c-tax-invoice.md) | Consumer tax invoices, credit notes, and the outward-supplies register |
## Subsections
diff --git a/docs/payments/audits/2026-09-03-finance-verdicts.md b/docs/payments/audits/2026-09-03-finance-verdicts.md
new file mode 100644
index 000000000..ceba2b883
--- /dev/null
+++ b/docs/payments/audits/2026-09-03-finance-verdicts.md
@@ -0,0 +1,190 @@
+# Finance subsystem verdict record — 2026-09-03/04
+
+**Branch:** `docs/finance-train-verdicts` | **Date:** 2026-09-03/04 | **Scope:** every finance-labelled issue filed by the same-day audit (#1351–#1373, #1377), the older finance issue backlog, the `bugs/**` money notes, and an HLD/LLD review of the payments, payouts, tax and compliance subsystems.
+
+This document is the durable record of a full verification pass over the finance subsystem. An unverified audit had already run earlier the same day and filed #1351–#1373 plus #1377 as agent-written findings against untracked notes in `bugs/financial-audit/`. Before any of those findings were turned into code, every one of them was re-checked against `dev@e1766fa2d` and the live Supabase database. The headline result is that of 41 audit findings, 12 were real defects, 9 were already fixed, 14 were refuted or unsubstantiated, and 6 were minor polish items — and the single highest-severity defect in the subsystem turned out to be one the original audit had framed incorrectly (`#1347`, see §3 below). This PR closes #1373 (the SCIM doc-drift item folded into the same sweep) and is part of the #1319 finance productionization umbrella.
+
+## 1. What was audited, and how it was verified
+
+The verification ran three read-only Explore agents in parallel against the codebase (one per subsystem area: payments/webhooks, payouts/TDS/GST, and booking-side money boundaries), a fourth agent that triaged every claim in the `bugs/**` money notes against current code, direct reads of the highest-risk files by the orchestrator, and seventeen web checks against primary regulatory and vendor sources (Razorpay API docs, GST notifications, the Income-tax Act 2025, RBI PA directions). Nothing in this record is taken on an agent's say-so alone: every "real" verdict below cites the file, the live-database check, or the primary source that confirmed it.
+
+The table below records the regulatory and vendor facts that were re-verified on 2026-09-03 and the specific effect each one had on the plan.
+
+| Fact | Effect on the plan |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Razorpay refunds require `X-Refund-Idempotency` of at least 10 characters (`[A-Za-z0-9_-]`) and return 409 while a refund is in flight | The repo's refund idempotency handling was already correct. |
+| The `stripe-node` SDK takes the idempotency key as the second argument, `{ idempotencyKey }`, not inline in the params object | This shaped the PR-A fix in `lib/payments/core/stripe.ts`. |
+| GST-TCS under Section 52 has been 0.5% since 10-Jul-2024, applies only to registered suppliers, and is filed via GSTR-8 by the 10th of the following month | Confirmed the schema's stale "1%" comments were wrong and that TCS is not applicable at all under the Principal model this train adopted. |
+| Section 194-O has been 0.1% since 1-Oct-2024, with a ₹5 lakh threshold that applies only to individual/HUF payees who have furnished PAN, and a 5% no-PAN rate | `lib/compliance/tds-194o.ts` already implements the correct three-limb test. |
+| The Income-tax Act 2025, in force from 1-Apr-2026, renumbers Form 26Q to Form 140, Form 27Q to Form 144, Form 16A to Form 131, and replaces section labels with Section 393 payment codes 1001–1067 | The return export must emit Section 393 codes; Form 16A generation is a TRACES portal download, not a code gap, so #1364 closed. |
+| Razorpay orders never expire unless `expire_by` is set, and an authorized-but-uncaptured payment auto-refunds after five days | The audit's claim about trial-intent expiry (8.7) was wrong as stated. |
+| Razorpay webhooks are delivered at-least-once, carry `x-razorpay-event-id`, and retry for 24 hours before the endpoint is disabled | Confirmed the existing webhook inbox design is correct. |
+| The RBI Payment Aggregator Directions 2025 (15-Sep-2025) restrict split-settlement to contracted merchants | Confirmed the platform's Path C posture (Razorpay PG, RazorpayX payouts as a separate licensed rail) still stands. |
+| Netlify Scheduled Functions support standard cron syntax, cap each invocation at 30 seconds, and support every-minute cadence on paid plans | This is the design basis for the five-minute ticker in PR-F. |
+| QStash costs $1 per 100k messages (500/day free); Inngest gives 50k free events then $99/month; Temporal has a $100/month cost floor | All three stay deferred; none is justified by current volume. |
+| Section 9(5)'s deemed-supplier list excludes consulting services | Confirms that neither the Principal nor the facilitator GST reading is forced by statute — it is the platform's business-model choice, made with CA sign-off pending. |
+| CGST Rule 46 requires a tax invoice for every B2C taxable supply, and supplies of ₹50,000 or more require the buyer's name, address and state on that invoice | This is why a B2C tax invoice became a required deliverable under the Principal model rather than an optional one. |
+
+## 2. The eleven locked decisions
+
+Eleven decisions were locked with the user across three rounds of questions before any code was written, and every PR in the train respects them without exception.
+
+1. Refunds are in scope: the user's instruction was to fix everything refund-related the audit surfaced.
+2. The GST model is **Principal**: the platform is the supplier of record, keeps 18% GST on the full discounted price, issues B2C tax invoices itself, and does not collect GST-TCS under Section 52 pending a CA opinion (this downgraded #1360 and #1361 rather than building them).
+3. Stripe stays a dormant contingency behind Razorpay (the primary gateway) and the planned Dodo Payments integration for international buyers; this train fences Stripe rather than building it out to parity.
+4. Schema and database changes are allowed freely, because the platform is pre-MVP and the data is mock data; the one Supabase project serves both dev and prod, so `db push` runs once per merged PR, run by the orchestrator, and never for two schema-bearing PRs concurrently.
+5. The async posture stays **state-as-outbox plus a Netlify scheduled ticker**: no new generic outbox table, and no QStash adoption in this train.
+6. The cron fleet gets hygiene only in this train — scheduling the one orphaned job and flipping one job's `failMode` — not a consolidation, with QStash left for a later escalation.
+7. The leg invariant is defined as: `Payment.amount` stays the gateway charge, and `REFERRAL_CREDIT` legs are excluded from the funding sum that must equal it.
+8. The B2C deliverable is a statutory tax invoice, a credit note, and an outward-supplies register for the CA, not in-app GSTR JSON builders.
+9. Branch cleanup deletes the twelve already-merged remote branches and the local release branch only; open worktrees and open PRs are left untouched.
+10. Ten issues close by hand with evidence comments rather than through an automatic `Closes` link: #677, #738, #737, #837, #1020, #270, #1371, #1341, #1355, #1364.
+11. Core logic wins over test coverage for this train: no PR is test-only, and at most one compact pin lands per PR.
+
+## 3. Verdict table for the 2026-09-03 audit findings
+
+Every finding from the same-day audit (#1351–#1373, #1377) was checked against `dev@aa2ce08b8` (the commit the audit ran against) before this train started building. The table records the verdict, the evidence, and the PR that carries the fix. A blank PR column means the finding needed only a triage comment, not a code change.
+
+| Finding | Verdict | PR |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| 1.1/2.3 Stripe refund drops the idempotency key | **Real** — the Stripe button is live on every checkout page and `gateway-router.ts:52-60` honours it with no flag | #1386 |
+| 1.2 Stripe test-key guard missing | Real, but the fence makes it moot; the guard was added anyway | #1386 |
+| 1.3 no Stripe SDK timeout | Minor (the SDK default is 80 seconds); `timeout`/`maxNetworkRetries` set explicitly | #1386 |
+| 1.4 `session.url!` non-null assertion | Minor (the client already toasts on a null URL); replaced with an explicit throw | #1386 |
+| 1.5 refund issued without a status check | Overstated — the front-door guards already cover this; a one-liner hardened it further | #1386 |
+| 1.6 `amount \|\| undefined` | Overstated — every caller already guards for amounts above zero; a defensive throw was added | #1386 |
+| 2.1 client key rotates on remount | **Already fixed** by `findReusablePendingOrderPayment`, with a pinned test | comment only |
+| 2.2 undefined refund key silently skipped | Unsubstantiated — deliberate; the single caller always passes `Refund.id`; the type was tightened to require it | in flight (fix/finance-refund-webhook-plumbing) |
+| 3.1 lookup failure can lose a refund | Overstated — the `DeferSignal` plus sweeper re-drive already cover it; the residual gap (no gateway payment id stored on `Payment`) is closed by persisting `Payment.gatewayPaymentId` | in flight |
+| 3.2 the signature-verify route has no rate limit | Partly true — auth, ownership and a SUCCEEDED short-circuit already gate it; `checkoutLimiter` was added | in flight |
+| 3.3 no audit trail for client-side confirmation | Minor; a `recordSystemEvent` call was added | in flight |
+| 3.4/7.1 Stripe bypasses GST/TDS | **Refuted** — both gateways share `handleRefundCreated`; the real residual (Stripe's route omits `providerPaymentId` and throws instead of deferring) was fixed | #1386 |
+| 4.1/4.2 organization-side TDS never reaches `TDSRecord` or the return | **Real** and structural, though a runtime warning already existed and zero rows are affected today | #1389 |
+| 5.1 consultee conflict check runs at READ COMMITTED | Refuted — it runs inside the Serializable transaction with a fail-closed lock | closed #1355 |
+| 5.2 no GiST exclusion on the consultee side | Accepted design — the consultee lives on participants, not on `SlotOfAppointment` | closed #1355 |
+| 5.3 PENDING refunds lock a consultant's balance forever | Refuted — FAILED refunds release the hold, and a 24-hour placeholder cap already exists | closed #1355 |
+| 5.4 a five-minute stale window | Unsubstantiated — the CAS claim it rests on doesn't hold | closed #1355 |
+| 6.1 no outbox for side effects | Partly true — booking and money side effects are already re-driven; the Stream channel/notification leg was not, and is now | in flight |
+| 6.2 no alert during the defer window | Partly true (a 72-hour console warning already existed); a Sentry warning was added | in flight |
+| 7.2 dispute status parsed as `z.string()` | Refuted — `mapDisputeStatus` already maps to null with a protective default | comment only |
+| 7.3 refund currency unvalidated | Refuted — `toCurrencyEnum` already fails closed | comment only |
+| 7.4 an overage transition inside a transaction rolls back the whole invoice | Refuted as stated; the real, inverse issue is that the CAS-updated count was silently discarded, leaving the overage un-transitioned | #1385 |
+| 8.1 the `/support` route | Unsubstantiated — a deliberate prior fix already covers this | comment only |
+| 8.2 the cancel dialog's refund-rail copy | Mostly fixed — the single-rail copy already exists | comment only |
+| 8.3 `InvoicesPage` calling `window.open` | Unsubstantiated — no such code exists | comment only |
+| 8.4 no polling while a dispute is open | Minor; a `refetchInterval` was added | in flight |
+| 8.5 no toast for `REFUND_IN_FLIGHT` | Minor and admin-only; a toast mapping was added | in flight |
+| 8.6 the invoice PDF renders Helvetica with no Devanagari support | Real | feat/finance-b2c-tax-invoice |
+| 8.7 trial-intent never expires | Unsubstantiated — the parent page already gates on `paymentDueAt`, and Razorpay orders don't expire on their own | comment only |
+| 8.8 the overage preview ignores available credits | Unsubstantiated — credits are disallowed on the org path by design | comment only |
+| 9.1 dead code in `transactions.ts` | Trivial; the file was deleted | #1386 |
+| 9.2 the idempotency header is optional | Unsubstantiated — structural guards below the header already cover it | comment only |
+| 9.3 chaos-testing gaps | Superseded — the chaos harness already exists (#874) | comment only |
+| 9.4 an unknown Stripe status maps to PENDING | Minor; a warning log was added | #1386 |
+| N1 GST-TCS unshipped | Real as a schema gap, but **not applicable under the Principal model**; the schema comments' stale 1% rate (correct value is 0.5%) was fixed; #1360 was relabelled `compliance`, `launch: post-mvp`, and CA-gated | #1389 |
+| N2 no GSTR-1/3B/9 builders | Under the Principal model the platform needs its own outward-supply return, not in-app GSTR JSON builders, so this became a CSV register for the CA instead; #1361 was re-scoped | feat/finance-b2c-tax-invoice |
+| N3 no 26Q/140 FVU export | A CSV export for the CA, never an FVU file; #1362 was re-scoped | #1389 |
+| N4 non-resident forms (27Q/144, 15CA/CB, §195) | Stays post-MVP and blocked; #1363 stays open | — |
+| N5 no Form 16A generation | Not a code gap — Form 16A is a TRACES portal download, and the schema already stores the certificate number; #1364 closed | closed #1364 |
+| N6 `Payment.consumerStateCode` never written | **Real** — confirmed zero writers and zero readers on the live schema | feat/finance-b2c-tax-invoice |
+| N7 float TDS rates | Tech debt — the persisted values are already basis points; #1367 stays open | — |
+| N8 the `TdsRate` table is unused | Tech debt, CA-gated; #1368 stays open | — |
+| N9 SAC 999293 vs the 9983xx family | A CA classification decision; #1369 stays open | — |
+| N10 the `reportedInGstr1` flag | Folded into the register export instead of standing alone | feat/finance-b2c-tax-invoice |
+| N11 IRP upload stubbed | Post-MVP — the AATO threshold is ≥ ₹5 crore, which is nowhere near current volume; #1366 relabelled post-mvp | — |
+| N12 wallet auto-charge | Duplicate of an existing #863 bullet | closed #1371 |
+| N14 `CREDIT_POOL` refund round-trip untested | Test-only, and the user's decision this train is core logic over tests; #1372 stays open with a comment | — |
+| #1341 cron lock fail-open | **Not an issue** — no such code branch exists; the lock only fails open when Redis is unconfigured (`isMockRedis`), and seven tests already pin that behaviour; `expire-stale-requests` was still flipped to fail-closed because it issues refunds | closed #1341; #1390 |
+| #1347 referral-credit legs break the funding-sum invariant | **Real, P0 in effect** — the `payment_legs_sum_to_amount` trigger is live on the database, so any referral-credit checkout failed at commit with a `check_violation`. The schema, the checkout code and the trigger disagreed with each other about whether `Payment.amount` is the pre-credit or post-credit figure | #1385 |
+| #1377 LIVE Razorpay keys are still gated | Correct operational posture; no change needed | — |
+
+## 4. Older-issue verdicts and the `bugs/**` counts
+
+The older finance-adjacent issue backlog was re-triaged alongside the new findings. The table below records the disposition for each issue that was in scope.
+
+| Issue | Verdict | Action |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| #270 service factory | Legit low-priority item, superseded by #1375 item C1 | closed as superseded |
+| #366 recording monetization | Out of scope for this train (it belongs to the Stream subsystem); Phase 2 partly landed as `RecordingPurchase` | left open |
+| #481 billing guardrails | An infrastructure issue, not a finance one; three of its code items (`take:` caps, `minimumCacheTTL`) are still true | left open, nothing dropped |
+| #677 master finance tracker | Its open tail was re-filed 1:1 by today's audit | closed as superseded, with a comment mapping it to the successor issues |
+| #738 / #737 B2C compliance | Same lineage as #677, now a fourth generation of the same tracker | closed as superseded |
+| #770 contract lifecycle gaps | A legitimate post-MVP UI/feature gap | left open |
+| #837 umbrella | Only #874 remains open under it, and the issue author confirmed the remaining checkboxes are decorative | closed as superseded by #1319/#874 |
+| #863 residuals register | Two of its boxes were stale (`ScimToken` expiry and the multi-collaborator journal are both done) | comment added, issue kept open |
+| #1020 dispute edge cases | Items 1, 2, 3 and 5 shipped with issue references in code; item 4 is a separate queue-cluster concern | closed as partly-fixed, remainder tracked in #1010 |
+| #1092 database observability | The first checkbox is done; the rest are deferred to scale | comment added, issue kept open |
+| #1135 priority DMs | A post-MVP feature request | left open |
+| #1246 durable intent cancellation | A legitimate low-priority hygiene item (orphaned orders cannot currently be paid) | comment added, issue kept open |
+| #1314 storage vendor decision | Out of scope for finance | left open |
+| #1319 umbrella | Owner action items remain | kept open, this train linked |
+| #1349 frozen decisions pointer | A documentation pointer, not an engineering gap | kept open |
+| #1375 god-module epic | Kept open — both files it names grew again during this train | kept open |
+| #866/#1010 QStash | Kept open; the Netlify ticker in #1390 is the interim measure | comment added |
+| #705/#688/#692 | Partially fixed (items REF-2/3/5 and SC-1/16 are done) | progress comments added |
+
+### `bugs/**` money-note counts
+
+The `bugs/**` folder's money-related claims (142 in total across the finance and enterprise-money dossiers) were re-checked one by one: 63 are still true today (mostly by design, behind a flag, or already tracked in one of today's issues), 65 have been addressed since the note was written, and 14 are stale. Nothing beyond the findings already recorded in §3 turned up new work, with two exceptions, both doc-drift: the `prisma/schema.prisma` comment near line 4002 said `allocationIdempotencyKey` wiring was "tracked in #837" when the column has in fact been wired since the allocate routes started reading the `Idempotency-Key` header (fixed by this PR, §6 below), and `payment-legs-triggers.sql` is applied only through the `npm run db:leg-triggers` script rather than through the ordinary `db push` path, which this record calls out explicitly so nobody assumes a schema push alone fixes a broken trigger. The disposition for the whole folder is: annotate every file with a verdict blockquote pointing back to this record, and delete the untracked `bugs/financial-audit/` directory now that its findings have been folded into a committed record.
+
+## 5. HLD/LLD verdicts and the distributed-systems answers
+
+### What stays — genuine and load-bearing
+
+The double-entry journal (`LedgerTransaction`/`LedgerEntry`) with its reconciled caches, the `PaymentLeg` stacking model, time-scoped `RateCard` snapshots, CAS-in-WHERE state transitions, the fail-closed Redis mutex layered with Serializable transactions and Postgres GiST exclusion, two-phase refunds with a reserve row, the single-writer confirmation pipeline (ADR 21), the `WebhookEvent` inbox, `OrgAuditLog`/`SystemEvent`/`SystemJobExecution` as the audit trail, the batched payout state machine, and `PENDING_TRUST` earnings parking are all genuine, working machinery. Replacing any of this with a ledger vendor such as Formance or Modern Treasury would trade working code for a new dependency and buy nothing.
+
+### What was under-engineered, and is now built
+
+A B2C tax invoice with place of supply and an outward-supplies register was missing entirely, and the Principal GST model makes them statutory rather than optional. Organization-side TDS never reached the return builder. The credit-leg invariant was a blocking defect rather than a documentation mismatch. `Payment` never persisted the gateway's own payment identifier, which made refund lookups fragile. Stripe had no fence around it despite being dormant. The GitHub Actions cron cadence could not deliver sub-hourly reliably. The Stream channel/notification side effect of a payment was not re-driven on failure the way the money side effects already are. All of these are addressed by this train.
+
+### What was over-engineered or premature, and stays untouched
+
+Stripe should stay fenced, not deleted, since it remains the contingency gateway. The GST-TCS and GSTR-8 machinery stays dormant and CA-gated rather than being built out. Form 15CA/CB, Section 195 and non-resident handling stay out of scope. The `TdsRate` table stays unused until a CA asks for it. The IRP e-invoicing uploader stays gated behind the AATO threshold. The 74 one-job-per-file cron workflows are boilerplate-heavy but consolidating them would not fix a correctness problem, so they stay as-is. `CHARGE_MEMBER` overage billing stays fail-closed because no program is configured to use it yet. A multi-currency ledger stays out of scope — settlement is INR-only by design, with Dodo Payments deferred to a later international push.
+
+### The six distributed-systems answers
+
+The user asked six explicit architecture questions during this train; each is answered once here rather than scattered across PR descriptions.
+
+1. **Outbox pattern.** The outbox pattern is already present three times over — domain rows such as `Payment`, `Appointment`, `Refund`, `WalletTopUp`, `WebhookEvent`, `OutboundWebhookDelivery` and `FailedEmail` already carry the durable state a generic outbox table exists to provide. No new table was added; instead the cron cadence that drains those rows was fixed (§6a below).
+2. **Double-entry ledger.** Yes, one is already built and reconciled nightly; it stays as-is.
+3. **Audit trails.** The existing trail is sufficient; the one addition this train made was a `SystemEvent` for the client-side payment confirmation source, which had no audit record before.
+4. **Optimistic versus pessimistic locking.** Both are used, deliberately layered: a short pessimistic Redis mutex guards the hot 30-minute slot atom, optimistic CAS plus Serializable retry guards state transitions more broadly, and a Postgres GiST exclusion constraint is the last line of defence on the consultant side. Pending payments and approvals expire via `expiresAt` plus CAS sweeps, and an approval lock's TTL is set equal to its transaction timeout. None of this changes.
+5. **Reconciliation.** Reconciliation exists for four distinct purposes — gateway truth versus the database, the ledger's cached balances versus its journal, crash-gap re-drives, and time-based expiry — and every scheduled job in the inventory maps to exactly one of those purposes, so none of it is redundant.
+6. **Message brokers.** Kafka and RabbitMQ are not justified: there is no consumer host for them, and current volume is three to four orders of magnitude too low to need one. QStash is the correct next escalation but not for this train. Inngest's adoption trigger has not been met. Temporal's cost floor exceeds the problem it would solve.
+
+### Cron classification
+
+The 74 scheduled workflows in the repository were classified by subsystem and by purpose. By subsystem: 10 are booking, 15 are finance-B2C, 12 are finance-B2B billing, 4 are payouts, 6 are compliance-tax, 9 are Stream, 11 are auth/cleanup, 6 are CI/tooling, and 1 is observability. By purpose: 28 are reconcile/sweep jobs, 22 are ordinary business jobs, 12 are operational, 6 are alerting, 3 are CI, and 3 are test-only. Two orphans turned up during this classification: `tds-26q-draft-export.ts` had no GitHub Actions workflow at all (fixed by #1389, which adds `tds-return-draft.yml`), and `gstr8-draft-export.yml` is dispatch-only, which is correct while GST-TCS collection stays dormant.
+
+## 6. Two live-database findings that changed the picture
+
+Two findings surfaced only by querying the live database, not by reading source, and both changed what this train had to fix.
+
+**The `payment_legs_sum_to_amount` trigger was broken on every leg write.** `prisma/sql/payment-legs-triggers.sql` defines `assert_payment_legs_on_leg_write()` with bare, unquoted references to `NEW.paymentId` and `OLD.paymentId`. Postgres folds unquoted identifiers to lowercase, so those references resolved to a column named `paymentid`, which does not exist on `PaymentLeg` (the real column is the quoted, camelCase `"paymentId"`). Pulling the live function body via `pg_get_functiondef` confirmed the bare references were exactly what shipped, which means the trigger has raised on every single leg write since the last time the trigger function itself was written, around 2026-07-28. #1385 fixes the identifiers to the quoted form and excludes `REFERRAL_CREDIT` legs from the sum at the same time; `npm run db:leg-triggers` must be re-run after that PR merges, because `prisma db push` does not manage triggers.
+
+**`Payment.consumerStateCode` had zero writers.** The column has existed in the schema, but nothing in `lib/payments/operations/checkout.ts` or anywhere else ever wrote to it, and nothing ever read it either. This is one of the reasons a B2C place-of-supply capture became a required deliverable of the Principal-model train (`feat/finance-b2c-tax-invoice`) rather than a nice-to-have: the column was reserved for exactly this and had sat empty since it was added.
+
+## 6a. Post-merge deployment runbook
+
+This runbook applies once per merged PR in the train, run by the orchestrator, and never for two schema-bearing PRs at the same time, because a single Supabase project serves both dev and prod.
+
+1. After every merge that touches `prisma/schema.prisma` (PR-D/#1389, PR-B, PR-E), run `npm run db:push` — which chains `db:sidecars` (triggers, leg triggers and CHECK constraints) — and then `npm run db:assert-sidecars` to confirm the sidecar objects actually landed.
+2. After #1385 (PR-C) merges, run `npm run db:leg-triggers` even though that PR has no schema change of its own, because the live trigger described in §6 above is broken on every leg write until that script re-applies it; `db push` alone does not manage triggers.
+3. Before the first live run of the new jobs, confirm the secrets are in place: the GitHub Actions `PAN_ENCRYPTION_KEY` for `tds-return-draft` (a missing key produces a blank PAN column and a silent exit 0, not a failure), the Supabase storage credentials already present in the secrets manifest, the Netlify production `CRON_SECRET` for the ticker plus the optional `CRON_TICK_BASE_URL`, `STRIPE_ENABLED` and `NEXT_PUBLIC_STRIPE_ENABLED` left unset, `PLATFORM_INVOICE_PREFIX` (optional, defaults to `FAM`), and `PLATFORM_GSTIN` plus `SUPPLIER_STATE_CODE`, both of which must be real values before the first consumer invoice mints — until then the mint step no-ops with a log line, and the register healer catches up once they're set.
+4. Verify on the Netlify deploy preview that `cron-tick` fires every five minutes in the function log, that every route it calls answers 200 or 207 inside the 26-second function ceiling, and that a concurrent GitHub Actions dispatch of the same route returns 409 because the lock is held.
+5. Owner actions that stay outside code: CA sign-off on ADR 26 (the questions listed there, plus #1388), rotating in Razorpay LIVE keys (#1377), and the load-gate exit criteria (#874).
+
+## Owner actions this train cannot complete
+
+- CA sign-off on the Principal GST model plus the 194-O operator pairing (ADR 26's question list, plus #1388's referral-credit question).
+- Rotating in Razorpay LIVE keys (#1377).
+- Confirming the Netlify team plan supports the five-minute ticker schedule — verified 2026-09-03 via `netlify api listAccountsForUser` that the Practitionist-Deploys team is on the Pro plan, so this is a note rather than a blocker.
+- Leaving `STRIPE_ENABLED` unset in the production environment until Stripe is deliberately reactivated.
+- Running the **pr-comment-triage** skill and the Sonar MCP quality-gate check on every PR in the train, which is a post-merge reminder rather than a deliverable of this PR.
+
+## Related
+
+- ADR 26 — [`docs/enterprise/70-design-decisions/26-gst-principal-model.md`](../../enterprise/70-design-decisions/26-gst-principal-model.md).
+- `docs/compliance/02-gst-overview.md`, `docs/compliance/15-india-compliance-shipping-checklist.md`, `docs/compliance/10-rbi-pa-and-payment-architecture.md`, `docs/finances/07-tax-compliance-marketplace-obligations.md`.
+- PR-C #1385, PR-A #1386, PR-D #1389, PR-F #1390, PR-B (`fix/finance-refund-webhook-plumbing`, in flight), PR-E (`feat/finance-b2c-tax-invoice`, in flight).
+- #1319 (umbrella), #1387 (Stripe dispatcher untyped), #1388 (CA question on referral credits vs GST).
diff --git a/docs/payments/checkout-flow/01-overview-and-consultation.md b/docs/payments/checkout-flow/01-overview-and-consultation.md
index 645ee8dba..8775090a3 100644
--- a/docs/payments/checkout-flow/01-overview-and-consultation.md
+++ b/docs/payments/checkout-flow/01-overview-and-consultation.md
@@ -107,6 +107,8 @@ All checkout data is stored in payment intent metadata:
> **Webhook backward-compat note:** Razorpay order `notes` objects embedded with the old keys (`startsAt` / `endsAt`) are still accepted by the webhook handler for in-flight orders created before the rename. `normalizeLegacySlotKeys()` in `schemas/webhooks/metadata.ts` maps old → new on ingest; new orders always use `startsAt` / `endsAt`.
```
+> **Empty optional fields are omitted, never sent as `""` (#1462).** `buildPaymentMetadata()` in `lib/payments/operations/checkout.ts` includes an optional key only when it has a value, because the webhook schemas type those fields with `.optional()`, which accepts an absent key and rejects an empty string. A subscription bought for a scheduling period carries no direct slot times, so it used to reach the gateway with `startsAt: ""` and `endsAt: ""`, and every capture webhook for such a sale then failed validation and stamped the payment `REQUIRES_MANUAL_RECOVERY` with the buyer already charged. Because a Razorpay order never expires, orders minted before the fix keep replaying with those empty strings, so `validateWebhookMetadata()` also strips empty-string entries before it normalizes legacy keys and parses. Omitting empty keys has the useful side effect of giving the fifteen-key gateway ceiling more headroom.
+
**Benefits:**
- Webhook can recreate appointment even if frontend crashes
@@ -133,27 +135,38 @@ await prisma.$transaction(async (tx) => {
// - Webhook will be retried by gateway
```
-### 5. Three-Layer Race Condition Protection
+### 5. Slot Occupancy Checks and the Buyer's Own Hold
-For consultation and subscription slot bookings:
+For consultation and subscription slot bookings, `validateSlotAvailability()` runs two blocking checks. The first rejects the request when any live appointment overlaps the requested window for this consultant, which includes another buyer's tentative hold. The second rejects it when the requesting buyer already holds an overlapping window with a live pending payment.
```typescript
-// Layer 1: Check confirmed bookings
-if (overlappingConfirmedBooking exists) {
+// Check 1: any live overlapping appointment for this consultant
+if (overlappingLiveAppointment exists) {
throw Error("Time slot is already booked");
}
-// Layer 2: Check same user duplicates
-if (userHasPendingBookingForThisSlot) {
- throw Error("You already have a pending booking");
-}
-
-// Layer 3: Rate limiting
-if (pendingAttempts >= 3) {
- throw Error("Time slot temporarily unavailable due to high demand");
+// Check 2: this buyer's own overlapping live hold
+if (buyerHasOverlappingPendingHold) {
+ throw Error("You already have a pending booking for this time slot...");
}
```
+Both checks subtract the buyer's **self-hold** (#1463). A self-hold is an appointment that belongs to the requesting buyer, is for the same plan, has a payment that is still `PENDING` and still inside its expiry window, and covers exactly the window being requested. Such an appointment is not an occupant of the slot; it is the buyer's own open gateway order, and the open-order resume described below is the path that finishes or replaces it. Anything else keeps blocking, including a different buyer's hold on the same slot, a hold on a different plan, and this buyer's own hold on a window that merely overlaps the requested one. When the plan identity cannot be resolved at all, as with webinars and classes whose slot rows are shared between attendees, nothing is excluded.
+
+Exact coverage is compared against the appointment's whole slot run rather than a single row, because a booked window is stored as a series of contiguous thirty-minute atoms: the run's first start and last end are what must equal the request.
+
+The consultee-side conflict check inside the checkout lock applies the same exclusion, so the buyer's own hold does not resurface there as "You already have a session booked during this time."
+
+There is deliberately no per-slot attempt cap. Since check 1 blocks on any live hold, a count of pending attempts for one slot can never exceed one, so the hold itself is the cap.
+
+### 6. Open-Order Reuse
+
+A checkout that is remounted, reopened in a new tab, or retried after the buyer dismissed the gateway modal mints a fresh client idempotency key, so the same-key replay cannot recognise it. Before any gateway call, `findReusablePendingOrderPayment()` therefore looks for an open order the buyer can simply finish paying: a payment of theirs that is still `PENDING`, still inside its minted expiry window, on the same gateway, under the same organization, and joined to an appointment for the same plan.
+
+A candidate is adopted only when it is for the same booking as the current request. A consultation candidate must cover exactly the requested slot window, a subscription candidate must carry exactly the requested scheduling period, and every candidate's frozen amount must equal the total this request computed, so a changed coupon or credit balance can never be charged at a stale price. When a candidate is adopted, checkout returns the existing order id, amount and currency with `reused: true` and creates no second appointment and no second payment.
+
+Candidates that fail those gates are **superseded** rather than left open. Superseding runs in one transaction: the payment moves `PENDING` → `EXPIRED` through a compare-and-set that carries the old status in its `WHERE` clause, the appointment's tentative slots are cancelled through `transitionSlotCompletion()`, and the parent consultation or subscription is cancelled through its own guarded transition. Releasing the hold is not optional bookkeeping. If the payment were expired while its appointment kept occupying the calendar, the buyer's very next attempt would be rejected by the occupancy check above, which is the wall #1463 describes. Group events are excluded from the release because their slot rows are shared between attendees, so giving back a seat is a disconnect rather than a status move and belongs to the cancel-pending front door.
+
---
## Consultation Checkout Flow
diff --git a/docs/payments/checkout-flow/03-payment-processing.md b/docs/payments/checkout-flow/03-payment-processing.md
index 4549882e0..0cdd406dd 100644
--- a/docs/payments/checkout-flow/03-payment-processing.md
+++ b/docs/payments/checkout-flow/03-payment-processing.md
@@ -263,13 +263,13 @@ export async function createStripeCheckoutSession({
#### Currency Conversion:
-```typescript
-// Lines 56-59
-const toSmallestUnit = (amount: number, currency: string): number => {
- const multiplier = CURRENCY_MULTIPLIERS[currency] || 100;
- return Math.round(amount * multiplier); // USD: 100 cents per dollar
-};
-```
+There is none, and there has not been any since the paise migration. Every money
+column in the schema already holds an integer count of the smallest unit, so the
+amount is handed to the gateway exactly as it is stored. The
+`CURRENCY_MULTIPLIERS` table this section used to show was deleted in #1396
+because nothing imported it. Settlement is INR-only in any case:
+`assertInrSettlement` is the first statement of both `createRazorpayOrder` and
+`createStripeCheckoutSession`, so a non-INR currency never reaches a gateway.
### 2.4 Razorpay Integration
diff --git a/docs/payments/gateways/README.md b/docs/payments/gateways/README.md
index 08229f4e2..0043dc610 100644
--- a/docs/payments/gateways/README.md
+++ b/docs/payments/gateways/README.md
@@ -202,7 +202,7 @@ Both gateways share a common abstraction layer:
| File | Purpose |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lib/payments/index.ts` | Unified orchestration — routes `createPaymentIntent()`, `cancelPaymentIntent()`, `createRefund()` to the correct gateway |
-| `lib/payments/core/types.ts` | Shared types (`PaymentIntent`, `RefundResult`, `DisputeResult`), error classes (`PaymentError`, `RefundError`, `DisputeError`), `CURRENCY_MULTIPLIERS` |
+| `lib/payments/core/types.ts` | Shared types (`PaymentIntent`, `RefundResult`, `DisputeResult`) and the error classes (`PaymentError`, `RefundError`, `DisputeError`) |
| `lib/payments/payouts/payout-service.ts` | Provider-agnostic payout orchestration (batch creation, admin approval, processing) |
| `lib/payments/payouts/earnings-service.ts` | Earnings calculation with flat 20% platform fee |
| `lib/payments/payouts/constants.ts` | Hold periods, minimum amounts, fee percentages, payout mode limits |
diff --git a/docs/payments/gateways/razorpay/01-setup.md b/docs/payments/gateways/razorpay/01-setup.md
index e010ac10f..bf89a24f0 100644
--- a/docs/payments/gateways/razorpay/01-setup.md
+++ b/docs/payments/gateways/razorpay/01-setup.md
@@ -112,14 +112,16 @@ Dashboard > Settings > Webhooks > Add New Webhook
**Events to select**:
-| Category | Events |
-| ------------------ | --------------------------------------------------------------------------------------------------------------- |
-| Payment | `payment.captured`, `order.paid`, `payment.failed` |
-| Refund | `refund.created`, `refund.processed`, `refund.failed` |
-| Dispute | `payment.dispute.created`, `payment.dispute.won`, `payment.dispute.lost`, `payment.dispute.closed` |
-| Payout (RazorpayX) | `payout.processed`, `payout.reversed`, `payout.rejected`, `payout.queued`, `payout.pending`, `payout.cancelled` |
+| Category | Events |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Payment | `payment.captured`, `order.paid`, `payment.failed` |
+| Refund | `refund.created`, `refund.processed`, `refund.failed` |
+| Dispute | `payment.dispute.created`, `payment.dispute.under_review`, `payment.dispute.action_required`, `payment.dispute.won`, `payment.dispute.lost`, `payment.dispute.closed` |
+| Payout (RazorpayX) | `payout.processed`, `payout.failed`, `payout.reversed`, `payout.rejected`, `payout.queued`, `payout.pending`, `payout.cancelled` |
-Copy the webhook secret after creation and store it in the appropriate environment variable.
+This list is the same one the go-live checklist requires, and it is the exact set the dispatcher in `app/api/webhooks/razorpay-dispatch.ts` handles. Omitting `payout.failed` is the expensive mistake, because it is the terminal event that tells the platform a bank refused the transfer; without it the earnings stay batched against a payout that will never arrive.
+
+Copy the webhook secret after creation and store it in the appropriate environment variable. Each mode has its own webhook secret, so the value generated in test mode will reject every live delivery and vice versa. Rotating the secret later is a two-sided change and must follow the grace-window procedure in [05-go-live-checklist.md](./05-go-live-checklist.md), because a hard cutover loses the events signed during the gap and Razorpay disables a webhook that has been failing for 24 hours.
### Test Mode vs Live Mode
@@ -214,3 +216,4 @@ Set the ngrok URL as your webhook endpoint in the Razorpay dashboard.
- [02-architecture-and-flow.md](./02-architecture-and-flow.md) — Payment flow and revenue split
- [03-payout-flow.md](./03-payout-flow.md) — RazorpayX payout system
- [04-kyc-and-onboarding.md](./04-kyc-and-onboarding.md) — KYC requirements
+- [05-go-live-checklist.md](./05-go-live-checklist.md) — What must be true before the first live rupee
diff --git a/docs/payments/gateways/razorpay/03-payout-flow.md b/docs/payments/gateways/razorpay/03-payout-flow.md
index 1452126c3..017d3c5de 100644
--- a/docs/payments/gateways/razorpay/03-payout-flow.md
+++ b/docs/payments/gateways/razorpay/03-payout-flow.md
@@ -208,15 +208,20 @@ Webhook confirms status
### RazorpayX Payout Status Mapping
-| RazorpayX Status | Internal Status | Description |
-| ---------------- | --------------- | ---------------------------- |
-| `queued` | PENDING | Queued due to low balance |
-| `pending` | PENDING | Awaiting processing |
-| `processing` | PROCESSING | Being processed by RazorpayX |
-| `processed` | COMPLETED | Funds transferred to bank |
-| `reversed` | FAILED | Bank returned the funds |
-| `rejected` | FAILED | Payout rejected by RazorpayX |
-| `cancelled` | CANCELLED | Payout cancelled |
+RazorpayX has three intermediate payout states and five terminal ones, and every terminal state must map to a terminal internal state. If a terminal gateway state is read as an intermediate one, the payout never leaves PROCESSING, its earnings stay BATCHED, and the consultant is neither paid nor re-queued. The mapping below is the full set as documented at [RazorpayX Payout Status](https://razorpay.com/docs/x/payouts/status-details/).
+
+| RazorpayX Status | Internal Status | Description |
+| ---------------- | --------------- | --------------------------------------------------------- |
+| `queued` | PENDING | Queued due to low balance |
+| `pending` | PENDING | Awaiting approval in the RazorpayX approval workflow |
+| `processing` | PROCESSING | Being processed by RazorpayX |
+| `processed` | COMPLETED | Funds transferred to bank |
+| `reversed` | FAILED | Bank returned the funds; RazorpayX credited us back |
+| `rejected` | FAILED | Approval was refused or lapsed |
+| `failed` | FAILED | The transfer failed at RazorpayX, the bank, or in transit |
+| `cancelled` | CANCELLED | A queued payout was cancelled manually |
+
+An unrecognised status deliberately maps to PENDING rather than to a terminal state, because "we do not know yet" must keep the reconciler polling instead of settling a payout on a guess.
---
@@ -227,6 +232,7 @@ Webhook confirms status
| `payout.processed` | Funds transferred successfully | Mark payout COMPLETED, earnings as PAID |
| `payout.reversed` | Bank returned funds | Mark payout FAILED, restore available balance |
| `payout.rejected` | RazorpayX rejected payout | Mark payout FAILED, alert admin |
+| `payout.failed` | Transfer failed at the bank | Mark payout FAILED, return earnings to READY |
| `payout.queued` | Insufficient balance, queued | Update payout status to PENDING |
| `payout.pending` | Payout pending processing | Update payout status |
| `payout.cancelled` | Payout cancelled | Mark payout CANCELLED |
@@ -250,9 +256,11 @@ Webhook confirms status
Since March 2025, RazorpayX **requires** an idempotency key on every payout request. This prevents duplicate payouts if a request is retried.
-The system generates idempotency keys using the payout ID and timestamp: `payout_{payoutId}_{timestamp}`
+The key must be deterministic for a given payout, because that is the only property that makes a retry safe. `generateIdempotencyKey` in `lib/payments/payouts/razorpay-payouts.ts` therefore returns `payout_{payoutId}` and nothing else. An earlier version appended a timestamp, which produced a fresh key on every attempt and so defeated the mechanism entirely: a retry after a timeout would have submitted a second payout for the same earnings. Do not reintroduce a clock, a random suffix or an attempt counter into this key.
+
+The key is sent via the `X-Payout-Idempotency` header. When the payout row already carries an `idempotencyKey`, that value is used ahead of the generated one, so every attempt on a given row lands on the same RazorpayX idempotency slot.
-The key is sent via the `X-Payout-Idempotency` header.
+RazorpayX bounds that header at 4 to 36 characters drawn from letters, digits, hyphens, underscores and spaces, and answers anything else with a 400. Two of our keys overshoot it: an organization payout derives `payout_`, which is 43 characters, and a consultant payout persists `payout__`, which is 72. `boundPayoutIdempotencyKey` therefore folds any key the gateway would refuse onto a 34-character digest of itself at the point the header is written. The fold is a pure function of the key, so determinism is preserved and a retry still returns the original payout rather than creating a second one. The persisted `idempotencyKey` is left alone, because it is also the row's unique constraint and the Stripe transfer key, and neither of those is bounded the way this header is.
---
diff --git a/docs/payments/gateways/razorpay/05-go-live-checklist.md b/docs/payments/gateways/razorpay/05-go-live-checklist.md
new file mode 100644
index 000000000..c6289d098
--- /dev/null
+++ b/docs/payments/gateways/razorpay/05-go-live-checklist.md
@@ -0,0 +1,115 @@
+# Razorpay Go-Live Checklist
+
+> What has to be true before the platform accepts its first rupee of real money through Razorpay, and what has to be verified in the Razorpay dashboard rather than in this repository.
+
+**Last Updated**: 2026-09-05 · **Tracking issue**: #1377
+
+---
+
+## How to read this page
+
+This checklist covers the payments product only. Consultant and organisation disbursement through RazorpayX is gated separately by `ENABLE_LIVE_PAYOUTS` and has its own runbook at [docs/enterprise/50-operations/06-live-payout-go-live-runbook.md](../../../enterprise/50-operations/06-live-payout-go-live-runbook.md); do not treat the two as one cutover, because accepting money and disbursing money can safely go live weeks apart.
+
+Several items below cannot be verified from the codebase at all. Auto-capture, the settlement cycle and the uncaptured-payment refund window are account settings that live in the Razorpay dashboard, and no amount of reading `lib/payments/core/razorpay.ts` will tell you how they are configured. Those items are marked as dashboard checks, and they need a screenshot or a dashboard link recorded against the issue rather than a code reference.
+
+---
+
+## 1. Account activation
+
+The account has to be activated before live keys do anything at all, and activation is not instantaneous.
+
+- [ ] KYC is submitted and approved, and the dashboard shows the account as activated. Razorpay quotes one to three business days for this, and a rejection restarts the clock.
+- [ ] The settlement bank account on the Razorpay account is the platform's current account, and the account holder name matches the registered business name exactly.
+- [ ] GSTIN is recorded on the Razorpay account. This is what lets Razorpay issue us a compliant invoice for its own fees, which we need for input tax credit; it is unrelated to the tax invoices this platform issues to consumers, which are minted in-house (see [../../07-b2c-tax-invoice.md](../../07-b2c-tax-invoice.md)).
+- [ ] If international cards are ever to be accepted, domestic acceptance is activated first and video KYC is complete. International acceptance is a separate approval, not a toggle.
+
+---
+
+## 2. Keys and the test-key guard
+
+The platform holds two unrelated Razorpay credential pairs and one webhook secret per mode, and confusing any two of them is the most common cause of a silent outage.
+
+- [ ] `RAZORPAY_KEY_ID` and `RAZORPAY_SECRET` hold the **live** key pair, with `rzp_live_` as the key id prefix. Note that the secret's variable name is `RAZORPAY_SECRET` in this repository and not `RAZORPAY_KEY_SECRET`; only the legacy readers under `scripts/` accept the second name.
+- [ ] `NEXT_PUBLIC_RAZORPAY_KEY_ID` holds the same live key **id**. It is the only Razorpay value that may ever be public, and neither secret may ever be given a `NEXT_PUBLIC_` prefix.
+- [ ] `RAZORPAY_ALLOW_TEST_KEYS_IN_PRODUCTION` has been **deleted** from the production environment. While it is set to `true`, a test key under `NODE_ENV=production` only logs a loud error instead of throwing, which is deliberate for the pre-launch period when signup is closed and checkout is exercised with test cards. Once live keys are in place the variable has no legitimate use, and leaving it behind removes the guard that would otherwise catch a future accidental rollback to test keys.
+- [ ] A production boot has been observed after the change. The test-key guard in `lib/payments/core/razorpay.ts` runs at module load, so a misconfigured production posture fails at require time rather than at the first customer — which means the deploy either comes up clean or does not come up at all.
+
+---
+
+## 3. Webhooks
+
+Webhook delivery is how the platform learns that money moved. Everything else is best effort.
+
+- [ ] A webhook is registered in **live** mode pointing at `https:///api/webhooks/razorpay` over HTTPS on port 443.
+- [ ] `RAZORPAY_WEBHOOK_SECRET` in the production environment holds the **live** webhook secret, which is a third value distinct from both the API secret and the test-mode webhook secret. A test-mode secret in production rejects every live delivery with a 400.
+- [ ] The selected events are exactly the ones the dispatcher handles: `payment.captured`, `order.paid`, `payment.failed`, `refund.created`, `refund.processed`, `refund.failed`, `refund.speed_changed`, the six `payment.dispute.*` events, and the seven `payout.*` events. Selecting an event the dispatcher does not handle is harmless because unknown events are logged and acknowledged with a 200, but omitting a handled one loses the state transition entirely.
+- [ ] The Alert Email Address on the webhook is a monitored inbox. Razorpay emails it when it disables a webhook, and that email is the only notification of the failure mode described below.
+- [ ] A signed test delivery has reached production and produced a `WebhookEvent` row. The recipe lives in the Razorpay skill at `.claude/skills/razorpay/references/local-testing.md`; the signature is an HMAC-SHA256 of the exact bytes posted, so it must be generated from the same string that is sent.
+
+### Why a non-2xx is dangerous here
+
+Razorpay treats every non-2xx response as a delivery failure, retries on an exponential backoff for 24 hours, and then **disables the webhook** ([webhook FAQs](https://razorpay.com/docs/webhooks/faqs/)). A disabled webhook is not merely paused: events that fire while it is disabled are never delivered, and Razorpay has no self-serve replay. Recovering them means a support ticket, only works for events under 15 days old, and only works if the webhook was enabled when the event fired. This is why the route returns 200 for events it does not handle and reserves 503 for the single case where a retry is genuinely wanted, namely an unreachable database.
+
+### Rotating the webhook secret
+
+Rotating `RAZORPAY_WEBHOOK_SECRET` is a two-sided change that cannot be made atomically, because the operator saves the new secret in the Razorpay dashboard and the platform picks it up only on the next deploy. Every event signed in that gap would be rejected, and a long enough gap ends in the disabled webhook described above.
+
+`RAZORPAY_WEBHOOK_SECRET_PREVIOUS` exists to close that window, mirroring for inbound deliveries what [ADR 09](../../../enterprise/70-design-decisions/09-webhook-rotation-grace.md) does for outbound ones. The procedure is:
+
+1. Set `RAZORPAY_WEBHOOK_SECRET_PREVIOUS` to the current secret and deploy. Nothing changes yet, because the current secret still verifies everything.
+2. Generate the new secret in the Razorpay dashboard, set `RAZORPAY_WEBHOOK_SECRET` to it, and deploy. Deliveries signed with either secret now verify.
+3. Watch the operations timeline. Every delivery that only the previous secret can verify writes a `WEBHOOK`/`WARN` system event naming the variable, so the rotation is visibly finished when those stop.
+4. Delete `RAZORPAY_WEBHOOK_SECRET_PREVIOUS` and deploy. The old secret stops being honoured.
+
+Leaving the variable set indefinitely defeats the purpose of rotating a leaked secret, which is why step 4 is part of the procedure rather than optional cleanup.
+
+### RazorpayX payout deliveries
+
+RazorpayX payout events arrive at the same endpoint but are signed with `RAZORPAYX_WEBHOOK_SECRET`, a different value again. The route verifies against the payment-side secrets first and only consults the RazorpayX secret when that fails **and** the event name begins with `payout.`. That ordering is the safety property rather than an optimisation: because a non-payout event can never be accepted by the RazorpayX secret, holding a second secret cannot be used to smuggle a forged `payment.captured` through.
+
+---
+
+## 4. Capture and settlement (dashboard checks)
+
+- [ ] **Automatic capture is on.** Verify at Settings → Payments → payment capture. Auto-capture is on by default, but if it has been turned off, payments sit in `authorized`, `payment.captured` never fires, and no booking is ever confirmed. The `payment_capture` request field that older integrations used is deprecated and this repository correctly does not send it; per-order overrides are available through the `payment.capture` and `payment.capture_options` objects on the Orders API, and the platform deliberately does not use them so that one dashboard setting governs every order ([capture settings](https://razorpay.com/docs/payments/payments/capture-settings/)).
+- [ ] **The auto-refund window for uncaptured payments is understood.** A payment left in `authorized` past the account's `manual_expiry_period` is refunded automatically, at normal speed, so the customer sees it back in five to seven working days. Read the actual configured value off the dashboard rather than trusting a remembered default, because Razorpay's own pages have quoted three days and five days in different places.
+- [ ] **The settlement cycle is recorded.** The standard domestic cycle is T+2 working days from capture, where working days exclude Sundays, the second and fourth Saturdays, and bank holidays; T+7 is the international cycle rather than a new-merchant probation ([settlements](https://razorpay.com/docs/payments/settlements/)). The finance owner needs this number to reconcile the bank statement against the ledger.
+- [ ] **A real ₹1 payment has been taken end to end in live mode** and has produced a Payment row at SUCCEEDED, a confirmed appointment, balanced ledger entries and a consumer tax invoice.
+
+---
+
+## 5. Refunds
+
+- [ ] A live refund has been issued against that ₹1 payment and has reached SUCCEEDED via the `refund.processed` webhook rather than by anyone editing a row.
+- [ ] The team understands that live refunds settle in five to seven business days at normal speed. Test-mode refunds usually appear instantly, which is not a guarantee and must never be built into a flow; the only correct trigger for "the customer has their money" is `refund.processed`.
+- [ ] Nobody has introduced a `speed` parameter. This platform always requests the default `normal` speed and never `optimum`, so it never pays the instant-refund fee and `refund.speed_changed` is informational only. Changing that is a pricing decision, not an engineering one.
+- [ ] Refund idempotency is intact: every refund carries `X-Refund-Idempotency` set to the `Refund` row's id, which is minted before the gateway call and unchanged on the error path. A key derived from the payment id and amount would make two legitimate partial refunds of equal value collide, and the second would silently return the first refund instead of paying the customer again.
+
+---
+
+## 6. Order metadata limits
+
+Razorpay caps order `notes` at **15 key-value pairs of at most 256 characters each**, and rejects the whole order with a `BAD_REQUEST_ERROR` when either limit is exceeded ([Orders API](https://razorpay.com/docs/api/orders/create/)). The receipt field is separately capped at 40 ASCII characters and must be unique per order.
+
+- [ ] Every producer of order notes has been counted against the 15-pair budget before any new key is added. `buildPaymentMetadata` in `lib/payments/operations/checkout.ts` already emits fifteen keys in the org-sponsored case, so it has no headroom left.
+- [ ] No unbounded user-supplied string reaches `notes`. This is an open gap at the time of writing: the free-text booking note is validated as `z.string().optional()` with no maximum and is forwarded verbatim, so a note longer than 256 characters fails order creation and the customer cannot pay. It is tracked for the multi-currency and checkout PR that owns those files.
+
+---
+
+## 7. Operations and observability
+
+- [ ] Sentry is receiving events from the payments subsystem, and the webhook route's signature-failure and parse-failure paths have been seen at least once in a preview environment so the alerting is known to work.
+- [ ] The scheduled sweeps are running in production. Payment confirmation is durable because the `WebhookEvent` row is written before the 200 is returned, but recovery from a crashed handler depends on `sweep-stuck-webhook-events`, and recovery from an event that never arrived depends on `reconcile-payment-status`. Both are driven by the Netlify ticker every five minutes with GitHub Actions as a backstop; see [ADR 27](../../../enterprise/70-design-decisions/27-state-as-outbox-and-scheduled-ticker.md).
+- [ ] No secret is logged. Payloads are scrubbed by `scrubWebhookPayload` before anything is written, and no code path prints `RAZORPAY_SECRET` or either webhook secret.
+- [ ] Payment records are retained for at least eight years, as Indian tax law requires. Nothing in the money subsystem hard-deletes a Payment, Refund or invoice row, and that property must survive any future data-retention work.
+
+---
+
+## Related Documents
+
+- [01-setup.md](./01-setup.md) — Account setup, keys, dashboard configuration and test credentials
+- [02-architecture-and-flow.md](./02-architecture-and-flow.md) — Payment flow and revenue split
+- [03-payout-flow.md](./03-payout-flow.md) — RazorpayX payout system and status mapping
+- [04-kyc-and-onboarding.md](./04-kyc-and-onboarding.md) — KYC requirements and timelines
+- [docs/payments/06-high-level-design.md](../../06-high-level-design.md) — Where money truth is written and which sweep closes each gap
+- [docs/enterprise/50-operations/07-required-secrets.md](../../../enterprise/50-operations/07-required-secrets.md) — The full secrets manifest and what breaks when each one is missing
diff --git a/docs/payments/gateways/stripe/01-setup.md b/docs/payments/gateways/stripe/01-setup.md
index fc322e71c..d37331a8d 100644
--- a/docs/payments/gateways/stripe/01-setup.md
+++ b/docs/payments/gateways/stripe/01-setup.md
@@ -25,6 +25,8 @@ Stripe serves two roles in our system:
### When to Use Stripe vs Razorpay
+The table below describes what Stripe is capable of, not what this deployment does. Today Razorpay takes every payment, domestic and international, and the routing table in `lib/payments/gateway-router.ts` never selects Stripe on its own. Read the fence section immediately after this one before assuming any of these rows is live.
+
| Customer From | Gateway | Why |
| ------------- | -------- | ----------------------- |
| India | Razorpay | UPI support, lower fees |
@@ -35,6 +37,26 @@ Stripe serves two roles in our system:
---
+## Fenced by default
+
+Stripe is switched off unless a deployment deliberately turns it on. It exists in the tree as a contingency rail: Razorpay is the primary gateway and covers international collections through IBT at roughly a sixth of Stripe's cost, Dodo Payments is the sanctioned post-MVP international rail, and Stripe is what we would fall back to if RBI rules changed and Razorpay could no longer settle a class of collections. Until that happens, a customer must never be able to reach a Stripe charge, because the account runs on test keys and no Stripe payment has ever been reconciled end to end.
+
+Three environment variables control this, and all three are optional and default to unset.
+
+| Variable | Read by | Effect when unset |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `STRIPE_ENABLED` | `assertGatewayUsable` in `lib/payments/validation/gateway-guards.ts`, at call time | Any attempt to route a checkout to Stripe, or to mint a live Stripe payment intent, throws a `DisabledGatewayError`. Mock payments are the one deliberate exception, because `createPaymentIntent` returns a mock intent before it consults the guard. This is the fence that actually protects money. Set it to exactly `true` to open it. |
+| `NEXT_PUBLIC_STRIPE_ENABLED` | `paymentGateways` in `app/checkout/plans/utils.ts`, inlined into the client bundle at build time | The Stripe card on all four checkout pages renders a disabled "Coming Soon" button and no `StripeCheckout` component mounts. It keeps the UI honest; because the value ships to the browser it is not a security control on its own. |
+| `STRIPE_ALLOW_TEST_KEYS_IN_PRODUCTION` | `initializeStripeClient` in `lib/payments/core/stripe.ts`, when the client is lazily constructed | Under `NODE_ENV=production`, a test-mode secret key throws `STRIPE_TEST_KEY_IN_PRODUCTION` instead of booting, and both `sk_test_…` and the restricted `rk_test_…` count as test mode. Set it to `true` only for the pre-launch window where the production site legitimately runs on test keys, and delete it with the first live key. |
+
+Turning Stripe on therefore means setting both `STRIPE_ENABLED` and `NEXT_PUBLIC_STRIPE_ENABLED` to `true` and redeploying, since the public one is inlined at build time and a runtime change does not reach an already-built bundle.
+
+Refunds are deliberately outside the fence. `assertGatewayUsable` guards the paths that start new money movement — routing a checkout and creating a payment intent — and does not guard `createRefund`, refund lookups or dispute reads. A `Payment` row already written against Stripe has to stay refundable after the flag goes back to unset, otherwise closing the fence would strand real customer money.
+
+The guard mirrors the Razorpay one in `lib/payments/core/razorpay.ts`, with one difference worth knowing: Razorpay's test-key check runs at module load, while Stripe's runs inside the lazy client initializer, because gateway cores are loaded at call time (#1376) and a module-scope throw would fire on any import of the file. Both carry the same `next build` carve-out, so a build that legitimately holds test keys still completes.
+
+---
+
## Prerequisites
| Requirement | Details |
diff --git a/docs/payments/multi-currency/01-architecture.md b/docs/payments/multi-currency/01-architecture.md
index 1945a9650..b65672b19 100644
--- a/docs/payments/multi-currency/01-architecture.md
+++ b/docs/payments/multi-currency/01-architecture.md
@@ -1,75 +1,82 @@
# Multi-Currency Architecture
-## Strategy: India-First + Accept International
+## Strategy: India-First, Accept International, Settle in INR
-All prices are stored in **INR paise**. International buyers see approximate prices in their local currency (client-side conversion), but all charges are processed in INR via Razorpay.
+Every price in this platform is stored as an integer count of INR paise, and every charge is taken in INR. An international buyer may switch the site into a foreign currency, in which case the prices they read are estimates converted client-side from those INR paise; the order the gateway mints is still an INR order and their card issuer performs the conversion at its own rate. This is a display feature, not a pricing feature, and the rest of this document is mostly about keeping that distinction visible to the person paying.
-### Gateway Selection
+Settlement being INR-only is enforced, not merely assumed. `assertInrSettlement` in `lib/payments/validation/currency-guards.ts` runs as the first statement of both `createRazorpayOrder` and `createStripeCheckoutSession` and throws a `PaymentError` with code `NON_INR_SETTLEMENT` on anything else. The three administrative surfaces that used to accept a currency choice — organisation creation, the billing-account patch, and purchase-order creation — now validate against `z.literal("INR")`. The `Currency` enum stays on those columns, for the reasons recorded in [ADR 15](../../enterprise/70-design-decisions/15-currency-as-enum-with-display-fields.md), but no API will write a value other than INR into them.
-| Buyer Country | Gateway | Method | Fee | Settlement |
-| ------------- | -------- | --------------------------------- | ----------------------- | ---------- |
-| India | Razorpay | Domestic (UPI, cards, netbanking) | 2% + GST (~2.36%) | INR, T+2 |
-| International | Razorpay | IBT (International Bank Transfer) | 1% + GST, zero forex | INR, T+1 |
-| Fallback | Stripe | Checkout Sessions | ~6.3% (4.3% + 2% forex) | INR, T+5-7 |
+### Gateway Selection
-### Why Razorpay for Everything
+| Buyer Country | Gateway | Method | Fee | Settlement |
+| ------------- | -------- | -------------------------------------------- | ----------------------- | ---------- |
+| India | Razorpay | Domestic (UPI, cards, netbanking) | 2% + GST (~2.36%) | INR, T+2 |
+| International | Razorpay | The same INR order, paid by an overseas card | ~3% + GST | INR, T+7 |
+| Fallback | Stripe | Checkout Sessions | ~6.3% (4.3% + 2% forex) | INR, T+5-7 |
-1. **Cost**: Razorpay IBT is 1% vs Stripe's 6.3% for international — **5x cheaper**
-2. **eFIRC**: Razorpay auto-generates eFIRC (Foreign Inward Remittance Certificate) monthly — Stripe requires manual coordination with bank
-3. **PA-CB License**: Razorpay received RBI PA-CB license (Dec 2025) — authorized for cross-border
-4. **UPI**: Zero-fee domestic payments (unique advantage over TopMate which uses Stripe)
+The settlement column deserves one clarification, because an earlier revision of this table put the international row at T+1. That figure belongs to the MoneySaver Export Account, not to this flow. Razorpay settles an ordinary international card payment in INR on a [T+7 working-day cycle](https://razorpay.com/docs/payments/international-payments/faqs/), against T+2 for a domestic one, which is also what our own [gateway evaluation](../gateways/gateway-evaluation-mar-2026.md) recorded.
-### Competitive Advantage vs TopMate
+An earlier revision of this table quoted Razorpay's International Bank Transfer product at 1% with zero forex markup and automatic eFIRC. That was a description of a product this codebase has never used. IBT is the MoneySaver Export Account, a virtual-account bank-transfer rail with [no Orders API behind it](https://razorpay.com/docs/payments/international-payments/international-bank-transfer/), so no checkout could have routed through it. The international row above is what the router actually does, and it costs roughly two points more than the figure that used to appear here.
-TopMate's effective international cost: **15-18%** (10% commission + 3% Stripe + 2-3% forex)
-Familiarise's effective international cost: **~11%** (10% commission + 1% Razorpay IBT)
+### Why Razorpay for Everything
-**Structural moat**: 4-7% cost advantage per international transaction.
+Razorpay remains the primary rail for three reasons that survive the correction above. It is still materially cheaper than Stripe for international cards, at roughly 3% against Stripe's 6.3% all-in. It holds an RBI PA-CB licence granted in December 2025, which authorises it for cross-border collection. And it accepts UPI, which is the bulk of domestic volume and something a Stripe-based competitor cannot offer on this rail. That last reason should not be overstated: UPI carries zero MDR because the RBI mandates it, but Razorpay still charges its standard 2% platform fee plus GST on a UPI collection, so the method is cheap for the buyer rather than free for us.
## Currency Flow
```
[Consultant sets price in INR paise]
↓
-[Consultee sees price in local currency (client-side conversion)]
+[Consultee optionally switches display currency; prices are converted client-side for reading only]
↓
[Checkout: buyer country detected → tax determined → gateway auto-routed]
↓
-[Razorpay charges in INR (or auto-converts for IBT)]
+[Order minted in INR; assertInrSettlement refuses anything else]
↓
-[Payment recorded with buyerCountry + isInternational flags]
+[Payment recorded with buyerCountry + isInternational flags, plus the display currency and rate snapshot for audit]
↓
[Earnings created in INR → hold period → TDS calculated → payout in INR]
```
## Buyer Country Detection
-Server-side cascade at checkout:
+The server runs a two-signal cascade at checkout, with a conservative fallback:
+
+1. `User.country`, when it is a two-letter ISO code — the highest-confidence signal, because someone asserted it.
+2. The `cf-ipcountry` header, when a Cloudflare edge is in front of the deployment.
+3. Fallback to `"IN"`, which charges GST rather than risking a missed collection.
-1. `User.country` (profile field — highest confidence)
-2. `cf-ipcountry` header (Cloudflare geo-IP)
-3. `Accept-Language` → country mapping
-4. Fallback: `"IN"` (conservative — charges GST rather than missing it)
+`Accept-Language` was removed from this cascade and must not be reintroduced. It was once the third step, and in this deployment it was effectively the only step that ever fired, because `User.country` is a free-text onboarding field that cannot satisfy the two-letter check and production runs on Netlify with no Cloudflare in front of it. A browser default of `en-US`, which is common in India, therefore zero-rated domestic sales as exports. A browser locale is not evidence a tax authority recognises. The reasoning is recorded in full at `lib/payments/tax/buyer-country.ts` and pinned by `__tests__/payments/currency-and-tax-gates.test.ts`.
## Exchange Rate Handling
-- Rates from `open.er-api.com` (free, daily updates, INR base)
-- Cached for 24 hours server-side
-- Client-side: React Query with 1-hour stale time
-- Disclaimer shown: "Final amount may vary based on current exchange rate"
-- `displayCurrencyAtCheckout` stored on Payment record (currency code shown to buyer, e.g., "USD")
-- `exchangeRateAtCheckout` stored on Payment record (INR→display rate snapshot for audit)
+Rates come from ExchangeRate-API's Open Access endpoint, which supports INR as a base currency and needs no API key. The endpoint is read from `EXCHANGE_RATE_API_URL` and defaults to `https://open.er-api.com/v6/latest/INR`, so moving to a paid host or a different provider does not require a code change.
+
+Caching happens in two places, and only one of them matters. `lib/currency.ts` holds the last response in a module-level variable for one hour, which means the cache belongs to a single serverless instance: Netlify runs many instances, there is no shared store on this path, and the admin invalidation endpoint at `/api/admin/exchange-rates` can only ever flush the one instance that happens to serve the flush request. The cache that actually spares the provider is the CDN, which `/api/currency` enables with `Cache-Control: public, s-maxage=3600, stale-while-revalidate=86400`. That route is also rate-limited to thirty requests per minute per IP, because the provider answers abuse with a 429 that locks the caller out for roughly twenty minutes, and a single scripted client could otherwise take FX display down for everyone.
+
+Staleness is bounded. A response older than twenty-four hours is never served, even when the provider is failing: `getExchangeRates` throws instead, `/api/currency` answers 500, the client query exhausts its retries, and `rate` settles at `null`. That null is the important case, and it is handled deliberately rather than papered over. When there is no rate, `useCurrency` reports `currency` as INR, `symbol` as `₹`, and `isEstimate` as `false`, so the whole display degrades together and the site shows honest rupees rather than rupee amounts wearing a foreign symbol. A missing estimate is better than a stale one presented as current.
+
+## Disclosure and Attribution
+
+An earlier revision of this document claimed the app displayed "Final amount may vary based on current exchange rate". No such string existed anywhere in the codebase, on any checkout page or beside any price. What exists now is `app/checkout/components/FxEstimateNote.tsx`, rendered directly under the Total on all four checkout pages. It appears only while `isEstimate` is true — that is, only when a non-INR currency is selected and a rate is actually available — and it names the INR figure the gateway will take: "Estimated in USD. You will be charged ₹5,000.00 in INR by the payment gateway; your card issuer's rate applies."
+
+The same component carries the provider attribution, as does the navbar beside the currency switcher. ExchangeRate-API's Open Access tier [requires visible attribution](https://www.exchangerate-api.com/docs/free) wherever its rates are shown, so this is a licence term rather than a courtesy; the link text and target live in `lib/currency-codes.ts` as `RATE_PROVIDER_NAME` and `RATE_PROVIDER_URL` so that every surface that renders a converted figure uses the same one.
+
+Two fields on `Payment` record what the buyer saw. `displayCurrencyAtCheckout` holds the currency code the checkout page was rendered in, and it is now validated against the shared allowlist in `lib/currency-codes.ts` rather than accepted as any three-letter string; the value originates in `localStorage` and `Intl.NumberFormat` will happily render an invented code, so an unvalidated field meant arbitrary text persisting onto a money row. `exchangeRateAtCheckout` holds the INR-to-display rate at the moment of the order. Both are audit-only. No stored amount is ever derived from either.
## Key Files
-| File | Purpose |
-| -------------------------------------------- | ---------------------------------------- |
-| `lib/payments/tax/buyer-country.ts` | Buyer country detection cascade |
-| `lib/payments/tax/tax-engine.ts` | Tax determination (GST vs zero-rated) |
-| `lib/payments/gateway-router.ts` | Auto-routing to Razorpay/Stripe |
-| `lib/payments/validation/currency-guards.ts` | Currency consistency validation |
-| `lib/currency.ts` | Exchange rates + locale→currency mapping |
-| `hooks/useCurrency.ts` | Client-side currency display hook |
+| File | Purpose |
+| -------------------------------------------- | -------------------------------------------------------------------- |
+| `lib/payments/tax/buyer-country.ts` | Buyer country detection cascade |
+| `lib/payments/tax/tax-engine.ts` | Tax determination (GST vs zero-rated) |
+| `lib/payments/gateway-router.ts` | Auto-routing to Razorpay/Stripe |
+| `lib/payments/validation/currency-guards.ts` | `toCurrencyEnum`, `validatePlanCurrency`, `assertInrSettlement` |
+| `lib/currency.ts` | Server-side rate fetch, per-instance cache, staleness bound |
+| `lib/currency-codes.ts` | Shared display-currency allowlist and provider attribution strings |
+| `hooks/useCurrency.ts` | Client-side display hook, including `isEstimate` and the INR degrade |
+| `app/api/currency/route.ts` | Public rate endpoint, CDN-cached and IP rate-limited |
+| `app/checkout/components/FxEstimateNote.tsx` | The checkout disclosure and its attribution |
## Future Phases
diff --git a/docs/payments/payouts/03-payout-processing.md b/docs/payments/payouts/03-payout-processing.md
index 540890f6d..5aeef8b54 100644
--- a/docs/payments/payouts/03-payout-processing.md
+++ b/docs/payments/payouts/03-payout-processing.md
@@ -374,6 +374,8 @@ flowchart TD
4. **Next batch** → Earnings included again
5. **New payout created** → Fresh retry
+The stuck-payout handler re-arms a payout for retry through a compare-and-set, not a bare update (#1407). `scripts/payouts/handle-stuck-payouts.ts` reads its cohort of `PROCESSING` payouts once and then spends a gateway HTTP round-trip on each one in turn, which leaves a wide window in which a concurrent `process-payouts` run or an inbound payout webhook can move a row that the handler has already read. The reset to `APPROVED` therefore carries the state it expects to find in its `WHERE` clause — `status = PROCESSING` and `providerPayoutId IS NULL` — so a row that something else has advanced in the meantime is no longer matched. When the update affects zero rows the handler counts the payout as skipped and logs that it raced; it neither throws nor retries, because whichever writer moved the row now owns it. Without that guard the handler would stamp a payout back to `APPROVED` after a webhook had already completed it, and the next weekly batch would disburse the same money a second time.
+
---
## Payout Database Schema
diff --git a/docs/payments/webhooks/01-monitoring.md b/docs/payments/webhooks/01-monitoring.md
index 02d62609e..4bf86f281 100644
--- a/docs/payments/webhooks/01-monitoring.md
+++ b/docs/payments/webhooks/01-monitoring.md
@@ -246,6 +246,14 @@ SKIP_PAYMENT=true # Remove for production
- ✅ Track booking status updates
- ✅ Review logs regularly
+### Method 5: The deferral warning
+
+A Razorpay webhook can be valid and still be unprocessable on arrival, most commonly a `refund.created` that overtakes the `payment.captured` which would have created the Payment row. The handler answers those with a `DeferSignal`, the dispatcher deliberately leaves the row `processed=false, error=null`, and `sweep-stuck-webhook-events` re-drives it until the awaited row lands or the seven-day give-up cap fires.
+
+The problem with that design was that a deferred row is indistinguishable from a row whose handler crashed before recording anything, so an event that would never become processable stayed silent for a week. The dispatcher now increments `WebhookEvent.deferCount` every time it defers, and the sweeper raises a single Sentry warning per run listing every event that has deferred five or more times or has been unprocessed for over an hour. If you see `sweep-stuck-webhook-events: N webhook event(s) still unprocessed` in Sentry, the attached context names each event id, its provider, its type and its defer count.
+
+A high `deferCount` on a refund means the handler could not resolve the payment the refund names, and there are two quite different reasons for that. Check the local capture state first: look the `pay_…` id up against `Payment.gatewayPaymentId` and the order id against `Payment.paymentIntent`, and if neither finds a row then the payment really was never captured on our side and the event is a reconciliation question rather than a webhook one. If a row does exist, the failure is in the lookup rather than in the data, which on a pre-`gatewayPaymentId` row means the dispatcher's `payments.fetch` translation is failing — check the Razorpay credentials the function is running with and the gateway's availability, because an authentication or network failure there produces exactly the same silent, repeating deferral as a genuinely missing capture.
+
## Success Indicators
### Your webhooks are working correctly if:
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 6e24f080d..f23dd2a05 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -39,9 +39,12 @@ export default [
},
},
- // Base config for all JavaScript/TypeScript files
+ // Base config for all JavaScript/TypeScript files. `mts`/`cts` included so
+ // netlify/functions/*.mts (#1356 — the scheduled ticker) is linted rather
+ // than silently skipped; it was previously the only extension this repo
+ // ships that fell through every `files` glob below.
{
- files: ["**/*.{js,mjs,cjs,ts,jsx,tsx}"],
+ files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"],
languageOptions: {
globals: {
...globals.browser,
diff --git a/hooks/useCurrency.ts b/hooks/useCurrency.ts
index 1c6c7b7c3..8d0798b41 100644
--- a/hooks/useCurrency.ts
+++ b/hooks/useCurrency.ts
@@ -4,24 +4,20 @@ import { useQuery, useQueryClient } from "@tanstack/react-query";
import { useCallback, useSyncExternalStore } from "react";
import { reportSentryError } from "@/lib/observability/report";
import { CURRENCY_LOCALE_MAP } from "@/utils/formatting";
+import {
+ SUPPORTED_CURRENCIES,
+ type SupportedCurrency,
+} from "@/lib/currency-codes";
const STORAGE_KEY = "preferred-currency";
const DEFAULT_CURRENCY = "INR";
-// Currencies offered in the navbar dropdown (keep this list lean)
-export const SUPPORTED_CURRENCIES = [
- { code: "INR", symbol: "\u20B9", label: "INR (\u20B9)" },
- { code: "USD", symbol: "$", label: "USD ($)" },
- { code: "EUR", symbol: "\u20AC", label: "EUR (\u20AC)" },
- { code: "GBP", symbol: "\u00A3", label: "GBP (\u00A3)" },
- { code: "AUD", symbol: "A$", label: "AUD (A$)" },
- { code: "CAD", symbol: "C$", label: "CAD (C$)" },
- { code: "SGD", symbol: "S$", label: "SGD (S$)" },
- { code: "AED", symbol: "AED", label: "AED" },
- { code: "JPY", symbol: "\u00A5", label: "JPY (\u00A5)" },
-] as const;
-
-export type SupportedCurrency = (typeof SUPPORTED_CURRENCIES)[number]["code"];
+// #1396 — the list itself moved to lib/currency-codes.ts so schemas/checkout.ts
+// can allowlist `displayCurrency` against the same codes without importing a
+// React module. Re-exported here because every existing consumer imports it
+// from the hook.
+export { SUPPORTED_CURRENCIES };
+export type { SupportedCurrency };
// ---------- shared external store (cross-component reactivity) ----------
@@ -94,12 +90,6 @@ export function useCurrency() {
retry: 2,
});
- const currency = isINR ? "INR" : (data?.currency ?? selectedCurrency);
- const symbol = isINR
- ? "\u20B9"
- : (data?.symbol ??
- SUPPORTED_CURRENCIES.find((c) => c.code === selectedCurrency)?.symbol ??
- selectedCurrency);
// No rate yet (still loading, or the provider failed after retries). Falling
// back to 1 meant multiplying by nothing and then stamping a foreign symbol
// on the result: a ₹5,000 session rendered as "$5,000" — about 83x its real
@@ -108,6 +98,24 @@ export function useCurrency() {
// instead, which is honest at any moment rather than wrong for a while.
const rate: number | null = isINR ? 1 : (data?.rate ?? null);
+ // #1396 — `currency` and `symbol` used to keep naming the selected currency
+ // even while `rate` was null and formatPrice was already rendering rupees, so
+ // the navbar advertised "$ USD" over prices denominated in INR. The whole
+ // triple degrades together now: no rate means no foreign labelling anywhere.
+ const degradedToINR = isINR || rate === null;
+ const currency = degradedToINR ? "INR" : (data?.currency ?? selectedCurrency);
+ const symbol = degradedToINR
+ ? "\u20B9"
+ : (data?.symbol ??
+ SUPPORTED_CURRENCIES.find((c) => c.code === selectedCurrency)?.symbol ??
+ selectedCurrency);
+
+ // True exactly when the figures on screen are a converted estimate rather
+ // than the amount the gateway will charge. Checkout uses it to say so; the
+ // navbar uses it to attribute the rate provider. It is deliberately false
+ // during the degrade, because rupees shown as rupees are not an estimate.
+ const isEstimate = !isINR && rate !== null;
+
const convert = useCallback(
(amountINR: number): number => {
if (isINR || rate === null) return amountINR;
@@ -121,9 +129,9 @@ export function useCurrency() {
// Convert from paise (smallest unit) to major unit for display
const amountInMajor = amountInPaise / 100;
const converted = convert(amountInMajor);
- // Until a rate arrives, render the amount in the currency it is actually
- // denominated in rather than relabelling it.
- const displayCurrency = rate === null ? "INR" : currency;
+ // `currency` is already "INR" whenever `rate` is null, so the amount is
+ // rendered in the currency it is actually denominated in.
+ const displayCurrency = currency;
// Use currency-appropriate locale for correct grouping (e.g. ₹1,00,000 vs $100,000)
const locale =
CURRENCY_LOCALE_MAP[displayCurrency.toUpperCase()] ||
@@ -136,16 +144,19 @@ export function useCurrency() {
maximumFractionDigits: 0,
}).format(converted);
} catch (error) {
- // Only throws on a malformed currency code (e.g. a bad value from
- // /api/currency) \u2014 a real data bug, not the "still loading" case.
+ // Intl accepts any well-formed three-letter code, so a merely unknown
+ // currency renders rather than throws \u2014 reaching here means the code is
+ // structurally malformed, which only happens when a tampered
+ // localStorage value is echoed back by /api/currency. Report it; the
+ // fallback below still renders an honest number.
reportSentryError(error, {
subsystem: "client",
extra: { displayCurrency },
});
- return `${rate === null ? "\u20B9" : symbol}${Math.round(converted).toLocaleString()}`;
+ return `${symbol}${Math.round(converted).toLocaleString()}`;
}
},
- [convert, currency, symbol, rate],
+ [convert, currency, symbol],
);
const setCurrency = useCallback(
@@ -161,6 +172,7 @@ export function useCurrency() {
currency,
symbol,
rate,
+ isEstimate,
convert,
formatPrice,
setCurrency,
diff --git a/hooks/useHoldCountdown.ts b/hooks/useHoldCountdown.ts
new file mode 100644
index 000000000..87044e7d7
--- /dev/null
+++ b/hooks/useHoldCountdown.ts
@@ -0,0 +1,40 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+export interface HoldCountdown {
+ /** Whole minutes remaining, floored; 0 once inside the final minute. */
+ minutesLeft: number;
+ /** True once `now` has passed `deadline`. */
+ isExpired: boolean;
+}
+
+/**
+ * Live minutes-remaining countdown against a tentative-hold deadline
+ * (Payment.expiresAt). Shared by SessionTimeline's held row and any other
+ * surface that needs to say "this reservation releases at