PH-08 — Payment Execution and Connector Framework¶

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

1. Objective¶

Provide the shared execution capability used by DragonPay to execute an authorized PH-03 Payment Leg through the Route Capability and Connection selected by PH-07.

PH-08 establishes:

one consistent execution boundary between DragonPay payment orchestration and CU/provider-specific integrations;
execution of exactly the Payment Leg and Connection authorized by the current Product/routing decision;
provider-neutral execution input derived from canonical DragonPay payment data;
normalization of CU/provider-specific execution outcomes;
explicit evidence of whether external handoff definitely did not occur, definitely occurred, or is uncertain;
safe handling of technical retry without creating duplicate payment movement;
status inquiry and asynchronous update handling for pending or uncertain executions;
current Connection availability information for PH-07 and operations;
secure retention/reference of external execution evidence needed for support, reconciliation, and audit; and
support for API, CU/core, file-based, message-based, or other integration styles required by supported Products and Tenant implementations.

PH-08 does not choose the payment route, redefine Product behavior, or own the canonical PH-03 Execution Attempt or Provider Transaction records.

The exact Connector runtime, Connector registry, Connection schema, retry library, circuit-breaker implementation, event transport, persistence schema, file/batch implementation, API contracts, transformation tooling, and operational dashboards are Engineering decisions provided the Product requirements in this epic are preserved.

2. Ownership boundaries¶

Owner	Responsibility
PH-03	Owns canonical Payment Legs, Execution Attempts, Provider Transactions, and their payment-domain state.
PH-04	Determines when execution is Product-authorized and whether another Execution Attempt may be created safely.
PH-05	Owns Party and Payment Instrument facts required to construct execution requests.
PH-06	Owns policy Decisions required before execution when applicable.
PH-07	Selects the Route Capability and Connection and ensures routing evidence remains valid.
PH-08	Executes through the selected Connection, normalizes external outcomes, tracks handoff certainty, retains execution evidence, and exposes Connection execution availability.
Concrete CU/provider integration	Implements the technical mapping and protocol required by a specific external interface.
PH-09 / PH-10 / PH-13	Consume execution history/evidence for payment history, reconciliation, and operational/reporting purposes.

PH-08 owns execution behavior and external evidence, not a duplicate canonical payment model.

3. Core execution model¶

3.1 Payment execution¶

Execution is performed for one PH-03 Payment Leg at a time.

Each separately executed Funding, Payout, Return, Refund, Reversal, or other movement has its own execution context and PH-03 Execution Attempt.

Execution of one Leg does not imply execution or success of another Leg.

3.2 Connector¶

A Connector is DragonPay-controlled integration code that translates between DragonPay's payment-execution model and one CU/provider/core/file/network interface.

Examples may include:

CU core integration;
payment-provider API;
ACH file delivery integration;
message-based payment interface;
another supported provider or network integration.

Provider-specific behavior remains inside the concrete Connector/integration boundary rather than leaking into PH-04 or the canonical payment model.

PH-08 does not require a generalized runtime mapping engine or customer-authored integration logic.

3.3 Connection¶

A Connection is the Tenant-specific configured use of a Connector or integration path.

It identifies the actual CU/provider/core/file destination and the configuration/credentials required to use it.

PH-07 selects the applicable Route Capability/Connection.

PH-08 executes that selected Connection and does not silently substitute another Route Type, Route Capability, Connection, or provider.

3.4 Execution instruction¶

PH-08 constructs a provider-neutral execution instruction from the authorized Payment Leg and applicable PH-05/payment context.

It contains the payment facts required to execute the intended movement while allowing the concrete Connector to perform provider-specific transformation.

The instruction for an Execution Attempt is stable once external execution begins.

A materially different payment instruction requires Product authorization for a new PH-03 Execution Attempt rather than mutation of the prior attempted movement.

4. Execution authorization and identity¶

PH-08 executes only when current DragonPay authority permits the Payment Leg to proceed.

Execution must be associated with:

the Tenant and PH-03 Payment Leg;
the applicable PH-04 Product-processing context;
the current PH-07 Route Decision;
the selected PH-08 Connection;
applicable PH-06 policy Decision when required; and
one PH-03 Execution Attempt.

PH-08 must not independently recalculate Product authorization, policy, or routing.

PH-08 must refuse external handoff when the supplied Product authorization, policy, or routing evidence is not current at the time of handoff. Verifying currency is not recalculation; PH-08 still does not re-derive the underlying Product, policy, or routing decision.

A stable external submission identity must exist for each intended external execution so technical retry/recovery can refer to the same intended movement rather than accidentally creating another one.

The exact identifier format, persistence structure, or provider idempotency mechanism is Engineering/integration specific.

5. Handoff certainty and normalized outcome¶

External execution result and external handoff certainty are separate concepts.

PH-08 must determine, to the extent supported by authoritative evidence, whether an execution instruction:

NOT_HANDED_OFF — definitely remained within DragonPay control and did not reach the external execution boundary;
HANDED_OFF — definitely reached the configured external execution boundary; or
UNKNOWN — may have reached the external execution boundary but DragonPay cannot establish that fact conclusively.

These concepts are Product/domain requirements because they determine whether another external submission can be safe.

Unknown outcome¶

A timeout, lost response, worker failure, or transport error must not be interpreted as confirmed payment failure when external handoff may have occurred.

When the external outcome or handoff remains uncertain:

the applicable PH-03 Execution Attempt becomes or remains OUTCOME_UNKNOWN;
PH-08 must not automatically make another external submission for that movement;
PH-08 may continue non-monetary inquiry or process later external evidence; and
PH-04 determines whether/when a new Execution Attempt is Product-safe after authoritative evidence is available.

Possible handoff is therefore fundamentally different from known pre-handoff failure.

6. Technical retry versus new payment execution¶

PH-08 may retry technical work that cannot create a second payment movement.

Examples include:

loading configuration;
credential retrieval;
persistence/recovery work;
status inquiry;
duplicate-safe event processing;
another operation known not to create an additional external payment.

A repeat external submission is permitted only when authoritative evidence establishes that the previous intended submission did not reach the external boundary and the applicable Product/execution rules permit continuation.

If handoff occurred or may have occurred, PH-08 must not use technical retry policy to create another payment submission.

Connector or provider retry guidance may further restrict whether repeat submission is appropriate, but must never authorize resubmission unless DragonPay has authoritative evidence that the prior handoff did not occur.

A new external payment submission requiring another PH-03 Execution Attempt is authorized by PH-04/Product behavior, not by PH-08 retry logic.

The exact retry counts, timing, backoff, libraries, and resilience policies are Engineering decisions.

7. Execution outcomes and external evidence¶

PH-08 normalizes provider/CU-specific results into payment-execution evidence that PH-03/PH-04 can consume without understanding the external implementation.

Normalized outcomes must distinguish, as applicable:

execution accepted/staged/pending;
authoritative completion/success;
authoritative rejection or known failure;
return/reversal/corrective result;
unresolved/unknown outcome.

PH-08 must preserve enough original external evidence to support:

operations investigation;
later status resolution;
PH-03 Provider Transaction association;
reconciliation;
audit/history; and
diagnosis of provider/Connector mapping behavior.

Evidence may include external transaction, file, batch, entry, network, or core references as relevant to the integration.

Sensitive raw request/response/file evidence must be protected and exposed only to authorized users/services.

The exact evidence schema and storage mechanism are Engineering/integration decisions.

Material PH-08-owned execution outcomes and material Connection/Connector state changes managed by PH-08 must be available to the capabilities responsible for durable payment history, reconciliation, and operational/reporting views. PH-08 does not republish canonical PH-03 payment state; PH-03 makes its own state changes available. How that availability is technically achieved is an Engineering/standards concern, not a PH-08 Product requirement.

8. Status inquiry and asynchronous external updates¶

Some execution outcomes are not authoritative at the time the initial execution call returns.

PH-08 must support later authoritative evidence through:

non-monetary status inquiry when the external interface supports it;
asynchronous provider/CU/core/network events;
file acknowledgements or later processing evidence;
reconciliation evidence when necessary.

Incoming external evidence must be correlated to the correct Tenant, Payment Leg, Execution Attempt, and Provider Transaction where possible.

Repeated delivery of the same logical external evidence must not apply the payment state change more than once.

Conflicting or ambiguous external evidence must not silently update the wrong payment.

Unmatched evidence remains available for investigation/reconciliation rather than being discarded or guessed into a payment.

When later authoritative evidence resolves an OUTCOME_UNKNOWN Attempt, it updates the existing execution history rather than creating a replacement attempt merely to record the new evidence.

9. Connection availability and resilience boundary¶

PH-08 owns the current operational facts needed to determine whether a configured Connection can accept new execution.

At minimum, PH-08 must distinguish, as separate dimensions rather than one collapsed status:

administrative status — administratively available versus suspended/maintenance/retired;
observed health — usable versus degraded/unavailable/unknown based on current external dependency evidence;
circuit state — whether outbound execution to this Connection is currently permitted, temporarily blocked, or in bounded recovery following prior failures; and
admission state — whether new payment work may currently be accepted.

These four dimensions must remain separately observable by PH-07 and operations; PH-08 must not collapse them into a single combined availability value, because downstream operational and reporting behavior depends on distinguishing them.

These facts must carry enough currency information for PH-07, PH-13, and operations to determine whether they are current or stale; stale availability facts must be distinguishable from a Connection genuinely observed as unavailable.

PH-07 consumes these facts when routing or validating a previously selected route.

PH-08 must not force PH-07 to derive Connection availability from provider-specific health signals.

The exact health model, circuit-breaker states, throttling model, capacity model, telemetry fields, and admission-control implementation are Engineering decisions.

Isolation¶

Failure or degradation of one CU/provider Connection must not consume shared resources in a way that prevents unrelated Tenant/Connection execution from continuing.

PH-08 must apply appropriate isolation and bounded execution behavior.

A temporary Connection failure does not itself change a payment outcome.

10. Supported integration styles¶

PH-08 must support different external execution mechanisms behind the same Product-facing execution boundary.

These may include:

synchronous or asynchronous APIs;
CU/core integrations;
file-based execution;
message-based execution;
provider-managed processing.

The specific mechanisms implemented are driven by supported CU/Product integrations.

File-based execution¶

File-based execution must be supportable when an integration requires it.

The Connector/integration may stage payments, group them, build a provider/network file, deliver that file, and later receive acknowledgement or status evidence.

The shared PH-08 behavior remains:

one Payment Leg/Execution Attempt remains independently traceable;
staging before external delivery is distinguishable from external handoff;
delivery of a file does not imply final payment completion;
stable external references protect against duplicate movement and support later correlation; and
Connector-specific batch/file mechanics do not become a second shared DragonPay payment domain.

ACH/Nacha is an expected example for an initial CU integration, but the details of ACH file construction, grouping, submission, acknowledgements, returns, and CU-specific processing are owned by the concrete integration rather than by PH-08 Product requirements.

11. Connector/integration readiness¶

A concrete Connector/integration must demonstrate that it safely satisfies the PH-08 execution contract before it is used for production payment execution.

At minimum, DragonPay must be able to establish that the integration correctly handles:

canonical-to-external transformation;
external-to-normalized-result transformation;
stable execution identity/idempotency behavior;
known pre-handoff failure;
confirmed handoff;
uncertain handoff/unknown outcome;
later status inquiry/events when supported;
duplicate external evidence;
protected credentials/evidence; and
provider-specific error/result normalization.

The exact simulation framework, fixture format, automated conformance suite, and release process are Engineering responsibilities.

12. Product stories¶

PH08-01 — Configure and Operate Execution Connections¶

Objective

Provide Tenant-specific execution paths that concrete Connectors/integrations can use safely.

Required behavior

Configure the Connector/integration and external destination required by a Tenant execution path.
Protect credentials/secrets used by the Connection.
Validate required configuration before production use.
Allow authorized administrative suspension/maintenance/restoration for future execution.
Preserve historical execution references when Connection configuration later changes.
Expose current execution-availability facts needed by PH-07.
Isolate Connection degradation from unrelated Tenant/Connection execution.

Acceptance

A suspended/maintenance Connection cannot accept new payment execution.
Connection secret material is not exposed through ordinary retrieval/logging.
PH-07 can determine whether the Connection currently admits new execution without implementing its own provider-health logic.
Changing Connection configuration does not rewrite historical payment execution evidence.

PH08-02 — Execute an Authorized Payment Leg¶

Objective

Execute one PH-04-authorized PH-03 Payment Leg using the PH-07-selected Connection.

Required behavior

Execute exactly one Payment Leg per logical execution operation.
Use the current Product/policy/route authority supplied by PH-04.
Use the Connection selected by PH-07 without silently substituting another route or provider.
Coordinate one PH-03 Execution Attempt for the intended external submission.
Construct a stable provider-neutral execution instruction.
Establish/reuse a stable external execution identity for technical recovery.
Prevent repeated delivery of the same logical execution request from creating uncontrolled duplicate external payment submissions.
Refuse new handoff when the selected Connection cannot safely admit execution.
Refuse new handoff when the supplied route or policy evidence is no longer current.

Acceptance

A technical replay of the same logical execution does not create another payment movement.
Funding, Payout, and corrective Legs have independent execution histories.
PH-08 does not select a new Route Type/Connection when the selected path becomes unavailable.
Known pre-handoff inability to execute does not create an external transaction.
Execution is refused when the supplied route or policy evidence is no longer current at the time of handoff.

PH08-03 — Normalize Execution Outcome and Handoff Evidence¶

Objective

Convert external execution results into authoritative DragonPay evidence without inventing payment success or failure.

Required behavior

Preserve external result/reason/reference evidence needed to interpret the execution.
Normalize provider-specific outcomes for PH-03/PH-04 consumption.
Record handoff certainty independently from execution outcome.
Treat possible handoff as unresolved rather than confirmed failure.
Associate authoritative external transaction references with the PH-03 Provider Transaction model when available.
Retain evidence required for operations and reconciliation.
Protect sensitive external evidence.

Acceptance

A timeout after possible external handoff does not become automatic FAILED.
UNKNOWN handoff results in unresolved/OUTCOME_UNKNOWN execution state.
Provider-specific statuses do not leak into the canonical payment lifecycle without normalization.
Historical external evidence remains available after later state resolution.

PH08-04 — Recover Execution Without Duplicating Payment Movement¶

Objective

Allow safe technical recovery while preventing retry logic from creating duplicate external payments.

Required behavior

Permit technical retry only when it cannot create a second payment or authoritative evidence establishes non-handoff.
Reuse the same execution identity for technical continuation of the same PH-03 Execution Attempt.
Prohibit automatic resubmission when handoff occurred or may have occurred.
Treat Connector/provider retry guidance as capable of further restricting resubmission, never of authorizing it beyond what authoritative handoff evidence already permits.
Require PH-04/Product authorization for another external submission/new Execution Attempt.
Preserve unresolved execution rather than manufacturing a successful or failed result when evidence is insufficient.

Acceptance

A timeout after possible handoff cannot trigger automatic resubmission/failover.
Known pre-handoff failure may be technically retried when safe.
PH-08 retry policy alone cannot create a new PH-03 Execution Attempt.
Optimistic Connector/provider retry guidance never results in resubmission when authoritative evidence has not established non-handoff.
Unknown outcome remains unresolved until authoritative evidence or Product-approved next action exists.

PH08-05 — Resolve Pending and Unknown Execution¶

Objective

Apply later authoritative external evidence to the correct existing execution history.

Required behavior

Support external status inquiry where the integration provides it.
Accept asynchronous execution/status evidence from supported integrations.
Deduplicate repeated delivery of the same logical external event/evidence.
Correlate authoritative evidence to the correct execution using stable DragonPay/external references.
Refuse to silently apply ambiguous/conflicting evidence to a payment.
Apply later authoritative evidence to the existing PH-03 Execution Attempt/Provider Transaction.
Preserve unmatched evidence for operations/reconciliation.

Acceptance

Repeated external delivery does not apply the same state transition twice.
A later authoritative status can resolve an existing OUTCOME_UNKNOWN Attempt.
Ambiguous/unmatched evidence does not update an arbitrary payment.
Status inquiry cannot itself create another external payment movement.

PH08-06 — Support Multiple Integration Mechanisms¶

Objective

Allow concrete CU/provider integrations to execute through the shared PH-08 model without forcing all integrations into one technical protocol.

Required behavior

Support API, CU/core, file-based, message-based, or other execution mechanisms required by implemented Products/CUs.
Keep provider/network/file-specific transformation and lifecycle mechanics behind the concrete Connector/integration boundary.
Preserve the same Payment Leg, Execution Attempt, handoff, normalization, evidence, and unknown-outcome guarantees regardless of the technical integration style.
For file-based execution, distinguish staging from external file delivery and final payment outcome.
Require production integrations to demonstrate duplicate safety, result normalization, handoff handling, and secure evidence handling before use.

Acceptance

A file-based integration can execute without creating a separate shared DragonPay batch-payment model.
File delivery does not imply payment completion.
An API integration and file integration expose the same essential PH-08 execution semantics to PH-04/PH-03.
New integration mechanisms can be added without changing the PH-03 canonical payment hierarchy.

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

PH-08 intentionally does not prescribe:

physical Connector registry or Connection database schemas;
exact Connector interface/method names;
exact Payment Instruction field schema;
exact Connector Result field schema;
exact Connection health/circuit/admission/capacity taxonomy or field names (the four dimensions in §9 are behavioral requirements, not a field schema);
retry-classification enum values or a required Connector retry-advisory response property;
retry counts/backoff/jitter algorithms;
request-fingerprint composition;
shared command/event envelope repetition already governed by standards;
transactional outbox/event implementation;
exact PH-03 Attempt/ProviderTransaction service calls;
exact provider-status mapping taxonomy;
external-event receipt schema;
exact event identity/fingerprint mechanism;
secure evidence-store implementation;
exact transformation/mapping version fields;
generic runtime mapping engines;
generic file/batch domain entities;
ACH/Nacha file layout, batching, delivery, acknowledgement, return, or correction implementation;
exact circuit-breaker or Connection-isolation implementation;
operations search/filter schemas;
Connector test-fixture/conformance framework structure; or
implementation/build sequence.

Engineering and concrete integrations should use established payment-execution, connector, idempotency, resilience, file/API integration, and evidence-preservation patterns appropriate to the supported Product/CU.

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

14. Scope boundaries¶

Out of scope¶

Product workflow sequencing.
Policy/risk decisioning.
Route selection.
Canonical PH-03 Execution Attempt/Provider Transaction ownership.
CU/provider-specific business behavior not required by the shared execution contract.
Building a generalized integration/mapping platform.
Building a generalized batch-payment domain.
ACH/Nacha implementation details at the PH-08 Product level.
Reconciliation ownership.
Customer balances, settlement accounting, prefunding, reserves, liquidity, or custody of customer funds.

15. PH-08 completion criteria¶

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

PH-04 can execute an authorized Payment Leg through the Connection selected by PH-07;
each externally executed Payment Leg is associated with its own PH-03 Execution Attempt and stable external execution identity;
PH-08 does not substitute another Route Type/Connection when the selected path is unavailable;
provider/CU-specific execution is isolated behind a concrete Connector/integration boundary;
execution outcome and external handoff certainty remain distinct;
possible/unknown external handoff cannot be treated as confirmed failure or automatically resubmitted;
safe technical recovery does not create duplicate external payment movement, and optimistic Connector/provider retry guidance cannot override DragonPay's own handoff-certainty determination;
PH-04 remains the authority for whether another PH-03 Execution Attempt is allowed;
status inquiry and asynchronous evidence can resolve pending/unknown execution when the external integration supports them;
duplicate/ambiguous external evidence cannot incorrectly mutate canonical payment state;
PH-08 provides PH-07 with current Connection execution-availability facts, as separately observable administrative/health/circuit/admission dimensions, without requiring PH-07 to build a duplicate health model;
material PH-08 execution outcomes and Connection/Connector state changes are available to the capabilities responsible for durable payment history, reconciliation, and operational/reporting views;
API, CU/core, and file-based execution can be supported behind the same essential execution semantics as required by integrations;
ACH/Nacha can be implemented as a concrete file-based integration without making its detailed file lifecycle a PH-08 Product requirement; and
production integrations demonstrate duplicate safety, normalization, handoff/unknown-outcome handling, and protected evidence handling before processing live payments.