Skip to main content

Settlement Alias Lifecycle

Trusted settlement aliases are the only authoritative quote-to-reservation identity surface for CRM-linked Partner POS settlements. Operators can inspect and invalidate aliases, but they cannot promote raw observational evidence into trusted identity from the admin surface.

Admin Endpoints​

  • GET /api/admin/pos/settlements/aliases Lists aliases filtered by clubCode, posProvider, trustState, limit, and offset. Default filter is trustState=ACTIVE_TRUSTED.
  • GET /api/admin/pos/settlements/aliases/:id Returns the alias plus the currently linked acceptance anchor and accepted settlement request, if present.
  • GET /api/admin/pos/settlements/aliases/:id/events Returns the append-only lifecycle events for the alias in chronological order.
  • POST /api/admin/pos/settlements/aliases/:id/invalidate Invalidates an active alias. Request body requires actor and reasonCode; note is optional.

Audit Model​

Every alias lifecycle transition writes an append-only settlement_alias_events row:

  • UPSERTED Written when a durable settlement outcome proves or refreshes a trusted alias.
  • INVALIDATED Written when an operator explicitly invalidates an active alias.

Each event captures:

  • trust-state transition
  • actor
  • reason code
  • optional note
  • evidence snapshot with identifiers and source context

Operational Boundaries​

  • Alias invalidation is safe because it only removes trust; it does not mutate historical settlement requests or acceptance anchors.
  • Acceptance anchors remain workflow ownership state, not trusted identity authority.
  • Observational unresolved-identity evidence is exposed in the reconciliation report's unresolvedCrmIdentity section. Operators may inspect it, but it must not be promoted into trust from the admin surface.