PH-10 — Payment Reconciliation¶

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

1. Objective¶

Provide an asynchronous reconciliation capability that determines whether DragonPay's payment/execution records agree with the authoritative external evidence available for the payment path that was actually executed.

PH-10 establishes:

reconciliation of implemented payment execution paths using authoritative DragonPay and external evidence;
strong-identifier matching rather than unsafe fuzzy transaction matching;
comparison of material payment facts such as amount, currency, direction, execution status, and expected external references;
explicit distinction between evidence that is still legitimately pending and a material mismatch;
durable reconciliation results that preserve prior evaluations as new evidence arrives;
support for investigating OUTCOME_UNKNOWN without treating uncertainty as payment failure or authorizing retry;
escalation of material unresolved discrepancies to PH-11 when human investigation is required; and
operational/reporting access to reconciliation status and history.

PH-10 is a control around payment execution, not another transaction-processing layer.

It does not participate in the normal synchronous payment execution path, independently execute provider transactions, maintain a second copy of PH-03/PH-08 payment state, or automatically correct payment outcomes.

The exact reconciliation service architecture, matching-handler implementation, scheduling mechanism, persistence schema, severity taxonomy, event/publication mechanism, and operations query implementation are Engineering decisions provided the requirements in this epic are preserved.

2. Ownership boundaries¶

Owner	Responsibility
PH-03	Canonical Payment Request, Action, Leg, Execution Attempt, Provider Transaction, and current payment state.
PH-08	External execution, normalized CU/provider evidence, status inquiry, external references, and secure raw-evidence references.
PH-09	Durable payment/commercial history used for operational chronology where helpful.
PH-10	Compare authoritative DragonPay execution records to applicable external evidence and retain reconciliation results.
PH-04	Determine Product progression, corrective action, retry, or rerouting using authoritative payment/execution evidence.
PH-11	Human investigation/case workflow for material unresolved discrepancies.
PH-13 / Data Platform	Operational presentation and analytical reporting of reconciliation outcomes.

PH-10 provides reconciliation evidence. It does not own payment outcome.

3. Reconciliation scope¶

Reconciliation is performed only for execution paths implemented by supported Products and CU/provider integrations.

Each executed Payment Leg is reconciled independently.

For example, in a multi-leg Product:

Funding may reconcile independently from Payout;
a later Return or other corrective Leg has its own reconciliation;
a matched Funding Leg does not imply that a later Payout succeeded; and
uncertainty on one Leg must not be resolved using unrelated evidence from another Leg.

The reconciliation behavior for a route/integration must reflect the authoritative evidence that actually exists for that execution path.

PH-10 does not require a generalized reconciliation-rules platform for future payment types.

4. Authoritative evidence¶

PH-10 evaluates existing DragonPay operational records and external evidence captured or made available through the owning integration/execution capabilities.

Applicable evidence may include:

PH-03 Payment Leg, Execution Attempt, and Provider Transaction;
PH-08 normalized execution result;
external transaction/provider/core/network references;
execution handoff certainty;
file/entry/trace references for file-based execution when applicable;
acknowledgements, returns, reversals, or later external status;
PH-09 historical payment evidence where chronology is useful; and
other strong integration-specific evidence required by the implemented payment path.

PH-10 does not build a separate provider-ingestion mechanism; acquisition and normalization of external evidence is owned by PH-08 or the applicable integration.

PH-10 may request PH-08 to perform a supported status inquiry when additional authoritative external evidence is needed.

5. Matching rules¶

Reconciliation should prefer strong identifiers that directly connect DragonPay's execution to the external system.

Examples include:

provider/core/network transaction reference;
PH-03 Provider Transaction external identity;
external idempotency/end-to-end reference;
CU core posting reference;
ACH trace or processor transaction identifier;
immutable file/entry reference;
another integration-defined authoritative transaction identifier.

The initial implementation must not automatically declare two transactions equivalent based only on fuzzy characteristics such as:

similar amount;
approximate date/time;
Party/customer name;
masked account value; or
another ambiguous descriptive attribute.

Such information may assist human investigation but cannot automatically establish authoritative reconciliation.

When multiple external records could match one DragonPay execution and no authoritative discriminator exists, the result is MISMATCHED rather than selecting one arbitrarily.

6. Material comparisons¶

The exact checks vary by execution path, but PH-10 must be able to evaluate the material facts required for the implemented integrations.

These may include:

whether an external transaction exists when one is expected;
whether an external transaction exists when PH-08 has authoritative evidence that no handoff occurred;
amount;
currency/asset;
debit/credit or movement direction;
normalized external execution status;
uniqueness of the external transaction/reference;
required posting/acknowledgement evidence;
return/reversal/corrective references; and
transformation/integration lineage when needed to interpret historical evidence.

Amount and currency are exact unless a supported Product explicitly defines conversion/tolerance behavior.

PH-10 does not invent external payment facts that are not available from authoritative evidence.

7. Reconciliation results¶

Each reconciliation evaluation produces one durable, immutable reconciliation result that records the comparison outcome and supporting evidence.

The initial result concepts are:

MATCHED — the material DragonPay and external evidence available for the execution agree.
PENDING — expected authoritative evidence is incomplete but is still legitimately expected.
MISMATCHED — material authoritative evidence conflicts, is unexpectedly present, is missing beyond its expected availability, or cannot be correlated safely.
ERROR — DragonPay could not perform a valid reconciliation evaluation because required reconciliation inputs or processing failed.
NOT_APPLICABLE — the evaluated path/object does not require reconciliation.

A later evaluation may establish that a prior PENDING, MISMATCHED, or unresolved condition has been resolved. A reconciliation discrepancy may also be closed by an authoritative PH-11 resolution rather than new external evidence; PH-10 records that closure as a new reconciliation result, and the prior result is not rewritten.

Prior results remain available; they are not rewritten to make the historical discrepancy disappear.

A reconciliation result must retain enough evidence to understand:

the Tenant/payment/Leg/execution being reconciled;
the result;
the material reason/findings;
the external evidence/references considered;
when the evaluation occurred;
what prior reconciliation result it follows when applicable; and
applicable PH-11 Case reference when escalated.

Material reconciliation outcomes and resolution evidence managed by PH-10 must be available to PH-09 for durable Payment History and to PH-13/Data Platform for operational and analytical consumption. The publication/transport mechanism is an Engineering/shared-standard concern.

The exact database fields, reason-code taxonomy, and result-linking implementation are Engineering decisions.

8. Delayed evidence and re-evaluation¶

External evidence may legitimately arrive after DragonPay execution.

Examples include:

CU/core posting evidence;
provider acknowledgement;
ACH trace assignment;
file processing acknowledgement;
payment-network status;
return/reversal evidence.

Expected delay must not immediately be treated as a mismatch.

When evidence is still within the reasonable expected availability window, PH-10 records PENDING and reevaluates later as needed.

Reevaluation must be bounded. Reconciliation must not remain in an endless automated polling loop.

When:

expected evidence arrives, the new result reflects it;
expected evidence fails to arrive after the applicable evidence horizon, the condition becomes actionable;
definitive contradictory evidence appears, PH-10 does not wait merely to exhaust a timer/retry schedule.

The exact evidence windows, timer implementation, retry cadence, and scheduling infrastructure are Engineering/integration configuration decisions based on the actual execution path.

9. OUTCOME_UNKNOWN support¶

PH-10 may assist investigation of a PH-03 Execution Attempt whose external outcome remains OUTCOME_UNKNOWN.

Reconciliation may determine that available authoritative evidence indicates:

the external transaction completed;
the external transaction exists and remains pending;
the transaction was definitively rejected;
the external authority establishes that the transaction was not accepted/not found; or
the outcome remains unknown.

Absence of evidence is not automatically authoritative proof that no external transaction exists.

PH-10 does not:

mark an uncertain payment as failed merely because evidence is absent;
create a new Execution Attempt;
select another route;
authorize resubmission; or
authorize a conflicting corrective movement.

PH-04/PH-08 use the resulting authoritative evidence and their own payment-safety rules to determine whether any new execution action is allowed.

10. Material mismatch escalation¶

A reconciliation discrepancy that can be resolved automatically through later authoritative evidence does not require immediate human case management merely because evidence is delayed.

A material definitive mismatch or unresolved condition requiring investigation must be surfaced to PH-11.

Examples may include:

unexpected external payment after authoritative non-handoff;
duplicate external transaction;
material amount/currency/direction discrepancy;
persistent required external evidence absence;
conflicting external transaction references;
unresolved execution uncertainty that exceeds the applicable operational tolerance; or
reconciliation processing failure that prevents a required control from completing.

The exact severity levels and which mismatch categories automatically open/update a PH-11 Case are configurable Product/Operations policy rather than a fixed PH-10 severity taxonomy; configuration may tune categories and thresholds but must not result in a material definitive mismatch or a reconciliation processing failure being neither escalated to PH-11 nor operationally surfaced.

Repeated evidence about the same unresolved condition should not create uncontrolled duplicate cases.

PH-11 owns human investigation, assignment, resolution, and any resulting operator workflow.

PH-10 retains the reconciliation history regardless of the Case outcome.

11. Examples¶

On-us / CU core execution¶

For an executed CU/core movement, reconciliation may:

match the PH-03/PH-08 execution to the authoritative CU/core posting reference;
compare amount, currency, direction, and normalized outcome;
verify required debit/credit posting evidence when the integration exposes it; and
detect an unexpected external posting after PH-08 had authoritative NOT_HANDED_OFF evidence.

Expected posting evidence that is not yet available may remain PENDING until its applicable evidence horizon.

ACH execution¶

For an ACH movement, reconciliation may use:

provider/processor transaction reference;
ACH trace;
immutable file/entry reference;
external idempotency/end-to-end reference;
acknowledgement/status/return evidence.

PH-10 does not create its own ACH file/batch/entry domain.

File/batch details remain execution/integration evidence owned by PH-08 and the concrete integration.

Future execution paths¶

FedNow, RTP, card, cross-border, stablecoin, or other execution paths add only the reconciliation behavior their actual authoritative external evidence requires.

They do not require redesign of the PH-10 reconciliation model.

12. Product stories¶

PH10-01 — Reconcile an Executed Payment Leg¶

Objective

Determine whether one executed Payment Leg agrees with the authoritative external evidence available for its execution path.

Required behavior

Reconcile one Payment Leg/execution scope independently.
Use PH-03/PH-08 authoritative payment/execution records and applicable external evidence.
Match using strong transaction/execution identifiers.
Compare the material facts required by the implemented execution path.
Do not automatically match ambiguous records using fuzzy characteristics.
Produce one durable reconciliation result without changing payment state.
Handle repeated processing of the same logical reconciliation trigger idempotently.

Acceptance

Matching authoritative evidence produces MATCHED.
Ambiguous external correlation is not automatically treated as matched.
Reconciliation of one Leg does not infer the outcome of another Leg.
PH-10 creates no PH-03/PH-08 payment state change.

PH10-02 — Handle Delayed and Missing Evidence¶

Objective

Distinguish expected external reporting delay from a genuine reconciliation discrepancy.

Required behavior

Return PENDING while required evidence is legitimately expected but not yet available.
Reevaluate pending reconciliation when additional evidence is expected.
Stop automated reevaluation when evidence resolves the condition, a definitive mismatch exists, or the applicable evidence horizon is exceeded.
Preserve each material evaluation rather than rewriting the prior result.
Do not use automated waiting to delay response to already-definitive contradictory evidence.

Acceptance

Normal provider/CU reporting delay does not immediately become a mismatch.
Later evidence can move the current reconciliation view from PENDING to MATCHED or MISMATCHED while preserving the earlier result.
Reconciliation does not poll indefinitely.
Definitive contradictory evidence becomes actionable without waiting for an arbitrary retry count.

PH10-03 — Reconcile Initial CU/Core and File-Based Payment Evidence¶

Objective

Support the authoritative evidence patterns required by the first implemented CU/payment integrations without building a generalized reconciliation engine.

Required behavior

Support CU/core execution evidence when required by the implemented integration.
Support file-based payment evidence when required by the implemented integration.
For file-based execution, use normalized execution/file/entry/trace/acknowledgement evidence supplied by PH-08/the integration rather than recreating a batch domain.
Keep integration-specific comparison behavior behind the reconciliation implementation for that execution path.
Add future execution paths only when the corresponding Product/integration is implemented.

Acceptance

On-us/core execution can be reconciled against the authoritative evidence actually provided by the CU integration.
File-based execution such as ACH can be reconciled using its available strong references/evidence.
PH-10 does not create a duplicate payment-file/batch/entry model.
Unimplemented future payment routes require no PH-10 implementation.

PH10-04 — Assist Resolution of Unknown Execution Outcomes¶

Objective

Use later authoritative evidence to help resolve an OUTCOME_UNKNOWN execution without authorizing duplicate payment movement.

Required behavior

Evaluate all applicable authoritative evidence for the affected execution.
Distinguish transaction found/completed, transaction found/pending, definitive rejection/not-accepted evidence, and still-unknown conditions.
Treat absence of current evidence as unknown unless the external authority explicitly establishes non-acceptance.
Allow PH-08-supported status inquiry when useful.
Return reconciliation evidence to PH-04/PH-08 without creating a new Attempt, route, or payment movement.
Preserve prior unknown reconciliation results when later evidence resolves the execution.

Acceptance

Missing evidence alone does not turn OUTCOME_UNKNOWN into failure.
Later authoritative evidence can resolve the existing execution history.
PH-10 never authorizes retry/resubmission.
A matched earlier Funding Leg is not used as evidence that a later unknown Payout succeeded.

PH10-05 — Escalate Material Reconciliation Exceptions¶

Objective

Surface material reconciliation problems for human investigation without making PH-10 a case-management system.

Required behavior

Identify discrepancies requiring human/operational investigation.
Request/create/update the applicable PH-11 Case when configured escalation criteria are met.
Avoid duplicate Cases for repeated evidence about the same unresolved condition.
Preserve the reconciliation result/evidence independently from the PH-11 Case.
Do not modify payment state based solely on escalation or human case creation.

Acceptance

A material duplicate/unexpected external payment can be escalated without waiting for irrelevant rechecks.
Repeated evidence for the same unresolved discrepancy does not create uncontrolled duplicate Cases.
PH-11 owns the investigation workflow.
PH-10 retains immutable reconciliation history after Case resolution.

PH10-06 — Provide Reconciliation History and Status¶

Objective

Make reconciliation outcomes available to operations and downstream reporting.

Required behavior

Expose the current reconciliation result for a payment/Leg/execution scope.
Preserve prior reconciliation results and evidence references.
Surface pending, mismatched, error, and escalated conditions needing attention.
Provide PH-13/Data Platform with reconciliation outcomes needed for operational and analytical use.
Keep reconciliation/reporting failures independent from normal payment execution.

Acceptance

PH-13 can display current reconciliation state and material reason/evidence.
Historical reconciliation changes remain available.
Analytical reporting may consume reconciliation outcomes without becoming the authoritative result store.
Reporting failure does not block payment execution.

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

PH-10 intentionally does not prescribe:

a generalized reconciliation rules engine;
code-defined handler registry structure;
physical reconciliation-result database schema;
exact reconciliation status/reason/severity enum implementation beyond the required outcome semantics;
fixed HIGH/CRITICAL case-escalation thresholds;
exact matching-priority algorithm;
exact API/endpoint names;
exact command/event/timer envelopes already governed by shared standards;
request fingerprints or idempotency-record structures;
transactional-outbox/event implementation;
exact recheck intervals or maximum retry counts;
durable timer/job implementation;
handler version pinning/migration mechanism;
independent provider/core/file ingestion;
duplicate payment file/batch/entry persistence;
PH-11 case-key format;
operations search/filter schemas;
metrics catalogs; or
implementation/build sequence.

Engineering should use established reconciliation, idempotency, evidence-correlation, scheduling, and operational-control patterns appropriate to the implemented CU/Product integration.

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

14. Scope boundaries¶

Out of scope¶

Synchronous payment execution gating for normal payment processing.
Payment execution.
Route selection.
Automatic correction of PH-03/PH-08 state.
Retry/reroute authorization.
Independent external-provider/file ingestion.
Generalized fuzzy/probabilistic transaction matching in the initial Product.
Case-management workflow.
Warehouse/BI implementation.
General-ledger reconciliation.
Bank-statement/corporate-finance reconciliation.
Accounts-receivable reconciliation.
Settlement balances.
Liquidity.
Prefunding.
Reserves.
Funds-in-transit accounting.

15. PH-10 completion criteria¶

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

reconciliation runs asynchronously and does not become a normal synchronous payment-execution dependency;
each implemented execution path can compare DragonPay's execution record to the authoritative external evidence actually available for that path;
each Payment Leg is reconciled independently;
strong identifiers are preferred and ambiguous/fuzzy matches are not automatically accepted;
material amount, currency, direction, status, expected-record, and reference checks can be performed where applicable;
expected evidence delay produces PENDING rather than an immediate false mismatch;
reevaluation is bounded and preserves prior results;
OUTCOME_UNKNOWN can be investigated using later authoritative evidence without PH-10 authorizing another execution;
material unresolved reconciliation discrepancies can be escalated to PH-11 without making PH-10 a case-management system;
PH-10 never directly changes canonical payment/execution state;
material reconciliation outcomes and resolution evidence are available to PH-09 and PH-13/Data Platform for durable history and reporting, with the publication mechanism left to Engineering/shared standards;
PH-13/Data Platform can consume reconciliation history/results without becoming authoritative for reconciliation; and
new execution paths can add only the reconciliation behavior their real external evidence requires without requiring a generalized reconciliation platform.