Skip to content

Functional Specification: HOA Direct Payment Portal

Document Status: DRAFT
Date: January 2, 2026
Target: Public Website (apps/web)

1. Executive Summary

We are implementing a specialized HOA Dues Payment Page on the public website. This page solves the "International Payer Friction" problem by intelligently routing users to the optimally cost-effective payment rail based on their geographic origin (Mexico vs. International), while ensuring the Administrator receives an automated, reconciliation-ready Payment Notice.

This is NOT a payment processor integration (Stripe/PayPal). It is a "Payment Rails Guide & Notice System".

2. User Journey

  1. Selection: User lands on /pay-dues. Selects origin: "🇺🇸 United States", "🇨🇦 Canada", "🇲🇽 Mexico", etc.
  2. Recommendation:
    • If Mexico: Shows domestic SPEI instructions (CLABE).
    • If International: Shows Wise-to-CLABE instructions (The "Golden Path" for low fees).
    • Fallback: Standard SWIFT wire details (hidden behind a "Show Wire Details" toggle, with a high-fee warning).
  3. Instruction: Displays the exact Reference Code format required (e.g., UNIT-MONTH-YEAR).
  4. Submission: User performs the transfer on their own banking app, then fills out the Payment Notice Form on our page.
  5. Confirmation: System emails the Admin (Reconciliation Team) and the User (Proof of Dispatch).
Origin Recommended Rail Why?
Mexico SPEI (Domestic) Instant, free, standard.
USA/CAD/EUR Wise -> CLABE Lowest fees (<1%), faster than SWIFT, better exchange rates.
Other Wise -> CLABE Default recommendation.
Fallback SWIFT Wire Available but discouraged due to intermediary bank fees ($25-$50) and bad FX rates.

4. Content Requirements

A. The "Golden" Recipient Data

Must be copy-friendly. * Bank: Banco Inbursa * Beneficiary: [Official Legal Name] * CLABE: [18-digit-code] * Currency: MXN (Pesos)

B. Intelligent Troubleshooting Area

  • "Wise asks for an email?" -> Provide safe admin email.
  • "Wise asks for a RFC?" -> Provide generic code XAXX010101000 (Foreign Generic) or specific RFC.
  • "Payment limit?" -> Advise on daily caps.

5. The "Payment Notice" Form

This form submits to the Universal Dispatcher API.

Fields: 1. Payer Name: Text (Required) 2. Unit Number: Dropdown/Text (Required) 3. Amount Sent: Number (Required) 4. Currency: Dropdown (USD/MXN/CAD/EUR) 5. Origin Country: Dropdown 6. Transfer Date: Date Picker 7. Proof of Payment: File Upload (Optional, image/pdf) 8. Status: "I have already sent the funds" (Checkbox confirmation).

6. Implementation Architecture

6.1 Frontend (apps/web)

  • Page: app/pay-dues/page.tsx
  • Components:
    • PaymentMethodSelector (Country Flags)
    • BankDetailsCard (Copy-to-clipboard functionality)
    • PaymentNoticeForm (React Hook Form + Zod)
    • WiseGuide (Step-by-step accordions)

6.2 Backend (apps/platform)

  • Server Action: submitPaymentNoticeAction(data)
  • Email Template: AdminPaymentNoticeEmail
    • Subject: 💸 Payment Notice: Unit [UNIT] - [AMOUNT] [CURRENCY]
    • Body: Structured table of details + attachment link.

7. Non-Functional Requirements

  • No PII Leakage: Admin email/phone is NOT displayed in plain text if possible; use a form to contact.
  • Mobile Optimised: Most users check banking details on their phone while at the bank.
  • Internationalization: Page must be available in English and Spanish.

8. Open Questions for Admin (Inputs)

  1. Exact CLABE and Beneficiary Name.
  2. RFC for the Association (required for some formal invoices).
  3. Admin Email destination for notices.