Payments, Invoicing & EMD

Relevant source files

The following files were used as context for generating this wiki page:

• src/pages/UniversalPayments.tsx
• src/pages/VendorPayments.tsx
• src/hooks/useVendorReportsData.ts
• src/components/PaymentSystemVerification.tsx
• src/utils/pdfGenerator.tsx
• src/integrations/supabase/types.ts
• src/lib/validation/adminSchemas.ts

The Payments, Invoicing, and Earnest Money Deposit (EMD) systems comprise the financial core of the platform. This module handles the complete lifecycle of financial transactions between property managers, vendors, and tenants, including invoice generation from project milestones, secure payment processing via Stripe, and the management of refundable or forfeitable EMDs during the bidding process.

Sources: src/pages/VendorPayments.tsx:43-65, src/integrations/supabase/types.ts:474-515, src/pages/UniversalPayments.tsx:1-15

Financial Architecture & Data Models

The system architecture relies on a centralized PostgreSQL schema managed via Supabase, with specialized tables for different transaction types. The primary entities include invoices, vendor_payments, vendor_payouts, and emd_transactions.

Core Entity Relationship

The following diagram illustrates the relationship between projects, milestones, and the resulting financial documents.

Database Schema Definitions

Table	Purpose	Key Fields
invoices	Represents a request for payment for services rendered.	invoice_number, amount, status, milestone_id, project_id
vendor_payments	Internal record of payments owed by or to a vendor (e.g., background checks, fees).	payment_type, amount, status, stripe_payment_intent_id
vendor_payouts	Funds being transferred from the platform to a vendor's bank account.	amount, status, vendor_acknowledged, payout_method
emd_transactions	Earnest Money Deposits held during the RFQ process.	amount_cents, status, rfq_id, released_at, forfeited_at

Sources: src/integrations/supabase/types.ts:601-645, src/integrations/supabase/types.ts:474-515, src/integrations/supabase/types.ts:1335-1395

Invoicing Workflow

The invoicing system is primarily event-driven, where the completion of a project_milestone serves as the trigger for generating a VendorInvoice.

Invoice Generation Logic

1. Milestone Completion: When a vendor completes a project milestone, the system identifies the associated milestone_id.
2. Data Extraction: The system pulls the amount and description from the milestone record.
3. Invoice Creation: A new record is inserted into the invoices table with a 'draft' or 'sent' status.
4. PDF Generation: A secure PDF is generated using @react-pdf/renderer to avoid common vulnerabilities associated with older libraries like jspdf.

Sources: src/components/PaymentSystemVerification.tsx:40-54, src/utils/pdfGenerator.tsx:160-185, src/integrations/supabase/types.ts:601-615

Secure PDF Generation

The pdfGenerator.tsx utility provides a secure way to generate invoices. It includes a sanitizeText function to strip control characters and prevent injection attacks within the document metadata.

function sanitizeText(text: string | undefined | null, maxLength: number = 500): string {
  if (!text) return '';
  return String(text)
    .replace(/[\x00-\x1f\x7f]/g, '')
    .slice(0, maxLength);
}

Sources: src/utils/pdfGenerator.tsx:88-95

Payment Processing & Stripe Integration

Payment processing is handled via Stripe Integration through Supabase Edge Functions. The system supports various payment types including background checks, subscription fees, and project-based payments.

Payment Sequence Flow

Validation Schemas

All financial inputs are strictly validated using Zod schemas before being processed by the backend.

• Amount Constraints: Payments must be between $0.01 and $1,000,000.
• Method Enum: Supports check, ach, wire, credit_card, and cash.
• Status Enum: Restricted to pending, completed, failed, and cancelled.

Sources: src/lib/validation/adminSchemas.ts:10-25

Earnest Money Deposits (EMD)

EMD transactions are specific to the Request for Quote (RFQ) process. Vendors may be required to deposit funds to ensure bid seriousness.

EMD States

EMD funds exist in one of several states defined in the emd_transactions table:

• Pending: Initial request for deposit.
• Paid: Funds successfully captured via Stripe.
• Released: Funds returned to the vendor after the bidding process.
• Forfeited: Funds captured by the property manager due to vendor breach of terms.

Sources: src/integrations/supabase/types.ts:474-515, src/integrations/supabase/types.ts:1825-1865

Financial Reporting & Performance Metrics

The useVendorReportsData hook aggregates financial data to provide vendors with insights into their business performance.

Key Performance Indicators (KPIs)

• On-Time Rate: Calculated by comparing completion_date against due_date for milestones.
• Win Rate: The ratio of awarded bids to total bids submitted.
• Monthly Financials: Aggregated totals for invoiced, paid, and pending amounts.

Sources: src/hooks/useVendorReportsData.ts:50-75, src/hooks/useVendorReportsData.ts:105-130

Monthly Financial Aggregation Logic

The system filters invoices and payouts by the current month and year to generate chart data for the vendor dashboard.

const monthlyInvoices = invoices.filter(inv => {
  const invDate = new Date(inv.created_at);
  return invDate.getMonth() === currentMonth && invDate.getFullYear() === currentYear;
});
const invoicedTotal = monthlyInvoices.reduce((sum, i) => sum + Number(i.amount || 0), 0);

Sources: src/hooks/useVendorReportsData.ts:145-160

Conclusion

The Payments, Invoicing, and EMD module provides a robust, secure framework for all financial interactions within the Monarch platform. By integrating Stripe for transactions, utilizing secure PDF generation, and implementing strict Zod-based validation, the system ensures data integrity and financial transparency for all users. The addition of EMD management specifically caters to the needs of professional property management bidding workflows.

Sources: README.md:12-25, src/pages/VendorPayments.tsx:120-135