PH-04 — Durable Product Orchestration¶

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

1. Objective¶

Provide durable orchestration of DragonPay Payment Products across long-running, asynchronous, and failure-prone payment processing.

PH-04 coordinates the Product lifecycle after a Payment Request is accepted. It determines when the Product may progress, wait, execute a payment movement, respond to customer/provider events, handle uncertainty, or perform a corrective action.

PH-04 establishes:

one durable logical Product-processing lifecycle for each PH-03 Payment Request;
durable progression across application, worker, and infrastructure restart;
safe handling of duplicate/retried commands and events;
durable customer, CU, provider, and Product-defined waits and expirations;
coordination of required validation, policy, routing, and execution results;
explicit separation between technical processing retry and authorization of a new payment Execution Attempt;
safe treatment of uncertain external handoff/outcome;
Product-defined cancellation and corrective behavior;
continuity of in-flight Product behavior across software changes; and
enough current orchestration visibility for DragonPay operations to understand waiting, blocked, uncertain, or exception conditions.

PH-04 does not define a proprietary workflow engine, orchestration-provider implementation, generic task scheduler, or provider-specific runtime model.

The exact orchestration technology, workflow-provider APIs, persistence representation, activity/task model, retry implementation, deployment/versioning mechanism, timer implementation, and operational tooling are Engineering decisions provided the Product behavior and safety guarantees in this epic are preserved.

2. Ownership boundaries¶

Owner	Responsibility
Payment Product epics	Define Product-specific states, allowed transitions, business timing, required waits, cancellation/corrective behavior, and the payment outcome expected by the customer.
PH-04	Coordinates durable Product progression and determines when required DragonPay capabilities may be invoked.
PH-02	Owns the Product configuration version governing the Payment Request.
PH-03	Owns canonical Payment Request, Payment Action, Payment Leg, Execution Attempt, Provider Transaction, and their current canonical state.
PH-05	Owns Parties, Payment Instruments, and associated validations.
PH-06	Owns applicable policy/risk decisions.
PH-07	Owns route eligibility and Route Decisions.
PH-08	Owns CU/provider execution and normalized execution evidence.
PH-09	Owns immutable payment lifecycle history when that capability is implemented.
PH-10	Owns reconciliation and reconciliation evidence.
Engineering / Infrastructure	Owns orchestration technology selection, runtime integration, deployment/versioning mechanics, technical retries, persistence design, observability, and operational tooling.

PH-04 coordinates these capabilities but does not replace their authoritative data or business ownership.

3. Durable Product-processing model¶

A Payment Request may require multiple asynchronous steps over seconds, days, or longer.

PH-04 maintains the durable Product-processing lifecycle needed to determine what the Product should do next.

Product orchestration state may be more detailed than the PH-03 canonical Payment Request status. Detailed workflow state remains orchestration context; PH-03 remains authoritative for the canonical payment records and current canonical payment state.

3.1 One logical lifecycle per Payment Request¶

A Payment Request must not accidentally acquire multiple competing Product-processing lifecycles because of:

client retry;
lost acknowledgement;
duplicate message delivery;
service restart;
infrastructure failure; or
orchestration-runtime recovery.

DragonPay must resolve repeated delivery/start attempts to the same logical Product-processing lifecycle.

3.2 Durable accepted progression¶

Once DragonPay durably accepts Product-processing work, temporary application or infrastructure failure must not cause that accepted work, wait, deadline, or Product state to be forgotten.

Recovery may re-run technical work when safe, but it must not repeat a business effect that has already been accepted or completed.

3.3 Product state and canonical state¶

The Product may use detailed internal states such as:

awaiting customer confirmation;
funding;
awaiting recipient claim;
ready for payout;
payout processing;
returning to sender;
execution outcome unknown; or
exception.

The owning Product defines the state vocabulary it needs.

PH-04 maps Product progression to the appropriate PH-03 canonical state without requiring PH-03 to represent every workflow detail.

4. Product orchestration invariants¶

The following are Product/domain requirements regardless of implementation technology.

4.1 Duplicate delivery does not duplicate Product behavior¶

A logical Product command, event, or other trigger may be delivered more than once.

Repeated delivery of the same logical trigger must not:

advance the Product twice;
create duplicate business Actions or Legs;
authorize duplicate payment execution; or
apply the same customer/business action more than once.

The exact command/event identity and deduplication mechanism follow applicable shared DragonPay standards and Engineering design.

4.2 Technical retry is not a new payment attempt¶

Retry by an orchestration runtime, worker, transport, queue, HTTP client, or other technical mechanism does not itself authorize a new PH-03 Execution Attempt.

A new payment Execution Attempt exists only when current Product behavior explicitly authorizes a new technical submission, retry, failover, continuation, or corrective execution.

4.3 Product timing remains authoritative¶

Product-defined deadlines, wait periods, and expirations must survive restart and recovery.

Technical retry or redelivery must not silently extend a Product/customer deadline.

When a Product-defined expiration occurs, the Product determines the resulting business transition.

4.4 Payment execution is gated by current Product authority¶

PH-04 may request payment execution only when the current Product state and required authoritative decisions permit the target Payment Leg to proceed.

Where applicable, execution requires:

a Product state that permits execution of the Leg;
required validation/eligibility results;
applicable policy/risk approval;
an applicable Route Decision, with execution remaining permitted under current route/Connection conditions as required by the owning capabilities;
any applicable Product-defined expiration, deadline, or time-based eligibility condition remains satisfied; and
no unresolved prior execution condition that would make another submission unsafe.

PH-04 coordinates these decisions but does not duplicate the business logic owned by PH-05, PH-06, PH-07, or PH-08.

4.5 Uncertain external handoff is not failure¶

When DragonPay cannot determine whether payment execution reached an external CU/provider system, the result must not be treated as confirmed failure merely because a response timed out or was lost.

An unresolved possible handoff blocks a conflicting new execution submission for the affected movement until authoritative evidence establishes a safe next action.

Resolution may come from provider status, external events, inquiry, reconciliation, or other authoritative evidence.

4.6 Corrective processing preserves prior payment history¶

Cancellation, Return, Refund, Reversal, Adjustment, and other corrective behavior are defined by the owning Product.

When a correction requires a distinct business operation or movement, it creates the applicable new PH-03 Action/Leg rather than rewriting prior payment history.

4.7 In-flight behavior does not silently change after deployment¶

A software release or workflow implementation change must not silently cause an in-flight payment to begin following materially different Product rules.

Engineering may use version pinning, compatible workflow evolution, controlled migration, or another established technique to satisfy this requirement.

5. Durable waits and asynchronous events¶

A Product may wait durably for conditions such as:

customer confirmation;
recipient claim;
CU/provider response;
external payment status;
Product-defined expiration;
scheduled business timing; or
authoritative resolution of an uncertain execution outcome.

A wait may last substantially longer than one application process or service instance.

The Product defines:

what condition satisfies the wait;
when the wait expires;
which business transition occurs after satisfaction or expiration; and
how competing events are resolved when their timing materially affects Product outcome.

Infrastructure responsible for waiting/timing does not determine the business result.

Duplicate delivery of a resolving event must not advance the Product more than once.

6. Coordination with Payment Hub capabilities¶

PH-04 invokes or obtains results from other DragonPay capabilities only when the Product requires them.

Canonical payment structure¶

PH-04 may require PH-03 Actions or Legs as Product processing progresses.

PH-03 remains authoritative for those objects and their idempotency/relationship rules.

A Product may create later Legs only after facts become available during processing. Product structure does not need to be fully known when the Payment Request is first created.

Party, Instrument, and validation¶

When Product processing requires Party, Payment Instrument, or related validation information, PH-04 obtains the applicable PH-05 result before proceeding.

Policy and risk¶

When Product processing requires a PH-06 decision, PH-04 must not proceed beyond the point governed by that decision unless the applicable decision remains valid for the intended action.

Routing¶

At the Product-defined routing point, PH-04 supplies the movement and Product constraints needed for PH-07 to determine an eligible Route Decision.

PH-04 does not determine Tenant route eligibility or provider/Connection health itself.

Payment history and reporting¶

Material PH-04 Product/workflow transitions must be available to the capabilities responsible for durable payment history and operational/reporting views; PH-04 does not own those records.

Each separately executed Payment Leg obtains the Route Decision required for that Leg.

Payment execution¶

PH-04 requests PH-08 execution only after current Product requirements and applicable gating conditions are satisfied.

PH-08 remains authoritative for execution processing and external handoff evidence.

PH-04 determines whether Product behavior permits another execution request after receiving the normalized execution result.

7. Failure and uncertainty behavior¶

PH-04 must distinguish business outcome from technical execution condition.

Condition	Product requirement
Technical processing fails before accepted Product work is durably established	The same logical operation may be safely retried.
Acceptance/delivery of the same logical Product command is uncertain	Recovery must resolve/retry the same logical operation rather than creating another business operation.
A downstream DragonPay operation experiences a retryable technical failure	The same logical operation may be retried without creating a new business effect.
A downstream capability returns a definitive business result	The Product applies that result according to its defined behavior.
Payment execution definitively did not reach the external destination	The Product may authorize retry/rerouting when its rules permit.
Payment execution may have reached the external destination	The Product remains unresolved/pending and another conflicting submission is blocked until authoritative evidence is available.
Orchestration/runtime infrastructure is temporarily unavailable	Payment outcome does not change merely because orchestration infrastructure is unavailable.
Product processing reaches an unrecoverable business/orchestration exception	The condition remains visible for operations; DragonPay does not manufacture a payment result.

8. Operational visibility¶

DragonPay operations must be able to determine enough current Product-processing information to understand whether a payment is:

actively progressing;
waiting for a customer/external condition;
waiting for a Product-defined deadline;
blocked on a required DragonPay capability;
unresolved because execution outcome is uncertain;
in an operational/Product exception; or
complete.

Operational visibility must preserve the association to the PH-03 Payment Request and applicable Product/configuration context.

Operational tooling may provide controlled recovery or corrective actions, but those actions must still pass through normal Product rules and must not bypass payment-safety requirements.

Privileged or manual recovery actions, and their outcomes, must be durably attributable and available to the applicable payment-history and operational/audit capabilities; PH-04 does not maintain a separate audit record for this purpose.

The exact query model, provider history integration, dashboards, operational commands, and recovery tools are Engineering/Operations decisions.

9. Reference example — Claim-based P2P¶

The P2P Product illustrates the orchestration capability without defining PH-04 exclusively around P2P.

A typical claim-based flow may require:

receive and validate the Payment Request;
obtain sender confirmation when required;
create and execute the Funding Leg;
after authoritative funding completion, wait durably for recipient claim;
on valid claim, establish the recipient destination;
create and route the Payout Leg;
execute payout and wait for authoritative result;
complete the Product when payout is authoritative; or
create Product-defined corrective Return processing when claim does not complete after funding.

Important PH-04 behavior demonstrated by this flow:

the claim wait survives application/runtime restart;
payout is not attempted before Product prerequisites are satisfied;
Funding and Payout remain separate PH-03 Legs;
a payout execution with uncertain handoff is not blindly resubmitted;
claim expiration after funding may create a corrective Return Action/Leg rather than rewriting the original funding history.

The owning P2P Product epic remains authoritative for the exact P2P states, timing, validations, customer behavior, and corrective rules.

10. Product stories¶

PH04-01 — Durably Orchestrate Product Processing¶

Objective

Maintain one durable logical Product-processing lifecycle for each Payment Request.

Required behavior

Associate Product processing with the applicable PH-03 Payment Request.
Preserve accepted Product state and pending work across application, worker, and infrastructure restart.
Prevent retried or uncertain start processing from creating competing logical Product lifecycles.
Allow Product state to be more detailed than PH-03 canonical state while keeping PH-03 authoritative for canonical payment records.
Preserve the Product/configuration behavior applicable to in-flight processing across software releases unless a controlled migration is explicitly performed.
Continue processing asynchronously after a synchronous caller stops waiting when DragonPay has already durably accepted the work.

Acceptance

Restart/recovery does not lose an accepted Product-processing lifecycle.
Retrying the same logical start does not create another payment-processing lifecycle.
A caller timeout after durable acceptance does not itself change payment outcome or cancel processing.
Deployment of newer Product logic does not silently reinterpret an in-flight payment using materially different rules.

PH04-02 — Process Commands, Events, Waits, and Deadlines Safely¶

Objective

Apply asynchronous Product inputs and timing conditions without duplicate business effects or loss of long-running state.

Required behavior

Apply the same logical Product command/event no more than once to business progression even when delivery is repeated.
Support durable waits for customer, CU, provider, and Product-defined conditions.
Preserve Product-defined deadlines/expirations across restart and technical retry.
Do not allow technical redelivery to extend a Product deadline.
Apply Product-defined behavior when a wait resolves or expires.
Resolve materially conflicting wait/event outcomes deterministically according to Product rules.

Acceptance

Duplicate delivery of a customer/provider event does not advance the Product twice.
A multi-day wait survives application/runtime restart.
Product expiration remains based on the original Product timing rather than restart/retry timing.
A resolving event and expiration cannot both create conflicting accepted Product outcomes.

PH04-03 — Coordinate Product Prerequisites and Payment Execution¶

Objective

Progress payment processing only after the authoritative DragonPay capabilities required by the Product permit the next action.

Required behavior

Obtain required PH-03, PH-05, PH-06, and PH-07 results at the Product-defined points in processing.
Allow Actions/Legs to be created later when facts required for those movements become available.
Request routing for each independently executed Leg according to Product requirements.
Request PH-08 execution only when current Product state and applicable prerequisite decisions authorize the target Leg.
Do not duplicate validation, policy/risk, route-eligibility, or provider-execution logic owned by other PH capabilities.
Treat technical redelivery of an orchestration operation as the same logical operation unless the Product explicitly authorizes a new business/execution action.

Acceptance

A required blocking Product prerequisite prevents progression until satisfied.
Routing/execution of one Leg does not authorize execution of another Leg.
A technical retry does not create a new PH-03 Action, Leg, or Execution Attempt unless Product behavior explicitly requires one.
PH-04 does not independently calculate route eligibility, risk outcome, or external provider result.

PH04-04 — Handle Execution Failure and Uncertain Outcome Safely¶

Objective

Prevent duplicate or incorrect payment movement when technical failure makes external execution outcome uncertain.

Required behavior

Distinguish known pre-handoff execution failure from possible/confirmed external handoff.
Permit Product-authorized retry/reroute after a definitive safe pre-handoff failure.
Treat possible external handoff as unresolved rather than confirmed failure.
Block a conflicting new execution submission for a Leg while prior execution outcome remains unresolved.
Allow authoritative provider/event/inquiry/reconciliation evidence to resolve the prior execution condition.
Do not treat technical timeout, worker failure, or orchestration-provider outage as proof of payment failure.

Acceptance

A definitive pre-handoff failure may be retried when Product rules permit.
An uncertain handoff does not automatically create another Execution Attempt.
A lost/late response after possible handoff does not become FAILED merely because a timeout expires.
Later authoritative evidence can resolve the existing PH-03 Attempt without rewriting execution history.
Orchestration/runtime outage does not manufacture a payment outcome.

PH04-05 — Handle Cancellation, Correction, and Operational Exceptions¶

Objective

Apply Product-defined cancellation/corrective behavior while preserving original payment history and exposing unresolved Product-processing conditions for operations.

Required behavior

Evaluate cancellation against the current Product/payment condition before changing progression.
Reject cancellation when the Product/payment can no longer be safely stopped.
Create new PH-03 Actions/Legs for Return, Refund, Reversal, Adjustment, or other corrective movements when they are distinct business operations.
Use the normal routing/execution path for corrective payment movement.
Preserve the original payment Actions, Legs, Attempts, and Provider Transactions.
Expose enough current Product-processing context for operations to identify waiting, blocked, execution-unknown, and exception conditions.
Ensure manual/operational actions remain subject to Product safety and transition rules.

Acceptance

Unsupported cancellation does not rewrite payment state.
Corrective movement preserves the original payment history.
Duplicate corrective commands do not create duplicate corrective business operations.
Operations can distinguish an ordinary wait from execution uncertainty or Product/orchestration exception.
Operational recovery does not bypass Product rules or authorize unsafe duplicate execution.

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

PH-04 intentionally does not prescribe:

orchestration vendor/platform;
whether the implementation uses workflow-as-code, state machines, BPMN, or another suitable orchestration model;
workflow-provider identifiers or binding-table schema;
exact Product workflow persistence representation;
activity/task schemas;
command/event/timer envelope definitions already governed by shared DragonPay standards;
exact idempotency receipt/deduplication implementation;
exact retry/backoff policy;
worker/process architecture;
timer/wait implementation;
provider-specific workflow versioning/deployment mechanics;
workflow migration mechanism;
exact API/operation names;
route/execution activity request field lists;
orchestration operational-state taxonomy;
provider-history/query integration;
dashboards and support tooling;
detailed Product lifecycle event taxonomy;
transactional outbox/event implementation; or
implementation sequencing and integration-test structure.

Engineering should use established durable-orchestration and distributed-systems patterns that satisfy this epic without building unnecessary DragonPay-specific infrastructure.

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

12. Scope boundaries¶

Out of scope¶

Defining Product-specific customer journeys or exact Product state machines.
Canonical payment persistence owned by PH-03.
Party/Payment Instrument ownership and validation logic owned by PH-05.
Policy/risk decision logic owned by PH-06.
Route eligibility/selection owned by PH-07.
Connector/Connection execution mechanics and provider normalization owned by PH-08.
Immutable payment history implementation.
Reconciliation processing.
Notification delivery.
Case-management workflow.
Customer balances, wallets, settlement accounting, prefunding, reserves, liquidity, or custody of customer funds.
Building a general-purpose workflow/orchestration product.

13. PH-04 completion criteria¶

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

each accepted Payment Request can progress through one durable logical Product-processing lifecycle;
accepted Product state, waits, and pending work survive normal application/runtime restart and recovery;
duplicate/retried delivery does not duplicate Product transitions or payment movement;
technical retry is demonstrably distinct from authorization of a new PH-03 Execution Attempt;
Product-defined waits and deadlines remain correct across restart/retry;
PH-04 obtains required authoritative prerequisite results before Product progression/execution;
PH-08 execution is requested only when current Product behavior permits the target Leg to proceed;
known pre-handoff failure and uncertain possible-handoff outcomes are treated differently;
unresolved external execution outcome blocks unsafe conflicting submission until authoritative evidence resolves it;
cancellation/corrective processing follows Product rules and preserves prior PH-03 history;
in-flight payment behavior does not silently change because newer Product/orchestration code is deployed;
operations can identify waiting, blocked, uncertain, exception, and completed Product-processing conditions;
material PH-04 Product/workflow transitions are available to the capabilities responsible for durable payment history and operational/reporting views; and
PH-04 provides the required durable payment behavior without Product prescribing the orchestration technology or detailed implementation mechanism.