Opening questions
Location (url) of the problem
https://specs.govstack.global/payments/6-functional-requirements#id-6.1-payment-orchestration
What is the problem you see?
Issue
The current requirement in the Payments specification reads:
(Given a payment is sent) Sending receipts, notifications, and acknowledgement of receipts in a secure manner to payers and other external applications.
This requirement conflates the Payments BB's own concern — signalling that a payment completed — with delivery mechanics, routing decisions, and acknowledgement protocols that belong to the inter-BB communication layer. As written, it implies the Payments BB is responsible for choosing which downstream Building Block to contact and how acknowledgement works, which is not the Payments BB's domain.
Under the GovStack architecture (§4.5.3), communication between BBs is expected to be mediated by an Information Mediator BB instance, though direct BB-to-BB connections are permissible. The Payments BB specification must not assume one topology or the other, nor must it name a specific downstream Building Block as the target. (on this I'd would like to invoke @kristovaher and @EastHastings for validation )
Analysis
What the Payments BB owns
The Payments BB's responsibility ends at its own boundary: confirming that a payment has completed and emitting that fact as a notification signal. It must not specify how that signal is routed, which BB ultimately receives or delivers it, or what the transport and delivery mechanism looks like.
What the Payments BB does not own
| Concern |
Why it does not belong here |
| Delivery to human recipients |
Belongs to whichever BB handles person-facing messaging in the deployment; the Payments BB must not reference this BB directly |
| Routing and transport |
Whether the signal travels via an IM BB instance or directly to an adjacent BB is a deployment topology decision — the requirement must be agnostic |
| Delivery semantics |
Retry logic, backoff, deduplication, and audit trails belong to the transport layer |
What the requirement must preserve
The original requirement does capture one legitimate Payments BB concern: acknowledgement. Once the Payments BB emits a notification signal, it needs to know that signal was received. The requirement should specify this as an expected signal at the Payments BB boundary — without prescribing how the receiving side implements it or which BB provides it.
Proposed rewrite
Upon successful payment processing, the Payments Building Block must emit a notification signal to an external Building Block indicating the transaction result. The Payments Building Block must support receiving an acknowledgement signal in response, confirming that the notification was received. The Payments Building Block must not specify the delivery mechanism, routing topology, or the type of downstream recipient.
What this rewrite achieves
- Scopes the Payments BB to its proper concern: emitting a notification event and registering an acknowledgement
- Is agnostic about whether communication is mediated by an IM BB or goes directly to an adjacent BB
- Does not presuppose which BB ultimately handles the notification or delivers it to an end recipient
- Preserves acknowledgement as a first-class concern at the Payments BB boundary without prescribing the protocol
- Eliminates any delivery, routing, and acknowledgement logic that belongs to the transport layer, not this specification
Opening questions
Location (url) of the problem
https://specs.govstack.global/payments/6-functional-requirements#id-6.1-payment-orchestration
What is the problem you see?
Issue
The current requirement in the Payments specification reads:
This requirement conflates the Payments BB's own concern — signalling that a payment completed — with delivery mechanics, routing decisions, and acknowledgement protocols that belong to the inter-BB communication layer. As written, it implies the Payments BB is responsible for choosing which downstream Building Block to contact and how acknowledgement works, which is not the Payments BB's domain.
Under the GovStack architecture (§4.5.3), communication between BBs is expected to be mediated by an Information Mediator BB instance, though direct BB-to-BB connections are permissible. The Payments BB specification must not assume one topology or the other, nor must it name a specific downstream Building Block as the target. (on this I'd would like to invoke @kristovaher and @EastHastings for validation )
Analysis
What the Payments BB owns
The Payments BB's responsibility ends at its own boundary: confirming that a payment has completed and emitting that fact as a notification signal. It must not specify how that signal is routed, which BB ultimately receives or delivers it, or what the transport and delivery mechanism looks like.
What the Payments BB does not own
What the requirement must preserve
The original requirement does capture one legitimate Payments BB concern: acknowledgement. Once the Payments BB emits a notification signal, it needs to know that signal was received. The requirement should specify this as an expected signal at the Payments BB boundary — without prescribing how the receiving side implements it or which BB provides it.
Proposed rewrite
What this rewrite achieves