PH-12 — Transactional Communications and Documents¶

Payment Hub · Working Draft · Revised Working Copy v5 · Updated September 4, 2026

1. Objective¶

Provide the shared capability for payment-related transactional communications and, when required by a Product, payment documents.

PH-12 establishes:

Product-controlled transactional communications without coupling Product workflow to a specific email, SMS, CU platform, provider, or other delivery mechanism;
support for communications delivered by the CU or directly by DragonPay;
Tenant-appropriate branding/content and approved delivery configuration;
historically attributable message/document content;
duplicate-safe communication processing;
delivery/outcome tracking that remains separate from payment status;
support for actionable communications without moving action authorization into PH-12;
operational visibility into failed, expired, or unresolved communications; and
optional generation of immutable payment receipts/confirmations or other Product-required documents.

PH-12 is not a general communications platform, CRM, marketing system, customer-journey engine, or enterprise document-management system.

The exact notification service architecture, provider/adaptor model, message schema, template persistence, retry implementation, event transport, delivery-status taxonomy, and document-storage implementation are Engineering decisions provided the requirements in this epic are preserved.

2. Ownership boundaries¶

Owner	Responsibility
Payment Product / PH-04	Determines when a communication is required, its business purpose, intended recipient role, applicable expiration, and Product consequences of communication failure/expiration.
PH-01	Authorization for communication/document administration and privileged access.
PH-03	Authoritative payment identity, amount/currency, and payment state referenced by communications/documents.
PH-05	Party/contact information, relationship/authority facts, and masked Payment Instrument information.
PH-09	Durable payment history for material communication/document outcomes when applicable.
PH-11	Operational Case handling when communication problems require human action.
PH-12	Communication preparation/delivery, content/template history, delivery evidence, and optional payment-document generation.
PH-13 / Data Platform	Consolidated communication/document reporting and analytics.
CU/provider communication system	External delivery/acceptance evidence for the channel it operates.

PH-12 does not determine whether a payment succeeded, failed, expired, or may proceed.

3. Product communication requirements¶

Each Product defines the transactional communications required for its supported customer/payment flow.

A Product communication requirement identifies, at minimum:

business purpose;
intended recipient role;
whether the communication is required for the Product flow or informational;
the communication content/template to use;
any permitted delivery constraints;
whether it contains a Product action reference; and
applicable expiration/failure behavior when the communication is Product-critical.

The initial implementation may support only the few communication purposes actually required by the first Product.

PH-12 does not require a generalized administrator-authored communication rules engine.

Adding a future communication purpose or channel must not require redesign of the payment model.

4. Tenant delivery and content configuration¶

DragonPay must be able to determine how an approved Product communication is delivered for a Tenant.

Depending on the implementation, this may include:

delivery through a CU digital/member communication platform;
direct DragonPay delivery through an approved provider;
email;
SMS;
in-app/message-center delivery;
webhook/event delivery to an approved CU platform; or
another supported transactional channel.

Tenant communication configuration may also include:

approved branding;
sender identity;
locale/language;
delivery provider/path; and
Product/channel restrictions.

Only supported, validated delivery configuration may be used in production.

The exact profile/versioning/data structure is Engineering responsibility.

5. Templates and historical content¶

Transactional communication content must be controlled and historically attributable.

DragonPay must be able to determine which approved content/template was used for a communication or generated document.

Once a communication/document has been created from approved content, later template changes must not silently change the historical meaning or reproduce different content for that prior communication.

Template/content handling must:

use only approved variables/data;
minimize sensitive payment/customer information;
mask/tokenize financial identifiers where appropriate;
support Tenant branding/locale where required; and
preserve enough template/content identity to investigate what was sent or generated.

The initial Product does not require a visual template designer or generalized content-management platform.

The exact Template Version entity, content-hash strategy, asset repository, and publication workflow are Engineering decisions.

6. Communication creation and duplicate protection¶

PH-12 creates communication only from an authorized Product/workflow/system request.

PH-12 must not infer on its own that a payment event requires customer communication.

Each logical communication must have a stable identity sufficient to prevent technical retries or duplicate event delivery from producing uncontrolled duplicate messages.

A legitimate reminder, resend, or new customer communication must be represented as an intentional new communication action rather than bypassing duplicate protection.

The communication record must retain enough context to identify:

Tenant;
payment and related Product object;
communication purpose;
recipient;
selected delivery path/channel;
approved content/template used;
applicable Product action reference;
applicable expiration;
current delivery outcome; and
external delivery reference/evidence when available.

The exact idempotency key, fingerprint, persistence schema, or request contract follows shared standards and Engineering design.

7. Delivery and outcome handling¶

PH-12 delivers the communication through the Tenant-approved delivery path and normalizes the resulting delivery evidence.

Delivery outcome is separate from payment outcome.

Depending on channel/provider capability, DragonPay may know that a communication was:

prepared;
submitted/accepted by the external delivery system;
delivered;
rejected/bounced/failed;
expired/cancelled; or
unresolved/unknown.

DragonPay must not claim final recipient delivery/read status unless authoritative evidence supports it.

Externally supplied delivery results must be verified as originating from the approved delivery integration and correlated to the correct communication before they change recorded delivery outcome.

A provider/CU timeout or ambiguous response must not automatically be interpreted as definitive non-delivery when the communication may already have been submitted.

Retry of communication must be bounded and duplicate-safe.

The exact retry count, backoff, provider-idempotency behavior, circuit-breaker behavior, delivery-status enum, and resilience implementation are Engineering decisions.

Required communication¶

Communication failure is not payment failure.

When the owning Product requires a communication for progression, PH-12 reports its current outcome to PH-04/Product.

The Product determines whether to:

wait;
use another approved delivery path;
allow an authorized resend;
expire the applicable customer action;
escalate operationally; or
follow another Product-defined behavior.

Informational communication failure normally does not change payment processing.

A corrective/return-outcome communication must not be sent until the owning Product/payment service establishes the authoritative corrective result; PH-12 must not communicate that outcome as though it were already known merely because a preceding step failed or expired.

8. Actionable communications¶

A transactional communication may contain or reference a Product-owned customer action.

Examples may include:

recipient claim;
confirmation;
information submission;
another Product-controlled action.

PH-12 may deliver an opaque action reference but does not own or evaluate the action.

The owning Product/channel capability controls:

authentication/authorization;
action eligibility;
replay protection;
expiration/revocation;
challenge/verification behavior; and
resulting payment/workflow transition.

Action references exposed through communications must not contain sensitive payment/account/customer information.

A communication must not include the Sender-provided security word or other secret that the Product requires to be communicated separately from the invitation for independent recipient verification.

Successful delivery of a communication is not evidence that the recipient completed or was authorized for the action.

9. Provider integration boundary¶

Delivery-provider or CU-specific behavior must remain behind the communication integration boundary.

The integration is responsible for provider-specific:

authentication;
endpoint/message format;
field transformation;
recipient addressing;
submission semantics;
callbacks/events; and
external status interpretation.

PH-12 presents normalized communication behavior to Products regardless of the underlying provider.

The Product does not require a generalized adapter framework or runtime mapping engine as long as additional approved delivery integrations can be introduced without rewriting Product workflow behavior.

10. Transaction documents¶

A Product may require DragonPay to generate a transaction document such as a payment receipt or confirmation.

Document generation is required only when an implemented Product requires it.

When generated, a transaction document must:

be associated with the correct Tenant/payment;
use authoritative payment data appropriate to the document;
retain the approved template/content identity used;
preserve the generated content immutably;
be stored and accessed securely;
be retrievable only by authorized users/relationships; and
preserve corrections by creating a superseding/new document rather than silently modifying the original.

Generation of a document does not itself determine payment status.

The exact document format, rendering engine, storage provider, hash strategy, and document-service architecture are Engineering decisions.

11. Operational visibility¶

Operations must be able to identify communications that require attention, including where applicable:

failed delivery;
expired required communication;
unresolved/unknown delivery;
repeated retry failure;
invalid delivery configuration; or
document-generation failure.

Operational visibility should retain the applicable Tenant, payment, communication purpose, delivery path/provider, outcome, age, and relevant external/error reference without exposing sensitive message contents unnecessarily.

PH-11 may be used when a communication/document exception requires human investigation after safe automated handling is exhausted.

The exact queue/search fields, metrics, health dashboards, and alerts are Engineering/Operations decisions.

12. Example behaviors¶

CU-delivered payment notice¶

The Product determines that a payment-completion notice is required.

PH-12 prepares the approved Tenant communication and sends/publishes it through the CU-approved communication path.

DragonPay may record that the CU accepted the message/event.

It must not claim the member saw the final communication unless the CU supplies that evidence.

DragonPay-delivered recipient invitation¶

After the Product establishes that recipient invitation is permitted, PH-12 delivers the approved invitation through the configured channel.

The communication carries only the Product-controlled action reference.

Any claim challenge, authentication, security word, or payment authorization remains outside PH-12.

The Sender-provided security word must not be included in the recipient invitation.

Corrective-result communication¶

If a funded claim fails/expires and the Product creates a Return-to-Sender Action, PH-12 must not tell the Sender that funds were returned merely because the claim failed.

The return-completed communication is triggered only after the owning Product/payment services establish the authoritative corrective result.

Receipt¶

When an implemented Product requires a receipt, PH-12 generates it from the authoritative transaction information appropriate to that point in the payment lifecycle and preserves the resulting document immutably.

13. Product stories¶

PH12-01 — Define and Configure Transactional Communications¶

Objective

Allow implemented Payment Products and Tenants to define the communications they require and the approved ways those communications may be delivered.

Required behavior

Support Product-defined transactional communication purposes.
Identify recipient role, required/informational behavior, applicable content/template, and Product action/expiration requirements.
Configure Tenant-approved delivery path/channel, branding, sender identity, and locale where required.
Validate communication/delivery configuration before production use.
Keep Product workflow independent from specific delivery-provider mechanics.
Add only the communication purposes/channels required by implemented Products.

Acceptance

An unsupported communication purpose is not delivered ad hoc.
A Tenant cannot use an unapproved delivery configuration.
The first Product can operate with only its required communication purposes and delivery path.
A future channel/provider can be introduced without changing Product payment semantics.

PH12-02 — Create and Deliver a Transactional Communication¶

Objective

Create one duplicate-safe communication from an authorized Product request and deliver it through the approved Tenant path.

Required behavior

Create communication only from an authorized Product/workflow request.
Resolve the intended recipient and approved communication content.
Use the configured Tenant delivery path/channel.
Retain the payment, purpose, recipient, content/template, delivery-path, and applicable action/expiration context.
Prevent duplicate technical processing from producing uncontrolled duplicate messages.
Normalize external submission/delivery evidence.
Protect sensitive recipient/payment/message data.

Acceptance

Technical replay does not create uncontrolled duplicate customer communications.
Provider/CU-specific delivery behavior does not leak into Product workflow.
Communication records remain associated with the correct payment and recipient.
Sensitive data does not appear in unrestricted logs/telemetry.

PH12-03 — Handle Delivery Failure, Retry, and Expiration¶

Objective

Handle communication delivery uncertainty and failure without confusing communication state with payment state.

Required behavior

Preserve authoritative delivery evidence and external references when available.
Do not claim delivery when only submission/acceptance is known.
Treat ambiguous provider/CU responses conservatively.
Retry only when another send is safe and the communication remains valid.
Bound retry behavior.
Report required-communication failure/expiration to the owning Product.
Allow operations to identify unresolved or failed communication.

Acceptance

A provider timeout does not automatically become definitive non-delivery when submission may have occurred.
Retry cannot generate uncontrolled duplicate messages.
Required communication failure is reported to PH-04/Product rather than interpreted as payment failure by PH-12.
Informational communication failure does not automatically stop the payment.

PH12-04 — Support Actionable Communications Safely¶

Objective

Deliver Product-owned action references without moving action authorization into PH-12.

Required behavior

Carry only an opaque Product/channel action reference.
Do not expose sensitive payment/customer values in action URLs/parameters.
Respect Product-supplied expiration/revocation when determining whether the communication may still be sent/resend.
Do not treat delivery/click evidence as payment authorization or action completion.
Leave authentication, authorization, challenge, and workflow transition to the owning Product/channel capability.

Acceptance

PH-12 cannot authorize a payment/customer action.
Expired/revoked action references are not automatically reissued.
Delivery does not imply action completion.
Sensitive payment data is not exposed through the action reference.

PH12-05 — Generate Product-Required Transaction Documents¶

Objective

Generate secure immutable payment documents when an implemented Product requires them.

Required behavior

Generate only supported Product document types.
Use authoritative payment data and approved content/template.
Retain the Tenant/payment/document relationship and historical content identity.
Store generated documents securely.
Protect retrieval using applicable Tenant/role/relationship authorization.
Create a new/superseding document for a correction rather than editing the original.

Acceptance

A historical document does not silently change because current payment/template data changed.
Unauthorized users cannot retrieve the document.
Corrected documents preserve the original.
Products that do not require transaction documents do not force unused document-generation implementation.

PH12-06 — Provide Communication and Document History¶

Objective

Make material communication/document outcomes available for payment investigation and operations.

Required behavior

Expose communications/documents associated with a payment.
Preserve material delivery outcomes and external references.
Surface failed/expired/unresolved communication requiring attention.
Support explicitly permitted, authorized resend/document regeneration requested through operational tooling, subject to applicable authorization, duplicate-protection, and expiration rules.
Make material communication/document history available to PH-09/PH-13/Data Platform as needed.
Keep reporting consumers independent from synchronous communication delivery.

Acceptance

Operations can understand whether a required communication was submitted, delivered when known, failed, expired, or remains unresolved.
PH-13 can present material communication/document history alongside the payment.
Reporting/data-platform outages do not prevent communication processing.
Ordinary history retrieval does not expose protected message/document content without authorization.

14. Engineering-owned / intentionally non-prescribed detail¶

PH-12 intentionally does not prescribe:

physical schemas for Tenant delivery/content configuration, content/template versioning, communication records, delivery attempts, or transaction documents;
exact Product communication-definition data structure;
immutable-template table/versioning mechanism;
exact delivery-integration/adapter interface;
a generic adapter registry/framework;
exact API/endpoint names;
exact command/event envelopes already governed by shared standards;
request fingerprints or idempotency-record implementation;
provider-facing idempotency-reference format;
delivery-status enum implementation;
exact retry/backoff/circuit/rate-limit behavior;
callback/event-deduplication schema;
transformation/mapping version fields;
content-hash implementation;
secure message/document storage technology;
template editor/content-management system;
exact document rendering technology or format;
operations search/filter schemas;
metrics catalog;
adapter conformance-test framework; or
implementation/build sequence.

Engineering should use established transactional-notification, provider-integration, idempotency, secure-content, and document-generation patterns appropriate to the implemented Product/Tenant needs.

Useful technical approaches explored in earlier PH-12 versions may be retained as non-authoritative Engineering reference material where they remain helpful.

15. Scope boundaries¶

Out of scope¶

Marketing/promotional campaigns.
CRM/lead nurturing.
Generic customer-journey orchestration.
General-purpose communications rules engine.
Enterprise preference center.
Advanced omnichannel optimization.
Provider cost routing/A-B testing.
General document repository/records-management platform.
Electronic-signature platform.
Customer authentication/authorization.
Payment-status determination.
Payment execution.
Risk/policy decisioning.
Reconciliation.
Customer-support ticketing.
Customer balances.
Settlement balances.
Prefunding.
Reserves.
Liquidity.

16. PH-12 completion criteria¶

PH-12 is complete for the initial Product scope when:

the initial Product can identify the transactional communications it requires;
each Tenant can use at least one approved delivery path required by the implemented Product;
communication content is controlled and historically attributable;
communications are created from authorized Product requests rather than inferred by PH-12;
duplicate technical processing cannot produce uncontrolled duplicate communications;
CU/provider-specific delivery mechanics remain outside Product workflow;
communication delivery state remains separate from payment state;
required communication failures/expiration can be returned to PH-04/Product for the appropriate Product response;
actionable communications carry only Product-controlled opaque references and PH-12 does not authorize the underlying action;
sensitive contact/payment/message content is appropriately minimized and protected;
operations can identify failed, expired, or unresolved communications requiring attention;
transaction documents can be generated immutably when an implemented Product requires them, without forcing unused document functionality into Products that do not; and
PH-09/PH-13/Data Platform can consume material communication/document history without becoming synchronous dependencies of communication delivery, and without material communication/document outcomes being lost when those consumers are unavailable.