PH-07 — Payment Route Resolution and Selection¶

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

1. Objective¶

Provide the shared routing capability used by DragonPay to determine how a specific PH-03 Payment Leg may be executed for a Tenant.

For the initial implementation, supported Products are expected to define the intended Route Type for each executable Payment Leg. PH-07 resolves that Product requirement to a Tenant-authorized executable Route Capability.

PH-07 establishes:

a clear distinction between the Product-required Route Type and the Tenant-specific executable capability;
one routing decision for each Payment Leg that requires execution;
validation that the selected capability is appropriate for the Product, payment facts, policy constraints, and current execution availability;
an immutable Route Decision identifying the selected execution path or that no permitted route is currently available;
protection against using stale or no-longer-valid routing evidence for execution;
safe reevaluation when routing facts change and another execution attempt is Product-permitted;
support for future Products that intentionally permit more than one Route Type; and
operational control over which Tenant Route Capabilities are available for future routing.

PH-07 does not execute the payment, own provider connectivity, calculate provider health, or choose a route outside the set permitted by the Product.

The exact routing-service architecture, capability schema, route-handler implementation, selection algorithm, API shape, caching, persistence schema, and operational tooling are Engineering decisions provided the requirements in this epic are preserved.

2. Ownership boundaries¶

Owner	Responsibility
Payment Product epics	Define which Route Type or permitted Route Types may satisfy a Product movement.
PH-02	Owns Tenant Product configuration that may influence Product routing requirements.
PH-03	Owns Payment Legs and canonical payment identity/state.
PH-04	Determines when routing is required and whether a new execution attempt is safe.
PH-05	Owns Party, Payment Instrument, institution, relationship, and validation facts used by routing.
PH-06	Owns policy Decisions and applicable route constraints.
PH-07	Owns Route Capability configuration and immutable Route Decisions.
PH-08	Owns Connections, Connector execution, Connection administrative/operational state, and execution evidence.

PH-07 determines the executable path. PH-08 performs the actual execution.

3. Core routing model¶

3.1 Route Type¶

A Route Type is DragonPay's logical category for how a Product movement is intended to execute.

Examples include:

ON_US
ACH
FEDNOW
RTP
CARD
CROSS_BORDER
STABLECOIN

The Product defines the Route Type required for the movement, or may explicitly permit more than one Route Type when future Product behavior requires alternatives.

PH-07 never adds a Route Type that the Product did not permit.

3.2 Route Capability¶

A Route Capability is a Tenant-authorized executable implementation of a Route Type.

It identifies the Tenant-specific path DragonPay may use to execute that kind of movement.

A Route Capability may include facts such as:

Route Type;
supported Product/use cases or movements;
supported direction;
supported Payment Instrument types;
supported currency/asset;
applicable amount constraints;
referenced PH-08 Connection;
timing/cutoff/reachability configuration where relevant; and
administrative availability for future routing.

Published/approved Route Capability configuration used by a Route Decision must remain historically interpretable even after later configuration changes.

The exact physical configuration/versioning model is an Engineering decision.

3.3 Route Decision¶

A Route Decision is the immutable result of routing one Payment Leg.

It identifies either:

the selected Route Capability required for execution; or
that no Product-permitted capability is currently eligible.

A selected Route Decision retains enough information to establish:

the Payment Leg being routed;
the Product/Tenant context;
the selected Route Type;
the selected Route Capability;
the PH-08 Connection/path needed for execution;
applicable route variant/network information when needed;
the PH-06 Decision/constraints considered where applicable;
material timing/reachability/availability facts that affected the result;
when the Decision was made; and
whether the Decision remains usable for execution.

A later route evaluation creates a new Route Decision rather than rewriting the prior result.

4. Route Type, Payment Network, and Connection¶

These concepts are related but not interchangeable.

Route Type describes the DragonPay execution category permitted by the Product.
Payment Network identifies an external payment network when the selected path uses one.
Route Capability is the Tenant-specific executable path.
Connection is the PH-08 technical connection used to perform that execution.

For example:

an ON_US Route Type may execute through a CU core Connection and have no external payment network;
an ACH Route Type may execute through a Tenant ACH capability using a processor/bank Connection and the ACH network;
a FEDNOW Route Type may execute through the CU's supported FedNow path and associated Connection.

PH-07 must preserve these distinctions without requiring every Route Type to have the same network/provider shape.

5. Initial routing behavior¶

For the initial Product implementation, Products are expected to specify the Route Type required for an executable Payment Leg.

Examples:

internal CU funding movement — ON_US;
same-CU recipient payout — ON_US;
external bank-account payout — ACH.

PH-07 then:

identifies the Tenant Route Capability or capabilities that satisfy the required Route Type;
evaluates the current facts required to determine whether the capability may execute this Payment Leg;
selects the applicable capability; and
records one immutable Route Decision.

If no capability can currently satisfy the Product-required Route Type, PH-07 returns a no-route outcome rather than silently substituting another Route Type.

Future multiple-route behavior¶

The routing model must permit a future Product to intentionally supply more than one acceptable Route Type.

When that occurs, PH-07 may select among the eligible Product-permitted alternatives using configured Product/Tenant preference.

The initial Product does not require a generalized cost/speed optimization engine.

More sophisticated selection based on cost, delivery speed, reliability, or other factors should be added only when an implemented Product requires that behavior.

6. Route eligibility¶

A Route Capability may be selected only when it remains compatible with the Product movement and current authoritative facts.

Depending on the Route Type and Product, PH-07 may evaluate:

required/permitted Route Type;
Product/use case and movement type;
execution direction;
source/destination Payment Instrument compatibility;
amount and currency/asset;
required PH-05 validation or institution/reachability facts;
applicable PH-06 policy constraints;
applicable timing, cutoff, or requested delivery requirements;
Route Capability administrative availability; and
current PH-08 Connection facts relevant to whether new execution may be admitted.

All required gates must pass before a capability is selected.

Ranking or preference cannot make an otherwise ineligible route eligible.

PH-07 does not duplicate the underlying validation, policy, or Connection-health logic owned by PH-05, PH-06, or PH-08.

7. Connection state boundary¶

PH-08 is authoritative for Connection configuration and operational state.

PH-07 may consume current PH-08 facts needed to determine whether a Route Capability is available for new execution.

PH-07 must not maintain a competing model of:

Connection health;
circuit-breaker state;
throttling/backpressure;
rate/concurrency limits;
maintenance/suspension; or
provider execution telemetry.

A Connection condition may make a Route Capability temporarily unavailable, but it does not authorize PH-07 to invent another Route Type.

If the Product permitted only one Route Type and its available capability cannot currently execute, PH-07 returns a no-route result.

8. Route validity and safe reevaluation¶

Routing depends on facts that may change between route resolution and payment execution.

A Route Decision must therefore not authorize execution indefinitely.

Before execution, DragonPay must ensure the material facts that made the route eligible are still valid.

This may include:

Route Capability remains available;
applicable PH-06 Decision/constraints remain current;
required timing/cutoff remains valid;
required reachability remains current; and
the PH-08 Connection still admits new execution.

The exact revalidation mechanism is Engineering responsibility.

Reevaluation¶

PH-04 may request a new Route Decision when:

the prior Route Decision is no longer valid;
relevant payment/policy/routing facts change;
the selected capability becomes unavailable before execution; or
another Product-permitted route is intentionally considered.

A new Route Decision does not itself authorize a new PH-03 Execution Attempt.

PH-04 must first establish that another execution submission is safe under PH-03/PH-04/PH-08 execution evidence.

A submitted, possibly submitted, acknowledged, pending, or OUTCOME_UNKNOWN prior Attempt must not be treated as safely reroutable merely because the prior Route Decision or Connection became invalid.

9. Route configuration and operational control¶

DragonPay must be able to configure the Route Capabilities available to each Tenant.

Configuration must prevent unsupported or internally inconsistent capabilities from becoming available for routing. A Route Capability may be published only when its route-specific configuration is internally consistent and sufficient for execution. Route Types that execute through an external payment network must identify the applicable network; ON_US routing must not depend on an external payment network.

Authorized operations must also be able to suspend a Route Capability for future selection without rewriting historical Route Decisions. Manual/operator route override is not required for the initial Product scope.

Initial CU onboarding may include human review and testing of the configured payment paths.

PH-07 does not require a dedicated pre-activation route-configuration validation interface separate from the normal configuration, testing, and managed onboarding process.

Route configuration must simply be valid and usable before a Product depends on it in production.

The exact configuration workflow, validation tooling, approval process, and deployment mechanism are Engineering/Operations decisions.

10. No-route behavior¶

When no Product-permitted Route Capability is currently eligible, PH-07 returns a durable no-route Decision.

The Decision must retain enough explanation for the Product and operations to understand the controlling reason.

Examples may include:

required Route Type not configured;
capability suspended;
instrument or currency unsupported;
policy constraint;
destination/reachability unavailable;
timing/cutoff unavailable; or
required Connection unavailable for new execution.

The exact reason-code catalog is not prescribed by Product. A no-route Decision must include a controlling reason sufficient for the consuming workflow to determine whether retry under unchanged conditions is meaningful or whether changed policy, configuration, Connection conditions, or operational intervention is required.

A no-route outcome does not itself mean that the payment failed.

PH-04 determines whether the Product should wait, request updated information, obtain a new policy Decision, retry routing later, or terminate according to Product behavior.

11. Product stories¶

PH07-01 — Manage Tenant Route Capabilities¶

Objective

Define the Tenant-authorized execution paths PH-07 may use for supported Payment Products.

Required behavior

Configure Route Capabilities for the Route Types required by supported Products.
Associate each capability with the Tenant and applicable PH-08 execution Connection/path.
Retain the Product/movement/instrument/currency/timing constraints needed to determine whether the capability applies.
Prevent invalid/unsupported capability configuration from becoming available for routing.
Preserve historical interpretation of a capability used by an existing Route Decision.
Allow authorized suspension/restoration for future route selection without rewriting prior Decisions.

Acceptance

A Tenant cannot route through a capability it is not authorized/configured to use.
A suspended capability is not selected for new routing.
Later capability changes do not rewrite an existing Route Decision.
The initial Product can configure the known ON_US and/or ACH paths it requires without building a generalized route-optimization system.

PH07-02 — Resolve the Route for a Payment Leg¶

Objective

Resolve the Product-required movement to one currently eligible Tenant Route Capability.

Required behavior

Route exactly one PH-03 Payment Leg at a time.
Evaluate only the Route Type(s) permitted by the owning Product.
For initial Products, resolve the known required Route Type to the applicable eligible Tenant capability.
Evaluate the current Product, payment, instrument, policy, timing/reachability, and Connection facts required by that Route Type.
Select an eligible capability when one exists.
Return a no-route outcome when none of the Product-permitted capabilities are eligible.
Handle repeated delivery of the same logical route request idempotently.

Acceptance

A request requiring ACH does not silently select ON_US, FEDNOW, or another unpermitted Route Type.
Funding, payout, and corrective Legs are routed independently.
A technical retry of the same routing request does not create uncontrolled duplicate Route Decisions.
No eligible capability produces a no-route result rather than an out-of-policy fallback.

PH07-03 — Preserve Immutable Route Decisions¶

Objective

Provide a durable, explainable routing result that PH-04/PH-08 can use for execution.

Required behavior

Create one immutable Route Decision for each logical routing evaluation.
Retain the Payment Leg, Route Type, selected Route Capability/Connection, applicable policy reference, and material decision evidence required to interpret the result.
Preserve Route Type separately from external payment network/provider/Connection identity.
Represent no-route as a valid Decision outcome.
Preserve prior Decisions when routing is evaluated again.

Acceptance

An existing Route Decision remains unchanged when the capability or Connection later changes.
A later evaluation creates a new Decision rather than mutating the prior one.
An ON_US Decision can exist without an external network.
An ACH Decision can identify the Tenant ACH capability and execution Connection without making the Connection itself the Route Type.

PH07-04 — Ensure Route Validity Before Execution¶

Objective

Prevent payment execution using materially stale or invalid routing evidence.

Required behavior

Ensure the selected Route Capability remains valid for the intended execution before PH-08 is invoked.
Recheck time-sensitive policy, timing/reachability, capability, and PH-08 Connection facts when required.
Return control to PH-04 when the prior route is no longer valid.
Do not automatically reroute or create a new Execution Attempt merely because route validity failed.
Allow PH-04 to request another Route Decision only when Product behavior and current execution evidence make another submission safe.

Acceptance

An unavailable/suspended capability cannot authorize a new execution.
An expired or otherwise invalid policy/routing condition cannot be ignored for execution.
Route invalidation alone does not prove that a prior external attempt failed.
OUTCOME_UNKNOWN or possible prior handoff prevents unsafe automated rerouting.

PH07-05 — Support Future Product-Permitted Route Alternatives¶

Objective

Allow future Payment Products to permit more than one acceptable Route Type without changing the fundamental routing model.

Required behavior

Accept an explicit Product-permitted set of Route Types when a Product requires alternatives.
Evaluate only those Product-permitted alternatives.
Exclude ineligible capabilities before selection.
Select among remaining eligible alternatives using configured Product/Tenant preference.
Keep initial selection behavior simple unless a supported Product requires more sophisticated optimization.

Acceptance

PH-07 never expands the Product-permitted route set.
Configured preference can deterministically select among multiple eligible alternatives.
A future Product can add cost/speed-aware selection without changing the core Route Requirement — Route Capability — Route Decision model.
The initial Product does not require implementation of unused optimization modes.

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

PH-07 intentionally does not prescribe:

physical Route Capability or Route Decision database schemas;
exact versioning/effectivity representation;
route-handler registry architecture;
exact route-handler interfaces;
exact API/operation names;
exact command/event envelope fields already governed by shared standards;
PH-07-specific idempotency-record structures or request fingerprints;
exhaustive route exclusion reason codes;
exact PH-08 Connection-state fields;
circuit-breaker, retry, admission, rate, capacity, or backpressure implementation;
Product activation validation contracts;
generalized automated onboarding-readiness evidence;
exact pre-execution revalidation API choreography;
transactional outbox/event implementation;
operations search/filter schemas;
cost/timing normalization algorithms;
dynamic weighted reliability optimization;
FASTEST, LOWEST_COST, or other optimization modes until a supported Product requires them;
exact ACH Same Day/Standard selection algorithm;
future FedNow/RTP/card/cross-border/stablecoin route-handler behavior before those Product integrations are implemented; or
implementation/build sequence.

Engineering should use established routing, configuration, idempotency, persistence, and availability patterns appropriate to the implemented Product scope.

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

13. Scope boundaries¶

Out of scope¶

Product workflow sequencing.
Payment Instrument ownership/validation.
Policy/risk calculation.
Provider/Connection execution.
Connector implementation.
Provider health/circuit calculation.
Execution retry policy.
Payment lifecycle history implementation.
Reconciliation.
General-purpose payment route optimization for future Products.
Customer balances, settlement accounting, prefunding, reserves, liquidity, or custody of customer funds.

14. PH-07 completion criteria¶

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

the Tenant can configure the known Route Capabilities required by the initial Payment Product;
PH-04 can request routing for one Payment Leg using the Product-required Route Type;
PH-07 never selects a Route Type outside the Product-permitted set;
Product, payment, instrument, policy, timing/reachability, and PH-08 Connection facts required by the selected route are respected;
each executable Payment Leg receives its own immutable Route Decision;
no eligible route produces an explicit no-route result rather than an unapproved fallback;
PH-08 remains authoritative for Connection operational state and PH-07 does not maintain a competing health model;
stale/invalid routing evidence cannot authorize new execution;
route reevaluation does not imply a prior payment attempt failed or authorize an unsafe duplicate submission;
Route Type, external network, Route Capability, and PH-08 Connection remain distinct concepts;
the model can later support Product-permitted alternative Route Types without requiring a redesign; and
the initial implementation is not required to build unused cost/speed/reliability optimization behavior.