Landlord API — Rent & Payments (v1)

Lets a landlord's AI agent read tenancies, the rent ledger, tenant payment claims, landlord receipts, and proof files through the Landlord Rental API v1, and confirm or reject tenant claims. A strict confirm gate, one locked review transaction with audit fields, and transition-only tenant email keep agent actions safe and traceable.

  • Predecessor Landlord API slices 1–3; Landlord API — Enquiries & Offers (2026-10-03-landlord-api-enquiries-design.md)
  • ADRs 0058 · 0061 · 0068 · 0071
  • Status Approved

View source markdown ↗ generated by claude-opus-5-5 · diagrams mermaid

Summary

A landlord's AI agent can follow rent and review tenant payment claims through the Landlord Rental API v1. It reads tenancies, the ledger, payment records, and proof files, and can confirm or reject tenant claims. A strict confirm gate, one locked review transaction with audit fields, and email only on real status changes keep every agent action safe and traceable.

  • Status Draft, grill closed (Q1–Q6, F1–F4)
  • Bundle Money, agreements, tenants — rent and payments only for now
  • Scopes tenancies:read, payments:read, payments:write
  • Surface 8 endpoints under /api/v1/rental
  • Delivery Two OpenSpec changes: backend/go, frontend/solidstart
  • ADRs Related 0058, 0061, 0068, 0071 · no new ADR
Predecessors
Landlord API slices 1–3; Landlord API — Enquiries & Offers (2026-10-03-landlord-api-enquiries-design.md)
Glossary
CONTEXT.md — Tenancy, Payment Record, Reversal, Charge Cancellation
Grill log
.docs/grill-with-docs/2026-10-03_landlord-api-rent-payments_123307_grill-review.json (Q1–Q6, F1–F4)

Goal

The agent uses an API key with the Money, agreements, tenants bundle. Success means it can answer three questions: "who has paid?", "who is overdue?", and "what is waiting for review?".

  • Confirm a clean claim, and reject a wrong one with a reason.
  • With an explicit override and a written note, confirm a claim the automatic checks flagged.
  • Every review action is recorded as done by the assistant.

This is the first of four sub-projects for the bundle. The others are Agreements (read-only), Move-in handover, and Contacts, each with its own spec. Until they ship, the bundle covers rent and payments only.

Decisions

#DecisionChoice
D1Scope of actionsRead tenancies, the rent ledger, payment records (tenant claims and landlord receipts), and the proof file. Confirm and reject tenant claims. Reversal, creating landlord receipts, charge cancel/reopen, late notices, and the pay-to name stay in the portal.
D2EvidenceThe agent sees claim fields, the AI verdict, the payee check, duplicate signal types, and the proof file exactly as uploaded.
D3Confirm gateA clean claim confirms directly. A flagged claim needs override_checks: true and a non-empty review_note. Otherwise 409 payment_checks_not_clean. Clean requires payee_check = match; not_set is not clean.
D4AuditNew review_via (api / portal) and review_override (bool), written in the same locked transaction as the status change. The portal shows "via your assistant" and the override note.
D5Tenant dataFirst name only in every JSON body, from the account name (users.name), never from agreement terms. The proof file is the only place tenant or bank details may appear.
D6Test keysA tenancy takes the test/live mode of its property. A mismatch reads as 404.
D7MoneyInteger sen everywhere (240000 = RM2,400.00). Frozen agreement rent (whole ringgit) is multiplied by 100.
D8ImplementationDedicated v1_payment_handler.go. Reads use landlord + mode + non-draft scoped queries, not the portal's GetPaymentRecord or StreamPaymentProof. Confirm and reject call the shared use cases with an explicit review input; gate, v1 status rules, and audit fields are applied inside the locked transaction. Allowlisted DTOs; v1 error codes. Portal response semantics unchanged except audit presentation and duplicate-email suppression.
D9RetriesIdempotency-Key on reject only. Repeat confirm returns 200. Repeat reject returns 409 unless it is an Idempotency-Key replay. The tenant is emailed only when the status really changes.
D10Overdueis_overdue and overdue_sen use the existing ledger rule. A pending claim does not change them. No new summary fields.
D11Tenancy statusscheduled | active | ended over the Malaysian calendar interval [starts_on, ends_on). ends_on is exclusive.
D12Record kindsLists and details return every non-draft record, with recorded_by: tenant | landlord. Actions apply only to tenant claims.

Scopes come from the existing bundle: tenancies:read, payments:read, payments:write. No Bun change.

Why, and what was rejected

D3 · Is a claim with no stored pay-to-name check clean?

No. payee_check = match is required; not_set is a separate, not-clean value.

ai_verdict = agrees already excludes payee mismatch and unknown (payment_extraction.go:91-117). The payee rule blocks one more case only: no pay-to-name check was stored. Without it, nothing shows the money reached the landlord's account, and the agent cannot see the bank.

Rejected: treat not_set as clean; map the stored empty value to unknown (mixes "set a pay-to name" with "the names could not be decided", so the agent gives the wrong advice).

D4 · Where are the audit fields written?

Inside the same locked transaction as the status change.

The audit must match the decision it describes. Writing it outside the lock could label a review that another request made.

Rejected: derive review_via from request context after the use case returns.

D5 · Which name identifies the tenant?

First word of the account name, users.name.

Enquiries already project first_name this way (viewing_request.go:93-99). One source keeps the same tenant recognisable across endpoints. The agreement holds the frozen legal identity (ADR-0058).

Rejected: first word of the agreement's terms.tenant.full_name.

D8 · Reuse portal reads, or scoped v1 queries?

Scoped landlord + mode + non-draft queries; gate and status rules inside the use case's row lock.

GetPaymentRecord and StreamPaymentProof authorise either tenancy party, do not check mode, and the stream does not hide drafts (payment.go:533-553, 646-666). A status check before the use case runs is outside the row lock and can be stale.

Rejected: reuse portal reads as they are; pre-read the status in the v1 layer; portal-compatibility shims.

D9 · How do retries behave?

Keep the drafted reject contract with Idempotency-Key; send email only after a real transition.

Today a repeat confirm emails the tenant again (payment.go:728-731, 783-785). A repeat reject emails again with the new request reason, while the old reason stays stored (payment.go:817-845). The reject contract with Idempotency-Key is an explicit scope decision.

Rejected: drop Idempotency-Key and make repeat reject 200 everywhere.

D10 · Does a pending claim change "overdue"?

No. Overdue stays the ledger rule; agents join pending claims themselves.

An overdue charge is unsettled ledger debt; a pending claim is an unverified statement. Nothing stops two pending claims from selecting one charge (payment.go:591-635), so a single "pending claim" field would be wrong. The agent joins GET /payment-records?status=pending_review&tenancy_id=… on charge_ids.

Rejected: pending_record_id on the charge; awaiting_review_sen on the tenancy; is_overdue = false while a claim is pending.

D11 · Which status words and end-date rule?

scheduled | active | ended over [starts_on, ends_on).

CONTEXT.md (Tenancy) and the portal (tenancyProjections.ts:34-56) already use these words and this interval. ends_on is starts_on plus the term (tenancy_test.go:183).

Rejected: upcoming; an inclusive end date; changing the glossary to match the draft.

D12 · How do landlord receipts appear?

Returned with recorded_by: landlord and null checks, review, submitted_at, proof.

A landlord receipt is born confirmed with no proof, AI, or review (CONTEXT.md Payment Record; payment.go:997-1015). Shown as a claim, it looks like a flagged claim confirmed without checks.

Rejected: hide receipts; a recorded_by filter.

Endpoints

All under /api/v1/rental.

#Method and pathScopePurpose
1GET /tenanciestenancies:readLandlord's tenancies. Filter status (scheduled, active, ended). Paginated.
2GET /tenancies/{id}tenancies:readOne tenancy.
3GET /tenancies/{id}/chargestenancies:readRent ledger: every charge with status and overdue flag.
4GET /payment-recordspayments:readTenant claims and landlord receipts. Filters status, tenancy_id. status=pending_review is the review queue, oldest first; otherwise newest first. Paginated. Drafts never shown.
5GET /payment-records/{id}payments:readOne record with its checks.
6GET /payment-records/{id}/proofpayments:readProof file as uploaded, with the media type stored on the record.
7POST /payment-records/{id}/confirmpayments:writeTenant claims only. Body { "review_note"?, "override_checks"? }.
8POST /payment-records/{id}/rejectpayments:writeTenant claims only. Body { "reason" }, required. Supports Idempotency-Key.

Pagination: same {items, pagination} envelope and page/limit rules as GET /properties.

Response shapes

Tenancy

{
  "id": "…",
  "property_id": "…",
  "listing_id": "…",
  "status": "scheduled | active | ended",
  "starts_on": "2026-11-01",
  "ends_on": "2027-11-01",
  "monthly_rent_sen": 240000,
  "tenant": { "first_name": "Aisha" },
  "property": { "building_name": "Arcoris", "unit_number": "A-12-3", "area": "Mont Kiara" },
  "overdue_sen": 240000,
  "open_sen": 480000,
  "next_due": { "charge_id": "…", "due_on": "2026-12-01", "amount_sen": 240000 }
}
Tenancy status over the half-open interval from starts_on to ends_on: scheduled before starts_on, active from starts_on up to but not including ends_on, ended from ends_on onwards. scheduled active ended starts_on (incl.) ends_on (excl.)
Tenancy status in Malaysian calendar dates over [starts_on, ends_on). The last day of the tenancy is the day before ends_on.
  • status is derived from today's date in Asia/Kuala_Lumpur over [starts_on, ends_on). It is not stored.
  • ends_on is exclusive. The tenancy is ended from that date. The example is a 12-month tenancy.
  • listing_id comes from the tenancy's agreement row. monthly_rent_sen is the agreement's frozen monthly_rent (whole ringgit) × 100, the same conversion as the charge schedule (tenancy.go:185). These are the only two agreement values read. Identity terms are never projected.
  • tenant.first_name is the first word of the tenant's account name (users.name, split by whitespace). An empty name gives "". It reuses the enquiries API projection.
  • overdue_sen sums charges where is_overdue is true. open_sen sums all open charges.
  • next_due is the earliest open, not-overdue charge, or null.

Charge

{
  "id": "…",
  "type": "rent | security_deposit | utility_deposit",
  "amount_sen": 240000,
  "due_on": "2026-11-01",
  "status": "open | paid | cancelled",
  "is_overdue": true,
  "paid_by_record_id": "… | null"
}
  • is_overdue uses entity.IsChargeOverdue: the charge is open and due_on is before today in Malaysia. The portal ledger and the dashboard use the same rule.
  • A pending claim does not change status or is_overdue. A charge becomes paid only when a claim is confirmed or a receipt is recorded.
  • paid_by_record_id is the record of the charge's active allocation, or null.

Payment record

Tenant claim:

{
  "id": "…",
  "tenancy_id": "…",
  "recorded_by": "tenant",
  "status": "pending_review | confirmed | rejected | reversed",
  "amount_sen": 240000,
  "payment_method": "bank_transfer | cash | other",
  "paid_on": "2026-11-01",
  "reference": "…",
  "charge_ids": ["…"],
  "submitted_at": "…",
  "checks": {
    "ai_verdict": "agrees | differs | fields_unreadable | not_applicable | null",
    "differs_fields": ["amount"],
    "payee_check": "match | mismatch | unknown | not_set",
    "duplicate_signals": ["same_proof_hash"],
    "clean": true
  },
  "proof": { "media_type": "image/jpeg", "sha256": "…" },
  "review": { "note": "… | null", "reviewed_at": "…", "via": "api | portal | null", "override_checks": false },
  "rejection_reason": null,
  "created_at": "…",
  "updated_at": "…"
}

Tenant claim

recorded_by: tenant
  • Status pending_review, confirmed, rejected, or reversed
  • checks object with the stored verdict and clean
  • Can be confirmed or rejected by the agent

Landlord receipt

recorded_by: landlord
  • Status confirmed or reversed
  • checks, review, submitted_at, proof, rejection_reason are all null
  • Creation stamps a review time in storage; that is creation, not a review, so it is not shown as review
  • Read-only for the agent

Checks (tenant claims only)

  • ai_verdict is the stored verdict. Submit always computes it, and a claim with no extraction gets not_applicable (no proof, no consent, AI refused, provider failure; payment.go:620-626). null appears only if the stored value is empty. The API does not invent a result and does not assume every row conforms. A null verdict is never clean.
  • duplicate_signals lists only each signal's signal_type. The free-text detail is never returned.
  • checks.clean is the server's verdict for the confirm gate.
match
The proof's payee matched the pay-to name.
mismatch
The names differ.
unknown
The names could not be decided.
not_set
No pay-to-name check result was stored when the proof was evaluated (no pay-to name set, or no extraction).

Review projection (tenant claims only)

Claim statusreviewreview.noterejection_reason
pending_reviewnull—null
confirmedobjectstored note, null when emptynull
rejectedobjectnullstored note (the reason)
reversedobject, kept from the confirmstored note, null when emptynull
  • Confirm and reject both store their text in one column, review_note (payment.go:765-773, 825-833). The API splits it by status as above.
  • A reversal does not touch the review (payment.go:910-914). The reversal itself is out of scope.
  • review.via and review.override_checks read review_via and review_override. Records reviewed before this change have null. There is no backfill.

Other fields

  • proof is null when no file was stored. proof.media_type is the media type stored on the record.

Behaviour

Access

Existing v1 chain: API key → per-key rate limit → audit context → landlord role → RequireKeyScope. A missing scope returns 403 insufficient_permission.

Ownership and mode isolation

A tenancy is visible only when landlord_user_id equals the key's user and its property's is_test equals the key's mode. Charges and payment records are reachable only through a visible tenancy. Everything else returns 404 and is left out of lists and counts: another landlord, the wrong mode, a tenancy where the key's user is the tenant, and tenant drafts. It is enforced in SQL.

Every v1 read, including the proof route, uses these scoped queries. v1 does not call GetPaymentRecord or StreamPaymentProof, which authorise either tenancy party and do not check mode.

Every read goes through a visible tenancy; everything else is 404 and absent from lists and counts
Every read goes through a visible tenancy; everything else is 404 and absent from lists and counts.

Tenant data and the proof file

JSON bodies name the tenant by first name only. The proof file may show tenant and bank details. Exposing it is an explicit decision (D2).

  1. Scoped lookup

    Find the record with the landlord + mode + non-draft query. Not found → 404 payment_record_not_found.

  2. Proof present?

    No stored proof (no storage key, which includes every landlord receipt) → 404 proof_not_found.

  3. Open the store

    Any failure → 503 media_unavailable. ProofStore.Open returns a plain wrapped error (proof_store.go:79-83), so the handler maps it on purpose; otherwise it would render as 500 internal_error.

  4. Stream unchanged

    Content-Type is the record's stored proof_media_type, not a guess from the key's file extension, so the header matches proof.media_type in the JSON.

Confirm gate

  • ai_verdict = agrees (already excludes payee mismatch and unknown; null and not_applicable fail) AND
  • payee_check = match (adds one case: not_set fails) AND
  • duplicate_signals empty = clean

fields on the 409 lists the failing checks: ai_verdict, payee_check, duplicate_signals.

The gate is evaluated on the row loaded with GetByIDForUpdate, inside the confirm transaction. The checks do not change after submit, but the status can. One lock covers status, gate, allocation, and audit.

Confirm flow inside one locked transaction. The tenant is emailed only after the commit of a real status change
Confirm flow inside one locked transaction. The tenant is emailed only after the commit of a real status change.

ConfirmPaymentRecord keeps its guarantee that every selected charge is still open; otherwise 409 charge_already_settled. A landlord receipt is never pending_review; a confirm or reject on one gets 409 payment_status_conflict.

Review input and audit fields

Inputv1Portal
Channelapiportal
Note or reasonfrom the bodyfrom the body
Override requestedoverride_checksalways false
Policygate on; repeat reject is a conflictno gate; repeat reject returns 200

The portal handlers are migrated to this input directly. There are no compatibility shims. Inside the locked transaction, together with the status change, the use case writes:

review_via
From the channel. Column TEXT CHECK (review_via IN ('api','portal')), nullable.
review_override
true only for a confirm of a flagged claim that used the override. override_checks: true on a clean claim stores false. Rejects and portal confirms store false. Column BOOLEAN, nullable.

A repeat that changes nothing writes nothing. The landlord's payment detail and review queue show "Confirmed via your assistant" / "Rejected via your assistant", plus "Checks overridden: {note}" when review_override is true. Tenant-facing views and emails are unchanged.

Reject

Calls the shared reject use case with the review input. A reason is required. The tenant is emailed as today, once. Idempotency-Key runs through the existing idempotency executor, as message posts do: the same key and body replay the first result with Idempotent-Replay: true; the same key with another body is 409 idempotency_conflict.

Repeats and email

RequestRecord statusv1Portal
Confirmconfirmed200, stored record200, stored record
Confirmrejected / reversed409 payment_status_conflictunchanged
Rejectrejected409 payment_status_conflict, unless Idempotency-Key replay200, stored record
Rejectconfirmed / reversed409 payment_status_conflictunchanged
  • The v1 reject rule is checked under the same GetByIDForUpdate lock, not by an earlier read.
  • The tenant email is sent only after a real status change commits. A repeat sends nothing.

Agent guidance (API guide)

  • Overdue vs pending. An overdue charge is unsettled ledger debt. A pending claim is an unverified statement from the tenant. For an overdue charge, list GET /payment-records?status=pending_review&tenancy_id=… and match on charge_ids. If a claim covers it, say "awaiting your review", never "paid" and never "definitely unpaid". Several pending claims may select one charge.
  • Duplicate signals. Detection compares against every record in the tenancy, including records the API hides, such as tenant drafts. Compare proof.sha256 and reference with the tenancy's visible records. A match on a rejected claim often means a resubmission; it is still flagged and still needs the gate. With no visible match, report the signal as unresolved. Do not guess at a hidden record, and do not treat the claim as safe.
  • payee_check: not_set. Ask the landlord to set the pay-to name in the portal for future claims. It does not recheck claims already submitted.
  • first_name is a display fragment from the account name, not a verified legal identity. Its first-word rule is a known limitation for some Malaysian names (for example a surname written first).
  • Tenancy dates. The last day is the day before ends_on.

Errors

Frozen v1 envelope. Reused: validation_failed, all 401/403/429 codes, idempotency_conflict, internal_error, auth_unavailable, rate_limit_unavailable, media_unavailable, route_not_found, method_not_allowed.

StatusNew codeWhen
404tenancy_not_foundMissing, not this landlord's, wrong mode, or the key's user is the tenant.
404payment_record_not_foundSame, plus tenant drafts.
404proof_not_foundThe record has no stored proof, including every landlord receipt.
409payment_checks_not_cleanConfirm on a flagged claim without override. fields = failing checks (ai_verdict, payee_check, duplicate_signals).
409payment_status_conflictConfirm or reject not allowed in the current status, or the record is a landlord receipt.
409charge_already_settledA claimed charge is no longer open (ErrChargeNotSelectable).
  • media_unavailable (503) also covers a proof that has a storage key but cannot be opened.
  • validation_failed covers: missing review_note with override; missing reject reason; an unknown status filter (including draft and upcoming); a malformed tenancy_id filter.

Frontend and documentation

  • Key form: enable Money, agreements, tenants (unchecked by default). Label it "no agreements or handover yet". Add a "Can confirm rent payments" warning.
  • Payment detail and review queue: "Confirmed / Rejected via your assistant", plus "Checks overridden: {note}" when review_override is true; en/ms/zh.
  • Dashboard API card: mention checking rent and confirming payments.
  • API guide: new "Rent and payments" section covering money in sen; tenancy status and exclusive ends_on; the ledger; tenant claims vs landlord receipts; the review-queue workflow; the confirm gate, override, and note; payee_check values; the proof file; the first-name rule; the agent guidance; and the error codes.

Contract and testing

openapi/rental-v1.yaml: 8 operations; schemas including the binary proof response, recorded_by, nullable checks / review / proof, payee_check with not_set, and tenancy status with scheduled; 6 new error codes; Idempotency-Key on reject. Drift test and contract table updated.

Go tests

Contract table
Rows for all 8 routes.
Golden no-PII
No tenancy, charge, or payment-record body contains full_name, phone, email, nric, address_line, payer_name, payee_name, ai_extraction, tenant_user_id, landlord_user_id. Extend the NRIC golden test to these routes. A tenancy whose agreement legal name differs from users.name returns the account first word.
Isolation
Other landlord, wrong mode, key user as tenant, and tenant drafts are 404 and absent from lists and counts, including the proof route.
Tenancy
scheduled / active / ended around both boundaries, with ends_on exclusive; listing_id and monthly_rent_sen (ringgit × 100) from the agreement; empty account name → first_name: "".
Ledger
An overdue charge with a pending claim stays open and is_overdue: true.
Records
A landlord receipt has recorded_by: landlord and null checks, review, submitted_at, proof; a tenant claim with no extraction shows not_applicable; a stored empty verdict shows null and clean: false; stored empty payee match shows not_set.
Review projection
Pending → review: null; rejected → rejection_reason set and review.note: null; confirmed then reversed keeps review.note; pre-change rows show via: null.
Confirm gate
Clean → confirmed; each failing check without override → 409 with that field, including not_set; override without note → 400; override with note → confirmed with review_via = 'api', review_override = true; override_checks: true on a clean claim → review_override = false; settled charge → 409 charge_already_settled; landlord receipt → 409 payment_status_conflict.
Repeats
Repeat confirm → 200 and no second email; repeat v1 reject → 409, and with the same Idempotency-Key → replay with Idempotent-Replay: true, no second email; portal repeat reject → 200 and no second email; concurrent v1 confirm and reject on one claim → one review, one email.
Proof
Streamed with the stored media type; no storage key → 404 proof_not_found; store open failure → 503 media_unavailable.
Email parity
A v1 confirm sends the same tenant email as a portal confirm.

Frontend tests

  • "via your assistant" label.
  • "Checks overridden" only when review_override is true.
  • Key-form bundle test.

Migration and delivery

Two nullable columns on rental_payment_records: review_via, review_override, added in migrator.go. No backfill; nothing is in production. Older reviewed records read as null.

  1. Backend · backend/go

    Endpoints, scoped reads, review input and gate in the shared use cases, transition-only email, columns, contract.

  2. Frontend · frontend/solidstart

    Key form, labels, dashboard, API guide.

Two OpenSpec changes, as for enquiries.

Risks

RiskMitigation
Agent confirms a wrong payment.Confirm gate under the record lock; override needs an explicit flag and a stored note; the landlord can reverse in the portal; every action labelled "via your assistant".
Proof files leak bank details to third-party AI.Explicit decision (D2); documented in the guide so landlords choose knowingly; payments:read is opt-in through an unchecked bundle.
Many claims need an override.payee_check names the cause. not_set → the guide tells landlords to set the pay-to name for future claims. While the Jev payee switch is off (ADR-0071), near names stay unknown; this is accepted.
Agent reports a claimed charge as paid, or as unpaid.Guidance: overdue is ledger debt, a pending claim is unverified; say "awaiting your review".
Agent explains a duplicate signal with a record it cannot see.Unresolved signals are reported as unresolved; detail text and drafts are never exposed.
Retries send duplicate emails or change the stated reason.Email only after a real transition; repeat rules checked under the lock; Idempotency-Key on reject.
Bundle name promises more than it delivers.Key-form label "no agreements or handover yet" until the other sub-projects ship.
PII through a future shared field.Allowlisted DTOs; only listing_id and monthly_rent read from the agreement; golden no-PII test.
A landlord who is also a tenant acts as tenant.Only landlord-side reads and actions mounted; every query filters on landlord_user_id.

Assumptions and limits

  • Known limits, accepted: first-word display names; unknown payee results while ADR-0071's switch is off; duplicate signals that cannot be explained from visible records.
  • No new ADR. The decisions are reversible API-layer and use-case choices.
  • No CONTEXT.md change. The draft's upcoming and "receipt file" were drift from the glossary, now fixed in the spec.