91 lines
4.4 KiB
Markdown
91 lines
4.4 KiB
Markdown
# 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.
|