3.2 KiB
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.
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.