govoplan-payments/docs/PAYMENTS_DOMAIN.md

Payments Domain Boundary

Purpose

Payments records payment obligations and authoritative settlement evidence for GovOPlaN procedures. The first vertical slice is deliberately narrow: a Case, Workflow, or other owner requests a fixed amount, and an authorized operator records a full offline/manual receipt against immutable evidence.

Ownership and contract

Payments owns:

• the tenant-bound payment ID and human payment reference;
• requested amount, ISO currency, subject, due time, and lifecycle state;
• replay-safe request and reconciliation semantics;
• the external transaction reference and typed evidence reference; and
• append-only request and reconciliation events.

Procedure modules call Core's payments.requests capability. They provide their own stable source resource and optional Case/Workflow context references, then retain the returned payment ID. They never import Payments models. Payments does not own the Case, Workflow, applicant, invoice, journal entry, evidence binary, or payment-provider transaction.

Manual reconciliation

The first path supports exactly one full reconciliation. The supplied amount and currency must equal the obligation. Evidence must belong to the same tenant and carry a version or checksum so the observation can be reconstructed. The operator also records the external transaction reference and received time; the API assigns the recorded time from the server clock. All supplied timestamps require a timezone.

The request and reconciliation commands are idempotent. Reusing a key with the same canonical command returns the existing result; changing any material field conflicts. Once paid, another reconciliation under a different key fails closed. Corrections, reversals, refunds, chargebacks, partial payments, and overpayments require future append-only adjustment types and must never mutate the original evidence silently.

Operator workspace

The permission-aware /payments workspace is the operator projection of this contract. Readers can filter requested and paid obligations and inspect their source, Case/Workflow context references, amount, due or settled time, and immutable evidence reference. Writers create fixed obligations in a guided dialog; the UI supplies an explicit replay key and never copies applicant or Form content into Payments.

Reconciliation uses a separate consequential dialog. Amount and currency are fixed from the selected obligation rather than editable. The operator records the external transaction reference, receipt time, evidence owner, kind, ID, and at least one immutable version or checksum. The dialog explains that paid state cannot be silently undone and that a governed adjustment is required. Missing permissions remain visible with the exact scope and responsible administrator.

Reload is always available in the collection action bar. A failed refresh preserves the last successful result and labels it stale; an initial failure uses a whole-surface retry state. The workspace also distinguishes loading, empty, permission-blocked, conflict, replay-success, and ordinary success states.

Access, privacy, and audit

Payment readers see obligation and reconciliation metadata. Writers create obligations, while the separate reconciliation permission records receipt. The contract needs stable procedure references, not applicant names, bank account details, or Form values. Evidence bytes remain with Files or another owner; Payments stores only EvidenceReference metadata.

Each state transition writes a Payment event. API transitions also emit Core audit evidence; installations with Audit retain it through the Audit owner. Automated capability consumers must retain their own command/effect evidence and the returned payment ID in the owning Case or Workflow.

Recovery and retirement

Restore obligations, reconciliations, and events together. Verify one unique payment ID and payment reference per tenant, one matching reconciliation for each paid obligation, exact amount/currency equality, same-tenant immutable evidence, and ordered lifecycle events. Replay the original keys and hashes to confirm they return the restored objects.

Destructive retirement is blocked while any of the three tables contain data. It requires a verified database snapshot and an explicit records/accounting decision for the retained evidence references. Ledger posting, XRechnung, online checkout, callbacks, and provider reconciliation are not implied by this slice.