[finance][P1 HIGH] Credit-funded B2C bookings break the sum(legs) === Payment.amount money invariant

[teetangh]

Summary

For a B2C checkout funded partly (or fully) by referral credit, the recorded payment legs violate the invariant that the legs sum to the Payment.amount. The CARD leg is stored post-credit, and the REFERRAL_CREDIT leg is recorded positive, so sum(legs) !== Payment.amount. This breaks downstream money reconciliation, refund math, and any auditor that sums legs.

Where it lives

• lib/payments/operations/checkout.ts:3346-3399 — leg construction for the credit + card split; the CARD leg is post-credit.
• lib/payments/operations/checkout.ts:2953 — the amount/legs assembly point.

Concretely: for an invoice of ₹X paid as (Credit=C, Card=X−C), the CARD leg is ~X−C (post-credit) while the REFERRAL_CREDIT leg is +C (positive), so the two legs sum to X (not a mismatch in magnitude) — but the semantics are inverted: a credit-leg that is positive rather than a negative offset, with the card leg already reduced, means a naive sum(legs) === amount check or a refund that re-adds credit can double-count. The invariant is documented as sum(legs) === Payment.amount and the current encoding makes it unverifiable/unstable.

Why it is real

Money-integrity: refund-on-cancellation and the ledger post either over- or under-attribute the credit, and SonarQube/static checks cannot validate the invariant because the encoding is internally inconsistent.

Suggested fix direction

• Decide the canonical encoding (recommend: CARD leg = full pre-credit amount, REFERRAL_CREDIT leg = negative offset, so CARD + CREDIT = amount), and make checkout emit it.
• Add a unit test asserting sum(legs) === Payment.amount for credit-funded, fully-credit, and cash bookings.
• Check the refund/reversal engine (refund.ts, reversal-engine.ts) against the chosen encoding.

Terms

payments · credit · referral · checkout · ledger · money invariant · refund

[teetangh]

Verified on the live database 2026-09-04 (pg_proc.prosrc): the installed assert_payment_legs_on_leg_write references NEW.paymentId / OLD.paymentId unquoted, which PL/pgSQL case-folds to paymentid, so the constraint trigger raises record "new" has no field "paymentid" on EVERY PaymentLeg insert, update or delete — not only credit-funded ones. Consistent with the data: the last successful leg write is 2026-07-28 and the six Payments created since August carry no legs. So the failure this issue describes is real but broader than filed: since the trigger was applied, any checkout that writes a leg cannot commit, and the credit-specific mismatch would have been the next failure once the identifier bug was fixed. PR #1385 fixes both (quoted identifiers + the REFERRAL_CREDIT exclusion + the LICENSE zero-leg carve the SQL was also missing), verified against a throwaway local Postgres 16 with 15 leg shapes. Deploy note: prisma db push does not manage triggers; npm run db:leg-triggers must run after merge, and until it does the live trigger keeps rejecting leg writes.

[teetangh]

Update: open PR #1385 (fix/finance-money-invariants) addresses this by REDEFINING the identity — the funding invariant becomes Σ(non-reversal, non-REFERRAL_CREDIT legs) === Payment.amount, filtering REFERRAL_CREDIT out of the funding sum (lib/payments/payment-legs.ts + prisma/sql/payment-legs-triggers.sql). \n\n- If #1385 merges as designed, this issue is resolved by decision (the contract narrows rather than the encoding changing). \n- If the team prefers the original encoding (CARD leg = full pre-credit, CREDIT = negative offset) the issue stays open. \n\nReconcile when #1385 lands.