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.
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.
- 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
| # | Decision | Choice |
|---|---|---|
| D1 | Scope of actions | Read 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. |
| D2 | Evidence | The agent sees claim fields, the AI verdict, the payee check, duplicate signal types, and the proof file exactly as uploaded. |
| D3 | Confirm gate | A 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. |
| D4 | Audit | New 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. |
| D5 | Tenant data | First 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. |
| D6 | Test keys | A tenancy takes the test/live mode of its property. A mismatch reads as 404. |
| D7 | Money | Integer sen everywhere (240000 = RM2,400.00). Frozen agreement rent (whole ringgit) is multiplied by 100. |
| D8 | Implementation | Dedicated 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. |
| D9 | Retries | Idempotency-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. |
| D10 | Overdue | is_overdue and overdue_sen use the existing ledger rule. A pending claim does not change them. No new summary fields. |
| D11 | Tenancy status | scheduled | active | ended over the Malaysian calendar interval [starts_on, ends_on). ends_on is exclusive. |
| D12 | Record kinds | Lists 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 path | Scope | Purpose |
|---|---|---|---|
| 1 | GET /tenancies | tenancies:read | Landlord's tenancies. Filter status (scheduled, active, ended). Paginated. |
| 2 | GET /tenancies/{id} | tenancies:read | One tenancy. |
| 3 | GET /tenancies/{id}/charges | tenancies:read | Rent ledger: every charge with status and overdue flag. |
| 4 | GET /payment-records | payments:read | Tenant claims and landlord receipts. Filters status, tenancy_id. status=pending_review is the review queue, oldest first; otherwise newest first. Paginated. Drafts never shown. |
| 5 | GET /payment-records/{id} | payments:read | One record with its checks. |
| 6 | GET /payment-records/{id}/proof | payments:read | Proof file as uploaded, with the media type stored on the record. |
| 7 | POST /payment-records/{id}/confirm | payments:write | Tenant claims only. Body { "review_note"?, "override_checks"? }. |
| 8 | POST /payment-records/{id}/reject | payments:write | Tenant 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 }
}
[starts_on, ends_on). The last day of the tenancy is the day before ends_on.statusis derived from today's date inAsia/Kuala_Lumpurover[starts_on, ends_on). It is not stored.ends_onis exclusive. The tenancy isendedfrom that date. The example is a 12-month tenancy.listing_idcomes from the tenancy's agreement row.monthly_rent_senis the agreement's frozenmonthly_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_nameis 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_sensums charges whereis_overdueis true.open_sensums allopencharges.next_dueis the earliest open, not-overdue charge, ornull.
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_overdueusesentity.IsChargeOverdue: the charge isopenanddue_onis before today in Malaysia. The portal ledger and the dashboard use the same rule.- A pending claim does not change
statusoris_overdue. A charge becomespaidonly when a claim is confirmed or a receipt is recorded. paid_by_record_idis the record of the charge's active allocation, ornull.
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, orreversed checksobject with the stored verdict andclean- Can be confirmed or rejected by the agent
Landlord receipt
recorded_by: landlord- Status
confirmedorreversed checks,review,submitted_at,proof,rejection_reasonare allnull- 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_verdictis the stored verdict. Submit always computes it, and a claim with no extraction getsnot_applicable(no proof, no consent, AI refused, provider failure;payment.go:620-626).nullappears only if the stored value is empty. The API does not invent a result and does not assume every row conforms. Anullverdict is never clean.duplicate_signalslists only each signal'ssignal_type. The free-textdetailis never returned.checks.cleanis 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 status | review | review.note | rejection_reason |
|---|---|---|---|
pending_review | null | — | null |
confirmed | object | stored note, null when empty | null |
rejected | object | null | stored note (the reason) |
reversed | object, kept from the confirm | stored note, null when empty | null |
- 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.viaandreview.override_checksreadreview_viaandreview_override. Records reviewed before this change havenull. There is no backfill.
Other fields
proofisnullwhen no file was stored.proof.media_typeis 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.
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).
-
Scoped lookup
Find the record with the landlord + mode + non-draft query. Not found →
404 payment_record_not_found. -
Proof present?
No stored proof (no storage key, which includes every landlord receipt) →
404 proof_not_found. -
Open the store
Any failure →
503 media_unavailable.ProofStore.Openreturns a plain wrapped error (proof_store.go:79-83), so the handler maps it on purpose; otherwise it would render as500 internal_error. -
Stream unchanged
Content-Typeis the record's storedproof_media_type, not a guess from the key's file extension, so the header matchesproof.media_typein the JSON.
Confirm gate
-
ai_verdict= agrees(already excludes payeemismatchandunknown;nullandnot_applicablefail) AND -
payee_check= match(adds one case:not_setfails) AND -
duplicate_signalsempty = 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.
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
| Input | v1 | Portal |
|---|---|---|
| Channel | api | portal |
| Note or reason | from the body | from the body |
| Override requested | override_checks | always false |
| Policy | gate on; repeat reject is a conflict | no 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_overridetrueonly for a confirm of a flagged claim that used the override.override_checks: trueon a clean claim storesfalse. Rejects and portal confirms storefalse. ColumnBOOLEAN, 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
| Request | Record status | v1 | Portal |
|---|---|---|---|
| Confirm | confirmed | 200, stored record | 200, stored record |
| Confirm | rejected / reversed | 409 payment_status_conflict | unchanged |
| Reject | rejected | 409 payment_status_conflict, unless Idempotency-Key replay | 200, stored record |
| Reject | confirmed / reversed | 409 payment_status_conflict | unchanged |
- The v1 reject rule is checked under the same
GetByIDForUpdatelock, 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 oncharge_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.sha256andreferencewith 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_nameis 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.
| Status | New code | When |
|---|---|---|
| 404 | tenancy_not_found | Missing, not this landlord's, wrong mode, or the key's user is the tenant. |
| 404 | payment_record_not_found | Same, plus tenant drafts. |
| 404 | proof_not_found | The record has no stored proof, including every landlord receipt. |
| 409 | payment_checks_not_clean | Confirm on a flagged claim without override. fields = failing checks (ai_verdict, payee_check, duplicate_signals). |
| 409 | payment_status_conflict | Confirm or reject not allowed in the current status, or the record is a landlord receipt. |
| 409 | charge_already_settled | A claimed charge is no longer open (ErrChargeNotSelectable). |
media_unavailable(503) also covers a proof that has a storage key but cannot be opened.validation_failedcovers: missingreview_notewith override; missing rejectreason; an unknownstatusfilter (includingdraftandupcoming); a malformedtenancy_idfilter.
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_overrideis 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_checkvalues; 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 fromusers.namereturns 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/endedaround both boundaries, withends_onexclusive;listing_idandmonthly_rent_sen(ringgit × 100) from the agreement; empty account name →first_name: "".- Ledger
- An overdue charge with a pending claim stays
openandis_overdue: true. - Records
- A landlord receipt has
recorded_by: landlordand nullchecks,review,submitted_at,proof; a tenant claim with no extraction showsnot_applicable; a stored empty verdict showsnullandclean: false; stored empty payee match showsnot_set. - Review projection
- Pending →
review: null; rejected →rejection_reasonset andreview.note: null; confirmed then reversed keepsreview.note; pre-change rows showvia: 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 withreview_via = 'api',review_override = true;override_checks: trueon 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 withIdempotent-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_overrideis 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.
-
Backend ·
backend/goEndpoints, scoped reads, review input and gate in the shared use cases, transition-only email, columns, contract.
-
Frontend ·
frontend/solidstartKey form, labels, dashboard, API guide.
Two OpenSpec changes, as for enquiries.
Risks
| Risk | Mitigation |
|---|---|
| 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;
unknownpayee 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.mdchange. The draft'supcomingand "receipt file" were drift from the glossary, now fixed in the spec.