PH-13 — Payment Operations and Reporting¶

Payment Hub · Working Draft · Revised Working Copy v7 · Updated September 5, 2026

1. Objective¶

Provide the read-side capabilities required to operate, support, report on, and analyze DragonPay Payment Products without making read/reporting data authoritative for payment processing.

PH-13 establishes:

authorized operational payment search and queues;
a consolidated payment detail view across the relevant Payment Hub capabilities;
visibility into payment exceptions, reconciliation, Cases, communications, and execution health;
Tenant- and DragonPay-facing reports and metrics required by implemented Products;
controlled export of approved reporting data;
explicit freshness/lineage when displayed data may lag authoritative state;
support for multi-leg payments and multiple execution attempts in operational/reporting views; and
reporting/read models that may be rebuilt, backfilled, or replaced without changing payment outcomes.

PH-13 does not require a specific operational projection database, reporting database, warehouse/lakehouse, search engine, semantic layer, or BI product.

Engineering may use projections, reporting tables, composed reads, search indexes, warehouse/lakehouse technology, or a combination of proven approaches as long as the Product behavior in this epic is preserved.

Authoritative PH domains remain the source of truth for payment state and behavior.

2. Ownership boundaries¶

Owner	Responsibility
PH-01	Tenant/user authorization and privileged access.
PH-02	Tenant Product/configuration identity.
PH-03	Canonical Payment Request, Action, Leg, Execution Attempt, Provider Transaction, and current payment state.
PH-04	Product workflow/current processing state.
PH-05	Party/Payment Instrument references and approved masked display data.
PH-06	Policy Decisions and overrides.
PH-07	Route Decisions and selected Route Capability/Connection.
PH-08	Execution evidence, external references, handoff certainty, and Connection execution availability.
PH-09	Durable payment/commercial history, Fee Records, Provider Cost Records, and billing-submission history.
PH-10	Reconciliation results/history.
PH-11	Operational Cases and corrective-action history.
PH-12	Transactional communication/document status and history.
PH-13	Operational presentation/search, reporting/metrics, controlled exports, and derived read/reporting data required to support them.

PH-13 does not directly modify records owned by another epic.

When an operations UI exposes a payment-affecting action, it invokes the owning domain capability, which independently validates the current authoritative state.

3. Operational payment search and queues¶

Authorized DragonPay/CU users must be able to find payments and identify payment-related work requiring attention.

Operational search should support the identifiers and filters useful for the implemented Products, which may include:

Payment Request/Action/Leg/Attempt/Provider Transaction references;
approved external transaction/reference identifiers;
Tenant and Product;
date/time range;
amount/currency;
current payment/Product status;
Route Type/Connection;
reconciliation status;
open Case state;
required communication status;
approved masked Party/customer display information; and
other Product-specific operational fields when needed.

Operational queues may include conditions such as:

active/in-process payments;
OUTCOME_UNKNOWN;
failed/rejected payments;
corrective/returned payments;
reconciliation mismatches or overdue reconciliation;
open/overdue Cases;
required communication failures; and
stale/incomplete read data.

Only queues needed by implemented Product/operations workflows are required initially.

Search and queue data is read-only.

4. Payment detail¶

Authorized users must be able to view a consolidated operational picture of one Payment Request.

The view may include, as applicable:

Payment Request/Action/Leg hierarchy and current status;
Product/workflow state and current wait/next step;
approved Party/Payment Instrument display;
policy Decision and override information;
Route Decision and selected execution path;
Execution Attempts, Provider Transactions, handoff certainty, and external references;
durable payment history from PH-09;
reconciliation status/history;
Case status/history;
transactional communication/document status; and
Fee/provider-cost/billing information when the user is authorized.

Current authoritative state and derived/historical information must remain distinguishable.

If one source is temporarily unavailable or the read-side data is stale, PH-13 must not fabricate missing/current state.

The UI/read API may return available information with an explicit partial/stale indication where appropriate.

PH-13 does not need to persist a second full copy of the payment graph solely to render Payment Detail.

5. Multi-leg and execution visibility¶

Operational and reporting views must preserve the canonical payment hierarchy rather than collapsing a Payment Request into a misleading single movement/execution.

DragonPay must be able to distinguish, where applicable:

Funding Leg;
Payout Leg;
Return/Refund/Reversal or other corrective Leg;
multiple Execution Attempts for one Leg; and
separate Provider Transactions/external references.

A completed Funding Leg must not make a later Payout appear completed.

A later retry/new Attempt must not erase the history/outcome of an earlier Attempt.

Route Type, external network/provider, Route Capability, and Connection should remain distinguishable when relevant to investigation/reporting.

6. Attention and execution health¶

PH-13 may derive operational attention indicators from authoritative payment/exception conditions to help users find work.

Examples include:

OUTCOME_UNKNOWN;
material reconciliation exception;
open/overdue Case;
required communication failure;
payment failure/rejection;
unresolved corrective processing; or
stale/incomplete operational data.

Attention is a presentation/read-side aid, not another workflow or Case system.

The source condition remains authoritative in its owning epic.

Connection/execution health¶

PH-13 may present Connection/integration availability and execution telemetry supplied by PH-08 and standard observability tooling.

PH-13 does not:

calculate a competing Connection-health model;
determine route eligibility;
control circuit breakers/admission;
execute payments; or
infer payment outcomes from infrastructure telemetry.

7. Reporting and analytics¶

DragonPay must support controlled reporting needed by implemented Products, participating Tenants, operations, and commercial management.

Initial reporting may include:

payment count/value and status/outcome;
payment completion/failure/rejection/cancellation/return trends;
Product processing duration;
movement/Leg outcomes;
execution/Attempt outcomes and unknown-outcome rate;
route/Connection/integration performance;
policy Decision/review/override outcomes;
reconciliation outcomes;
Case volumes/aging;
required communication outcomes;
fees/provider costs/billing information when authorized; and
Product-specific measures required by an implemented Product.

Reporting must preserve enough Product/payment hierarchy to analyze multi-leg payments and retries correctly.

Controlled definitions¶

Metrics and reports whose meaning is presented externally or used operationally must have controlled, stable definitions.

A material change in how a metric/report is calculated or interpreted must be traceable rather than silently changing historical meaning.

Product/approved reporting definitions own the business meaning of a metric or report. The exact metric-definition schema, semantic layer, report-code registry, or versioning mechanism used to implement and enforce that meaning is Engineering's responsibility.

Product-specific reporting¶

A Product may expose additional Product-specific reporting fields without requiring every such field to become part of the shared canonical payment model.

Product-specific reporting must remain linked to the applicable Payment Request and Tenant/Product context.

8. Tenant reports and access control¶

Tenant-facing reports must be scoped to the authorized Tenant and role.

DragonPay privileged/cross-Tenant reporting requires explicit PH-01 authorization.

Reporting must:

expose only approved fields;
mask/restrict sensitive Party, Payment Instrument, provider, commercial, and evidence data;
enforce Tenant isolation before returning results;
use clearly defined date/time basis where it materially affects results;
identify reporting freshness when data may lag; and
avoid exposing unrestricted arbitrary queries against payment data.

A future configurable reporting/BI experience may be added later.

The initial Product does not require arbitrary SQL, user-authored formulas, or a drag-and-drop enterprise BI platform.

9. Controlled exports¶

Authorized users must be able to export approved reporting datasets when an implemented operational/Tenant requirement needs it.

Exports must:

enforce Tenant/role scope and approved fields;
apply applicable masking/restrictions;
use bounded date/volume limits appropriate to the implementation;
preserve enough request/audit context to identify what was exported and by whom;
protect generated files/artifacts;
expire or otherwise control access to generated artifacts; and
prevent technical retry from creating uncontrolled duplicate logical export work/artifacts.

An explicit regeneration may create a new export when requested/authorized.

The exact export tracking/execution model, asynchronous job system, file format, storage technology, and artifact-access mechanism are Engineering decisions.

10. Freshness, lineage, and data quality¶

PH-13 read/reporting data may be asynchronous and may lag authoritative payment state.

Where stale or incomplete information could mislead an operator or Tenant, PH-13 must expose appropriate freshness/quality context.

Depending on the read/reporting implementation, this may include:

data_as_of;
last refresh/projected time;
source/version lineage;
incomplete/backfill state;
reporting-load failures; or
another clear freshness indicator.

Derived read/reporting data must handle repeated, delayed, or out-of-order source updates without silently regressing to older known state.

Data-quality problems must be visible when material, but must not change authoritative payment records.

PH-13 read, reporting, export, and rebuild activity must not become a dependency of authoritative payment processing or materially degrade its availability or execution. Authoritative payment execution must not wait on PH-13.

11. Rebuild and backfill¶

Derived operational/read/reporting data must be recoverable.

DragonPay must be able to rebuild or backfill read/reporting data from authoritative payment records and durable history as needed.

Rebuild/backfill must:

not modify authoritative payment state;
produce the same reporting semantics as normal ingestion for the same authoritative source data;
make materially incomplete/failed rebuild scope visible; and
coexist safely with normal payment processing.

The exact rebuild/backfill tracking/execution model, locking/lease behavior, watermark strategy, event replay, backfill command, or infrastructure is Engineering responsibility.

12. Product stories¶

PH13-01 — Search Payments and Operational Queues¶

Objective

Allow authorized operations/CU users to find payments and identify payment-related work requiring attention.

Required behavior

Search payments using approved identifiers and operational filters.
Enforce Tenant/role scope and masking.
Provide queues for the exception/processing conditions required by implemented Products.
Include freshness/partial-state indication when applicable.
Keep search/queue behavior read-only.

Acceptance

An authorized user can locate a payment using supported operational identifiers.
Cross-Tenant access is prohibited unless explicitly authorized.
Sensitive fields remain masked/restricted.
Stale/incomplete derived data is not presented as unquestionably current.
Searching does not change payment state.

PH13-02 — Present Consolidated Payment Detail¶

Objective

Provide one support-oriented view of the current payment and its material history.

Required behavior

Present current information from the authoritative PH domains needed for the supported operational view.
Include material PH-09 payment history.
Preserve separate Funding/Payout/Return/other Legs and their Execution Attempts.
Show related reconciliation, Case, communication/document, and commercial information when applicable/authorized.
Distinguish current authoritative state from historical/derived information.
Return controlled partial/stale indications rather than fabricating unavailable data.

Acceptance

Operations can understand the current payment and the significant events leading to it.
Multiple Legs/Attempts remain distinct.
PH-13 does not become a second canonical payment store.
Missing/unavailable source data is identified rather than invented.

PH13-03 — Surface Operational Attention and Health¶

Objective

Help operations identify payment/integration conditions requiring attention without creating another workflow or health authority.

Required behavior

Derive attention indicators from authoritative exception/payment conditions.
Clear derived attention when the owning condition is resolved.
Present PH-08/observability Connection and integration health information needed for operations.
Keep PH-11 authoritative for human Cases.
Keep PH-07/PH-08 authoritative for routing/execution availability.

Acceptance

OUTCOME_UNKNOWN, reconciliation exception, overdue Case, or required communication failure can be surfaced operationally.
Clearing the source condition removes the corresponding derived attention on refresh.
PH-13 does not decide route eligibility or payment execution.
Integration health presentation does not create a second PH-08 health model.

PH13-04 — Provide Controlled Metrics and Reports¶

Objective

Provide Tenant/DragonPay reporting required by implemented Payment Products.

Required behavior

Support controlled reports/metrics over payment, movement, execution, exception, communication, and commercial information where required.
Preserve the canonical hierarchy so multi-leg payments and multiple Attempts are counted/analyzed correctly.
Use stable, traceable report/metric definitions.
Support Product-specific reporting fields without expanding the shared canonical payment model unnecessarily.
Enforce Tenant/role/data restrictions.
Identify reporting freshness.

Acceptance

A Tenant can retrieve its authorized implemented reports without seeing another Tenant's data.
Multi-leg payments and retries are not incorrectly collapsed into one execution record.
Material definition changes are traceable.
Reporting lag does not change payment processing.
Unsupported arbitrary SQL/user-defined formulas are not required for the initial Product.

PH13-05 — Provide Controlled Reporting Exports¶

Objective

Allow authorized export of approved reporting information without exposing unrestricted payment data.

Required behavior

Export only approved fields/datasets for the caller's authorized scope.
Apply required masking/data restrictions.
Protect generated artifacts and control their availability.
Preserve export request/completion audit evidence.
Make technical retry duplicate-safe.
Treat an explicit regeneration as a new authorized export.

Acceptance

Unauthorized/cross-Tenant fields are not exported.
Sensitive raw provider/payment evidence is excluded unless explicitly authorized for that export use.
Technical replay does not create uncontrolled duplicate logical exports.
Generated artifact access is controlled.
Regeneration is explicit rather than an accidental side effect of retry.

PH13-06 — Preserve Read/Reporting Freshness and Recoverability¶

Objective

Ensure derived operational/reporting information remains understandable and recoverable without becoming authoritative payment state.

Required behavior

Expose meaningful freshness/partial-data information where stale data could mislead users.
Prevent duplicate/out-of-order updates from silently regressing derived views.
Make material reporting/load/data-quality failures visible.
Support rebuild/backfill from authoritative records/history.
Never write rebuild/reporting corrections back into authoritative payment domains.

Acceptance

Users can distinguish stale/incomplete reporting from authoritative current payment state.
Reporting/read-side outages do not block normal payment execution.
Rebuild/backfill can restore derived data without changing the underlying payment.
Incomplete rebuild/reporting ranges are not silently presented as complete.

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

PH-13 intentionally does not prescribe:

a separate Operational Read Model database;
a separate Reporting Data Store;
a specific warehouse/lakehouse/search/BI technology;
physical structures used to support operational search, queues, and consolidated payment views;
physical structures used to preserve payment, movement, and execution reporting relationships;
formal dimension-table design;
source-event ingestion pipeline architecture;
watermark/version implementation;
exact source fan-out versus projection behavior for Payment Detail;
fixed attention-code taxonomy;
storage/registry implementation for metric and report definitions;
exact report/metric formulas not yet required by a Product;
physical tracking/persistence used for exports;
physical tracking/persistence used for rebuild and backfill processing;
asynchronous job platform;
artifact-storage technology;
exact API/endpoint names;
exact paging/search implementation;
event/outbox/CDC mechanisms;
exact data-quality rules/catalog;
BI semantic layer;
operations UI technology; or
implementation/build sequence.

Engineering should use established operational-read, reporting, search, analytics, export, data-lineage, and rebuild patterns appropriate to the implemented Product/Tenant needs.

14. Scope boundaries¶

Out of scope¶

Authoritative payment/workflow/policy/routing/execution/reconciliation/Case/communication/commercial state.
Direct payment mutation.
A second canonical payment database.
A required dedicated warehouse/lakehouse before scale/tooling justifies it.
General-purpose enterprise BI.
Arbitrary SQL/report builder in the initial Product.
Customer-funds ledger.
Settlement balances.
Prefunding.
Reserves.
Liquidity.
Funds-in-transit accounting.
Unrestricted export/retention of sensitive payment/Party/provider evidence.

15. PH-13 completion criteria¶

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

authorized users can find supported payments and operational work through appropriate search/queues;
operations can view a consolidated payment detail containing current authoritative information and material payment history;
Funding/Payout/Return/other Legs and multiple Execution Attempts remain independently understandable;
material payment exception/attention conditions and Connection/integration health can be surfaced without PH-13 becoming another workflow/routing/health authority;
implemented Tenant/DragonPay reports and metrics can be produced with Tenant/role/data restrictions;
reporting definitions that materially affect interpretation are controlled/traceable;
authorized reporting exports can be generated without exposing unrestricted data or creating uncontrolled duplicates;
stale/incomplete derived data is visibly distinguishable from authoritative current state;
PH-13 failure, lag, or workload must not block or materially degrade normal payment execution;
derived operational/reporting data can be rebuilt/backfilled without changing authoritative payment records;
Product-specific reporting can expand without forcing every field into the shared canonical payment model; and
Engineering remains free to choose projections, relational reporting tables, search indexes, warehouse/lakehouse technology, BI tooling, or other proven read/reporting architecture as actual scale and Product needs justify it.