Skip to content

PH-09 — Payment History and Commercial Records

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

1. Objective

Provide durable, immutable payment history and the commercial records DragonPay needs for operational investigation, auditability, reconciliation support, fees, provider costs, and billing.

PH-09 establishes:

  • a cross-domain history of material payment activity;
  • enough chronology, causation, lineage, and external-evidence references to understand what DragonPay knew and did;
  • preservation of historical events without creating a second authoritative payment database;
  • immutable correction behavior that adds new evidence rather than rewriting history;
  • DragonPay fee and provider-cost records;
  • billing/export records needed to send commercial charges to an external billing/accounting platform;
  • protection against duplicate commercial charges and duplicate billing submissions; and
  • downstream access to historical payment/commercial information for operations, reconciliation, and reporting.

PH-03 through PH-08 remain authoritative for the payment objects and current state they own.

PH-09 does not require a dedicated journal service, separate event store, or particular event-stream architecture. Engineering may use a journal, domain-event projection, append-only history store, event stream, or another proven pattern provided the Product requirements in this epic are satisfied.

PH-09 is also not the analytical warehouse or DragonPay general ledger.

2. Ownership boundaries

Owner Responsibility
PH-03 Canonical Payment Request, Action, Leg, Execution Attempt, Provider Transaction, and current canonical payment state.
PH-04 Product-processing state and payment workflow behavior.
PH-06 Policy Decisions and overrides.
PH-07 Route Decisions.
PH-08 Execution normalization, external handoff/evidence, Connector/Connection execution history.
PH-09 Durable cross-domain payment history plus DragonPay commercial records for fees, provider costs, adjustments, and billing/export.
PH-10 Reconciliation matching, mismatches, and resolution.
PH-11 Case/investigation workflow when applicable.
PH-13 / Data Platform Operational presentation, consolidated views, analytics, and reporting derived from authoritative/history sources.
External billing/accounting platform Invoice issuance, accounts receivable, cash collection, general ledger, revenue recognition, and related accounting state.

PH-09 records what occurred. It does not become the authority for current payment state.

3. Durable payment history

DragonPay must preserve a durable historical record of material payment activity across the components involved in processing a Payment Request.

The history must allow an authorized user or system to understand, where applicable:

  • which Payment Request, Action, Leg, Attempt, or Provider Transaction was affected;
  • the material event or state transition that occurred;
  • when it occurred;
  • which component produced the information;
  • what caused the event or transition;
  • applicable normalized reason/status information;
  • policy/routing/execution references that materially affected the outcome;
  • external transaction/file/network/core/provider references when relevant;
  • whether execution handoff or outcome was uncertain;
  • later evidence that resolved an earlier uncertain condition; and
  • corrections or operational actions that changed the interpretation or handling of the payment.

Recorded historical entries are immutable. Corrections, reversals, or adjustments are represented by new linked entries rather than modifying or deleting the original record.

Later information may supersede an earlier interpretation, but the earlier historical record remains available.

Not a second payment database

PH-09 must not duplicate complete PH-03/04/06/07/08 business objects solely to create history.

Historical records should reference the authoritative objects and retain only the material facts needed for chronology, explanation, audit, reconciliation, and downstream consumption.

A delayed or unavailable PH-09 history mechanism must not change the outcome of a payment already being processed by its authoritative domain services.

4. Material payment history

PH-09 captures material business and operational milestones rather than every internal technical operation.

Examples include:

  • Payment Request creation and material status change;
  • Action/Leg creation and material status change;
  • Execution Attempt and Provider Transaction milestones;
  • Product/customer milestones such as confirmation, claim, expiration, cancellation, or corrective processing;
  • PH-06 policy Decision and override outcomes;
  • PH-07 route resolution/no-route/reroute outcomes;
  • PH-08 external handoff, normalized result, OUTCOME_UNKNOWN, later resolution, and material external-reference evidence;
  • reconciliation mismatch/resolution where applicable;
  • payment-impacting authorized operational actions; and
  • PH-09 commercial adjustments or billing outcomes.

Routine worker retries, health polling, debug logs, traces, and other implementation noise are not Product-required payment history unless they materially affect the payment or are needed to explain an externally meaningful outcome.

The exact event taxonomy and publication mechanism are Engineering decisions.

5. Chronology, causation, and integrity

Historical payment information must preserve enough context to reconstruct the relevant sequence of events without pretending there is a single global ordering across every DragonPay service.

At minimum, the history must support:

  • event occurrence time;
  • recording/availability time when materially different;
  • Tenant/payment identity;
  • source component;
  • correlation across one payment flow;
  • direct causal relationship when available;
  • ordering within a source payment aggregate where required;
  • detection of duplicate/conflicting historical evidence; and
  • references to protected external evidence without copying sensitive raw payloads into general history.

DragonPay must not manufacture missing payment outcomes because a historical record is delayed or absent.

The authoritative domain remains the source of truth for the underlying payment state.

The exact sequence-numbering, hashing, deduplication, event envelope, transactional publication, retention, and storage design follow shared standards and Engineering implementation.

6. Corrections

Historical payment records are not edited in place to make prior information disappear.

When an authorized correction is necessary:

  • the original historical record remains intact;
  • the correction identifies the original record or payment context;
  • the corrected interpretation/value is recorded separately;
  • the reason and authorized actor are retained where applicable; and
  • correction of PH-09 history does not directly rewrite authoritative PH-03/04/06/07/08 state.

If the authoritative payment state itself must change, that change occurs through the domain that owns that state and produces its own resulting history.

7. Fee records

PH-09 maintains DragonPay commercial fee records required to bill or credit a Tenant.

A Fee Record must preserve:

  • Tenant;
  • applicable payment/commercial reference;
  • fee type;
  • amount and currency;
  • pricing/contract basis used when required;
  • the chargeable event or basis when applicable;
  • current commercial status; and
  • adjustment/credit relationship when one record corrects another.

The following Product rules apply:

  • the same chargeable event must not create duplicate fees;
  • a finalized commercial amount is not silently overwritten;
  • credits/corrections create a new commercial record linked to the original;
  • a fee does not represent customer funds or payment settlement;
  • a fee record does not imply invoice payment or revenue recognition.

The exact pricing-engine integration, database schema, uniqueness mechanism, and fee-calculation implementation are not prescribed by PH-09.

8. Provider cost records

DragonPay may record costs charged by a CU, processor, provider, network, or other execution partner.

A Provider Cost Record must preserve enough information to understand:

  • applicable Tenant/payment/execution when relevant;
  • provider/Connection/source;
  • cost type;
  • amount and currency;
  • whether the amount is estimated or confirmed;
  • source evidence/reference when available; and
  • adjustment/correction relationship.

Provider cost evidence must not be duplicated when the same authoritative source record is received more than once.

A later confirmed or corrected cost does not erase the prior estimate/history.

Provider cost is not automatically billed to the Tenant. If a contract passes a cost through to the Tenant, that charge is represented as a Fee Record according to the applicable commercial agreement.

Provider Cost Records do not represent settlement or funds held by DragonPay.

9. Billing and export

DragonPay must be able to prepare billable commercial records and send them to an external billing/accounting platform.

Billing preparation must:

  • group the appropriate billable Fee Records for the applicable Tenant/period/currency;
  • prevent the same Fee Record from being included in more than one finalized billing submission;
  • preserve credits/adjustments;
  • freeze the content of a billing submission once it is finalized for export; and
  • preserve the association to any resulting external billing/invoice reference.

The external billing/accounting system remains authoritative for invoice issuance, accounts receivable, collection, general ledger, and revenue recognition.

Uncertain billing export

Billing export has the same fundamental duplicate-risk problem as payment execution.

If DragonPay cannot determine whether an external billing submission was accepted:

  • the export remains unresolved;
  • DragonPay must not blindly submit a second invoice/export request;
  • DragonPay must use the same stable external export identity when resolving the prior submission;
  • resolution may use status inquiry, asynchronous acknowledgement, reconciliation, or other authoritative evidence; and
  • a new export attempt is permitted only when authoritative evidence establishes that the prior submission was not accepted, or the external contract otherwise provides a safe idempotent retry guarantee.

The exact billing-batch state machine, export-attempt table, API names, and query/event mechanism are Engineering/integration decisions.

10. Downstream operational and analytical use

Authorized downstream consumers must be able to obtain:

  • a material payment timeline for one Payment Request;
  • relevant commercial records for a payment or Tenant;
  • historical policy/routing/execution references needed for support;
  • unknown-outcome and later-resolution history;
  • correction history;
  • reconciliation-related history where available; and
  • billing/export status needed for operations.

PH-13 may combine authoritative current payment state with PH-09 history for operational presentation.

The Data Platform may consume PH-09 and other authoritative sources for analytical reporting.

Long-running analytics, aggregates, BI datasets, model-training datasets, and warehouse/lakehouse schemas are not PH-09 responsibilities.

Downstream reporting may be delayed or rebuilt without changing payment or commercial source records.

11. Product stories

PH09-01 — Preserve Material Payment History

Objective

Maintain durable cross-domain history of material payment activity without creating a second authoritative payment database.

Required behavior

  • Record material payment events produced by PH-03 through PH-08 and other approved domains.
  • Retain payment/domain references needed to correlate the historical event.
  • Preserve event time, source, causal/correlation context, and material reason/evidence.
  • Keep historical records immutable.
  • Handle repeated delivery of the same logical historical event without creating uncontrolled duplicates.
  • Keep payment processing independent from the availability of the history/reporting mechanism.

Acceptance

  • A payment can be investigated across Product, policy, routing, and execution milestones.
  • Duplicate delivery does not produce conflicting duplicate history.
  • A history-system delay does not roll back or change a payment outcome.
  • PH-09 does not become the source of current PH-03/04/06/07/08 state.

PH09-02 — Preserve Execution and External Evidence Lineage

Objective

Retain enough execution history to understand external payment behavior and resolve operational/reconciliation questions.

Required behavior

  • Preserve material PH-08 execution outcomes and external references.
  • Preserve whether handoff/outcome was known or uncertain.
  • Preserve later evidence that resolves OUTCOME_UNKNOWN.
  • Retain references to protected external evidence rather than copying sensitive raw content into general payment history.
  • Preserve enough integration/version context to diagnose materially different external interpretation when needed.

Acceptance

  • Operations can identify the external execution reference/evidence associated with an Attempt.
  • OUTCOME_UNKNOWN and its later authoritative resolution are both visible.
  • Sensitive external payloads are not exposed through ordinary payment-history retrieval.
  • Historical execution interpretation remains understandable after the Connector/integration later changes.

PH09-03 — Record Corrections Without Rewriting History

Objective

Allow authorized corrections while preserving the original historical record.

Required behavior

  • Create a new correction record/event rather than modifying or deleting the original.
  • Identify the affected historical record/payment context.
  • Retain correction reason and actor/approval information when required.
  • Present original and correction together for investigation.
  • Do not use PH-09 correction as a shortcut to modify authoritative payment state.

Acceptance

  • The original historical record remains intact.
  • The corrected interpretation is separately visible and auditable.
  • Authoritative payment state changes only through the domain that owns that state.

PH09-04 — Record Fees and Provider Costs

Objective

Maintain the commercial records DragonPay needs for Tenant billing and provider-cost visibility.

Required behavior

  • Create Fee Records for chargeable DragonPay fees.
  • Prevent duplicate fees from the same chargeable basis.
  • Record Provider Cost Records when provider/CU/network cost evidence is available.
  • Preserve estimated versus confirmed provider cost when relevant.
  • Correct fees/costs through linked adjustments rather than overwriting prior records.
  • Keep provider costs separate from Tenant fees unless the commercial agreement explicitly creates a pass-through Fee Record.

Acceptance

  • Duplicate source evidence does not create duplicate commercial charges/costs.
  • Original fee/cost history remains visible after correction.
  • Fee/provider-cost records do not create customer-funds or settlement balances.
  • Provider cost alone does not create a Tenant billing charge.

PH09-05 — Prepare and Export Billing Records Safely

Objective

Prepare DragonPay fees for external billing without creating duplicate billing submissions.

Required behavior

  • Group eligible Fee Records by appropriate Tenant/billing scope.
  • Prevent duplicate inclusion of the same Fee Record in finalized billing.
  • Preserve finalized billing content and later adjustments separately.
  • Use a stable identity for the external billing submission.
  • Preserve resulting external billing/invoice references when available.
  • Treat an uncertain external export outcome as unresolved rather than blindly submitting again.
  • Permit another submission only when authoritative evidence or the external idempotency contract makes it safe.

Acceptance

  • The same Fee Record is not billed twice.
  • Finalized billing content is not silently changed after export begins.
  • Unknown export outcome cannot cause an uncontrolled duplicate invoice request.
  • Later authoritative evidence can resolve the existing export history.
  • The external accounting platform remains authoritative for invoice/receivable/accounting state.

PH09-06 — Provide Payment and Commercial History to Downstream Consumers

Objective

Make durable history available to operations, reconciliation, and reporting without turning PH-09 into the analytical warehouse.

Required behavior

  • Provide payment-scoped history suitable for operational investigation.
  • Provide applicable commercial/billing history.
  • Support PH-10/PH-11/PH-13 consumption where those capabilities require history.
  • Allow analytical/data-platform consumers to ingest/rebuild derived views.
  • Preserve Tenant authorization and protection of sensitive evidence.

Acceptance

  • PH-13 can combine current payment state with durable payment history.
  • PH-10 can consume relevant historical/commercial evidence without PH-09 owning reconciliation.
  • Analytical reporting can lag or rebuild without affecting operational payment state.
  • General historical retrieval does not expose protected raw execution evidence.

12. Engineering-owned / intentionally non-prescribed detail

PH-09 intentionally does not prescribe:

  • a dedicated journal microservice or database;
  • an event-sourced payment architecture;
  • physical history-record, fee, provider-cost, and billing table schemas;
  • exact domain-event taxonomy;
  • exact event-envelope/payload fields beyond shared standards;
  • source sequence implementation;
  • payload hashes or conflict-detection implementation;
  • transactional-outbox implementation;
  • event-broker/stream technology;
  • replay implementation;
  • CDC versus event publication for the Data Platform;
  • exact correction API/event names;
  • pricing-engine architecture;
  • exact fee/provider-cost idempotency keys;
  • billing-batch/line-item/export-attempt schemas;
  • exact billing state machine;
  • exact billing status-inquiry/event interfaces;
  • operations-search filters;
  • metrics catalogs;
  • warehouse/lakehouse implementation; or
  • implementation/build sequence.

Engineering should use established append-only history, event publication, commercial-record, idempotency, and external-export safety patterns that satisfy this epic.

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

13. Scope boundaries

Out of scope

  • A second canonical payment database.
  • Reconstructing PH-03 current state exclusively by replaying PH-09 history.
  • Payment workflow, policy evaluation, routing, or execution.
  • Reconciliation matching/resolution.
  • Warehouse/lakehouse schemas and BI implementation.
  • General ledger.
  • Accounts receivable/payable.
  • Revenue recognition.
  • Tax accounting.
  • Invoice collection.
  • Customer/CU balances.
  • Stored value.
  • Settlement balances.
  • Prefunding.
  • Reserves.
  • Liquidity.
  • Funds-in-transit accounting.
  • Raw external request/response/file storage in ordinary history.

14. PH-09 completion criteria

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

  • material payment activity across the implemented Product lifecycle is durably available for operational history;
  • historical payment records remain immutable and corrections preserve the original record;
  • payment history references authoritative PH-03 through PH-08 records rather than duplicating them as a second source of truth;
  • payment processing does not depend synchronously on PH-09 history/reporting availability;
  • external execution uncertainty and later authoritative resolution remain visible historically;
  • DragonPay Fee Records can be created without duplicate chargeable records and corrected through immutable adjustments;
  • provider costs can be recorded without creating settlement/accounting balances or automatically billing the Tenant;
  • billing records prevent duplicate fee inclusion;
  • an uncertain external billing export cannot cause blind duplicate submission;
  • PH-13/PH-10 and downstream analytical consumers can use the resulting history without making PH-09 the warehouse or reconciliation engine; and
  • Engineering remains free to implement these requirements using a dedicated journal, event projection, append-only history store, stream, or another proven architecture.