Build the backend behind rent collection for a property management or proptech product: recurring lease charges, grace periods and late fees, ACH payments that settle days later, allocation to open charges, returned payments, and a tenant ledger that always balances.

Rent collection looks like a recurring payment until you build it. Rent is due on the first, but late fees only start after a grace period that differs by lease and jurisdiction. Most tenants pay by ACH, which can take days to confirm and can come back as returned weeks later. A partial payment has to land on the oldest charge first. Property owners want their payout as soon as possible, and the manager has to show any tenant a ledger that matches their bank statement to the cent.
This guide builds the backend for that: lease charges, late fees, payments with delayed confirmation, allocation, reversals and a tenant ledger.
Idempotent charge posting. A daily job that posts rent must be safe to run twice. A unique key on (lease_id, kind, period) turns a rerun into a no-op, and running the job daily, not monthly, handles leases due on different days of the month and catches up after an outage.
Late fees are data, not code paths. Many US states and cities cap late fees or require a minimum grace period, so the lease stores grace_days and the fee rule your counsel approved, and the job reads them. The fee itself is a charge with its own unique key, so it is applied once per late charge.
Payments settle later. With Stripe, ACH Direct Debit can take up to four business days to report success or failure, and a consumer can dispute a debit for up to 60 calendar days. A payment row starts pending, becomes succeeded only on a signed webhook, and allocation happens at that point. A later return or dispute posts a reversal entry, reopens the charges and can add a returned-payment fee where the lease allows it.
Ledger first. Every financial event writes an entry: charges positive, payments negative, reversals the opposite of what they reverse. The tenant balance is SUM(amount_cents), and every number a manager sees can be traced to entries. The Nacha operating rules govern ACH authorizations and returns, so store the tenant's authorization with the payment method.
Encore is a backend framework with built-in infrastructure. You declare the database, the cron jobs, the Pub/Sub topic for payment events and the provider secrets in Go, and Encore provisions them in your own AWS or GCP account. Tenant bank details stay with the payment provider; your account holds leases, the ledger and provider IDs.
-- rent/migrations/1_init.up.sql
CREATE TABLE leases (
id BIGSERIAL PRIMARY KEY,
unit_id TEXT NOT NULL,
tenant_id TEXT NOT NULL,
rent_cents BIGINT NOT NULL,
due_day INT NOT NULL CHECK (due_day BETWEEN 1 AND 28),
grace_days INT NOT NULL DEFAULT 5,
late_fee_cents BIGINT NOT NULL DEFAULT 0,
starts_on DATE NOT NULL,
ends_on DATE
);
CREATE TABLE charges (
id BIGSERIAL PRIMARY KEY,
lease_id BIGINT NOT NULL REFERENCES leases(id),
kind TEXT NOT NULL, -- rent, late_fee, returned_payment_fee
period TEXT NOT NULL, -- '2026-12', or the charge id a fee belongs to
amount_cents BIGINT NOT NULL,
due_on DATE NOT NULL,
paid_cents BIGINT NOT NULL DEFAULT 0,
UNIQUE (lease_id, kind, period)
);
CREATE INDEX charges_open_idx ON charges (lease_id, due_on) WHERE paid_cents < amount_cents;
CREATE TABLE payments (
id BIGSERIAL PRIMARY KEY,
lease_id BIGINT NOT NULL REFERENCES leases(id),
provider_id TEXT NOT NULL UNIQUE,
amount_cents BIGINT NOT NULL,
status TEXT NOT NULL DEFAULT 'pending' -- pending, succeeded, failed, reversed
);
CREATE TABLE allocations (
payment_id BIGINT NOT NULL REFERENCES payments(id),
charge_id BIGINT NOT NULL REFERENCES charges(id),
amount_cents BIGINT NOT NULL,
PRIMARY KEY (payment_id, charge_id)
);
CREATE TABLE ledger_entries (
id BIGSERIAL PRIMARY KEY,
lease_id BIGINT NOT NULL REFERENCES leases(id),
kind TEXT NOT NULL, -- charge, payment, reversal
ref_id BIGINT NOT NULL,
amount_cents BIGINT NOT NULL,
posted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
UNIQUE (kind, ref_id)
);
Capping due_day at 28 avoids the "rent due on the 31st in February" problem; leases that say "last day of the month" need an explicit rule.
Both jobs are single SQL statements, so they are atomic and safe to rerun. Each inserts charges and their ledger entries together.
package rent
import (
"context"
"encore.dev/cron"
"encore.dev/storage/sqldb"
)
var db = sqldb.NewDatabase("rent", sqldb.DatabaseConfig{Migrations: "./migrations"})
var _ = cron.NewJob("post-charges", cron.JobConfig{
Title: "Post rent charges and late fees",
Schedule: "0 6 * * *", // 06:00 UTC daily
Endpoint: PostCharges,
})
//encore:api private
func PostCharges(ctx context.Context) error {
// Rent: one charge per due period through today, so a missed run still catches up.
if _, err := db.Exec(ctx, `
WITH months AS (
SELECT l.id, l.rent_cents, l.due_day, l.starts_on, l.ends_on,
gs::date AS month_start
FROM leases l
CROSS JOIN LATERAL generate_series(
date_trunc('month', l.starts_on)::date,
date_trunc('month', current_date)::date,
interval '1 month'
) AS gs
WHERE l.starts_on <= current_date
),
new_charges AS (
INSERT INTO charges (lease_id, kind, period, amount_cents, due_on)
SELECT id, 'rent', to_char(month_start, 'YYYY-MM'), rent_cents,
month_start + (due_day - 1)
FROM months
WHERE month_start + (due_day - 1) <= current_date
AND month_start + (due_day - 1) >= starts_on
AND (ends_on IS NULL OR month_start + (due_day - 1) <= ends_on)
ON CONFLICT (lease_id, kind, period) DO NOTHING
RETURNING id, lease_id, amount_cents
)
INSERT INTO ledger_entries (lease_id, kind, ref_id, amount_cents)
SELECT lease_id, 'charge', id, amount_cents FROM new_charges`); err != nil {
return err
}
// Late fees: once per unpaid rent charge past its grace period.
_, err := db.Exec(ctx, `
WITH new_fees AS (
INSERT INTO charges (lease_id, kind, period, amount_cents, due_on)
SELECT c.lease_id, 'late_fee', c.id::text, l.late_fee_cents, current_date
FROM charges c JOIN leases l ON l.id = c.lease_id
WHERE c.kind = 'rent'
AND c.paid_cents < c.amount_cents
AND c.due_on + l.grace_days < current_date
AND l.late_fee_cents > 0
AND NOT EXISTS (
SELECT 1 FROM payments p
WHERE p.lease_id = c.lease_id AND p.status = 'pending')
ON CONFLICT (lease_id, kind, period) DO NOTHING
RETURNING id, lease_id, amount_cents
)
INSERT INTO ledger_entries (lease_id, kind, ref_id, amount_cents)
SELECT lease_id, 'charge', id, amount_cents FROM new_fees`)
return err
}
The NOT EXISTS clause skips the fee while an ACH payment is still pending, so a tenant who paid on time is not charged a late fee because the bank took three days. Whether a pending payment protects the tenant is a policy choice; put it in the lease rules if it varies.
A webhook endpoint verifies the provider's signature and publishes a PaymentEvent. A subscriber allocates or reverses inside one transaction, guarded by the payment status so redelivery does nothing.
package rent
import (
"context"
"errors"
"encore.dev/pubsub"
"encore.dev/storage/sqldb"
)
type PaymentEvent struct {
ProviderID string `json:"provider_id"`
Outcome string `json:"outcome"` // "succeeded", "failed" or "reversed"
}
var PaymentEvents = pubsub.NewTopic[*PaymentEvent]("rent-payment-events", pubsub.TopicConfig{
DeliveryGuarantee: pubsub.AtLeastOnce,
})
var _ = pubsub.NewSubscription(PaymentEvents, "apply-payment", pubsub.SubscriptionConfig[*PaymentEvent]{
Handler: applyPayment,
})
func applyPayment(ctx context.Context, e *PaymentEvent) error {
tx, err := db.Begin(ctx)
if err != nil {
return err
}
defer tx.Rollback()
var paymentID, leaseID, amount int64
from := "pending"
if e.Outcome == "reversed" {
from = "succeeded"
}
err = tx.QueryRow(ctx, `
UPDATE payments SET status = $2
WHERE provider_id = $1 AND status = $3
RETURNING id, lease_id, amount_cents`, e.ProviderID, e.Outcome, from).Scan(&paymentID, &leaseID, &amount)
if errors.Is(err, sqldb.ErrNoRows) {
return nil // already processed or unknown payment
} else if err != nil {
return err
}
switch e.Outcome {
case "succeeded":
// Allocate oldest due first, locking open charges for this lease.
rows, err := tx.Query(ctx, `
SELECT id, amount_cents - paid_cents FROM charges
WHERE lease_id = $1 AND paid_cents < amount_cents
ORDER BY due_on, id FOR UPDATE`, leaseID)
if err != nil {
return err
}
type open struct{ id, due int64 }
var opens []open
for rows.Next() {
var o open
if err := rows.Scan(&o.id, &o.due); err != nil {
rows.Close()
return err
}
opens = append(opens, o)
}
rows.Close()
left := amount
for _, o := range opens {
if left == 0 {
break
}
apply := min(left, o.due)
if _, err := tx.Exec(ctx, `UPDATE charges SET paid_cents = paid_cents + $2 WHERE id = $1`, o.id, apply); err != nil {
return err
}
if _, err := tx.Exec(ctx, `INSERT INTO allocations VALUES ($1, $2, $3)`, paymentID, o.id, apply); err != nil {
return err
}
left -= apply
}
// Any remainder stays on the ledger as a credit for future charges.
if _, err := tx.Exec(ctx, `
INSERT INTO ledger_entries (lease_id, kind, ref_id, amount_cents)
VALUES ($1, 'payment', $2, $3)`, leaseID, paymentID, -amount); err != nil {
return err
}
case "reversed":
// Undo allocations and post the reversal to the ledger.
if _, err := tx.Exec(ctx, `
UPDATE charges c SET paid_cents = c.paid_cents - a.amount_cents
FROM allocations a WHERE a.charge_id = c.id AND a.payment_id = $1`, paymentID); err != nil {
return err
}
if _, err := tx.Exec(ctx, `
INSERT INTO ledger_entries (lease_id, kind, ref_id, amount_cents)
VALUES ($1, 'reversal', $2, $3)`, leaseID, paymentID, amount); err != nil {
return err
}
}
return tx.Commit()
}
A failed payment never touched the ledger, so the status change is all it needs. A reversed payment, a return or a lost dispute after success, undoes its allocations, which reopens those charges, and the next daily run can apply a late fee if the grace period has passed. Tenant credit from overpayment is visible as a negative balance, and a later allocation pass can apply it to new charges.
The tenant balance is one query, SELECT COALESCE(SUM(amount_cents), 0) FROM ledger_entries WHERE lease_id = $1, exposed through a typed API behind your auth handler. Owner payouts should come only from payments that succeeded and have passed your hold period, for example five business days, recorded in their own table so each payment pays out once.
Encore tracing follows a payment event from the webhook through allocation, which is the first thing support needs when a tenant asks why a payment shows as pending. Charge and fee rules live in SQL and Go in the repository, so an agent asked to add a utility charge or a new fee rule changes them in a pull request with tests, and any new table or job ships in that same reviewed change.
Best fit: proptech and property management teams that want rent, fees and ledgers in their own AWS or GCP account, with payment providers holding the bank details.
Property management suites include rent collection, and smaller landlords should use one. Building fits proptech products where rent collection is part of the product, such as a resident app, a rent reporting or flexible rent feature, or a platform serving many managers with their own rules. The parts to get right are the ones above: idempotent charges, late fees as lease data, payments that are pending until confirmed, allocation oldest first, and a ledger that explains every balance.
A scheduled job posts a rent charge to each active lease's ledger on its due date, a second job applies late fees once the grace period passes, tenants pay by ACH or card through a payment provider, webhooks report when payments succeed or fail, and the backend allocates each payment to the oldest open charges. The tenant balance is the sum of the ledger entries.
Give each charge a natural key such as (lease_id, kind, period), for example lease 42, rent, 2026-12, and enforce it with a unique constraint. The charge job inserts with ON CONFLICT DO NOTHING, so a job that runs twice or retries after a timeout posts each month's rent once.
ACH debits take up to four business days to confirm success or failure with providers such as Stripe, and a consumer can dispute a debit through their bank for up to 60 calendar days. Mark the payment pending when initiated, apply it to charges when it succeeds, and hold owner payouts until it has cleared by your chosen policy.
Yes. Encore gives you cron jobs for charge and late fee runs, Postgres for leases and the ledger, Pub/Sub for payment events, typed APIs for tenant and manager apps, and secrets for the payment provider, all declared in Go and deployed to your own AWS or GCP account.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.