Compact descriptors bind government-payment context

What the public implementation shows

The Government Payments gateway contains a DescriptorService, a required DescriptorHmacSecret, and verification responses that carry normalized bill-payment fields.

The descriptor crosses an interface constrained by participant payload shape while the authoritative bill remains in the gateway. This is the implementation fact behind the note; the architectural reading begins from that visible boundary rather than from an assumed production story.

Operating principleA compact field can carry context safely only when its contents and integrity are governed.

The decision behind the mechanism

An integrity-protected compact representation lets later payment confirmation detect altered context without making the descriptor the bill record.

An unsigned concatenated reference can be edited between verification and payment, changing account or obligation context. The mechanism matters because it gives that failure a named boundary, durable evidence, and a controlled response instead of leaving the outcome to timing or operator guesswork.

• Canonicalize fields before calculating the HMAC.
• Keep the descriptor secret outside source and ordinary configuration.
• Version the payload format.
• Revalidate the referenced bill at payment time.

How the control should be operated

Descriptor versions, secret rotation, field canonicalization, validation failures, and maximum size should be managed as an integration contract.

The participant can carry verified context while the gateway rechecks it against durable bill state. The reusable lesson is not to copy a class or endpoint in isolation, but to preserve the relationship between identity, state, authority, evidence, and operational ownership.