The dues ledger helps boards track HOA dues before online payments are enabled.
This first version is for manual tracking. It does not move money through Stripe yet.
Create a dues campaign
Board admins can create a dues campaign from Billing.
Each campaign includes:
- A title
- Amount per member
- Due date
- Optional grace period
- Description
- Payment instructions
When the campaign is created, HoatzinHome assigns a charge to each current member in the organization.
Add payment instructions
Because online payment collection is not enabled yet, board admins can add payment instructions to each dues campaign.
Examples:
- Where to mail checks
- Who checks should be payable to
- Whether members should include their property address in the memo
- External bank portal or ACH instructions
- Who to contact with payment questions
Admins can edit these instructions from the campaign card on Billing.
Export treasurer reports
Board admins can export CSV reports from Billing for offline review or bookkeeping.
Available exports include:
- Campaign summary
- Member balances
- Payment history
- Checkout attempts
- Open balances
These reports are designed for board treasurers and bookkeepers who need a snapshot outside HoatzinHome.
Record manual payments
Board admins can record payments received outside HoatzinHome, such as:
- Check
- Cash
- External ACH
- Card payment recorded elsewhere
- Other manual payment
Recording a payment lowers the member's balance and updates the dues status.
Each recorded payment creates a receipt in the member's payment history. Receipts show:
- Receipt number
- Payment date
- Amount
- Payment method
- Payment source
- Processing fee and net amount, when available
- Balance after payment
Manual receipts are ledger records. They confirm that the board recorded a payment in HoatzinHome, not that HoatzinHome processed money online.
Member view
Members can open Billing to see dues assigned to them, including the amount due, due date, status, payment history, and printable receipts.
If a balance is still open, members will see that online payment collection is not enabled yet. This prevents confusion while the board is still using the manual dues ledger.
If payment instructions have been added, members will also see a How to pay section on their open dues card.
Payment-ready fields
HoatzinHome now tracks the fields needed for future online payment collection, including payment source, processing fees, net amount, Stripe payment identifiers, and failure reason.
Online payment collection will come later, after the dues ledger and receipt history are working correctly.
Online payment settings foundation
Board admins can also save payment settings that will be used when online collection is enabled later.
Current settings include:
- Processing fee policy
- Statement descriptor
- Payment support email
- Stripe Connect status
- Card and ACH readiness states
Stripe Connect, card payments, and ACH payments remain disabled in this version. These settings prepare the account for a future online payment workflow without showing members a pay button or moving money through HoatzinHome.
Stripe Connect onboarding
Board admins can start Stripe-hosted onboarding from Billing. This creates or reuses the HOA's connected Stripe account and sends the admin to Stripe to provide business, representative, and payout information.
After the admin returns to HoatzinHome, the billing page syncs the account status, including:
- Connect status
- Whether charges are ready
- Whether payouts are ready
- Requirements still due in Stripe
- Last synced date
Even if Stripe reports the account as connected, member online payments remain disabled until checkout sessions, webhook handling, payment failure states, and receipt flows are fully enabled.
Checkout guardrails
HoatzinHome now includes the safety foundation for future card checkout.
Before a member pay button can appear, the system checks that:
- The charge belongs to the signed-in member
- The charge has an open balance
- The dues campaign is published
- Stripe Connect is enabled for the HOA
- Card payments and payouts are ready
- The HOA has selected a processing fee policy
- Webhook idempotency is in place
Stripe webhook events are recorded by event ID so retries do not accidentally process the same event twice.
Card checkout
When the HOA's Stripe Connect account is ready, board admins can enable member card checkout from Billing.
The first online payment version supports:
- Card payments only
- One open Checkout Session per dues charge
- Stripe-hosted Checkout
- Ledger updates after Stripe confirms payment
- Online payment receipts in the member payment history
This first card checkout slice supports the HOA absorbs fees policy. ACH and homeowner-paid processing fees remain future work.
Failed, expired, or canceled online payments
If an online card payment is not completed, the member's dues balance stays unchanged.
HoatzinHome tracks each Stripe Checkout attempt separately from the final payment receipt. This helps the board see whether a member started checkout, canceled it, let the link expire, or had a failed card payment.
Members may see one of these states:
- Open - a secure Stripe Checkout session is still available
- Expired - the checkout link timed out before payment was completed
- Failed - Stripe reported that the card payment did not go through
- Canceled - the member returned from Stripe Checkout without completing payment
When the balance is still open and card payments are enabled, the member can safely try again. HoatzinHome reuses a still-open checkout session when possible and creates a new one after the previous attempt expires or fails.
Board admins can review these attempts from a member's payment history and export them from Treasurer exports > Checkout attempts for support or audit review.
Charges with a failed, expired, or canceled latest checkout attempt are marked Needs attention in the admin dues table while the balance remains open. This is a follow-up cue, not a penalty or new charge. The board can ask the member to try again, record an outside payment, or leave the balance open.