PH-05 — Party and Payment Instrument Foundation¶

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

1. Objective¶

Provide the canonical Party and Payment Instrument foundation used by DragonPay Payment Products to identify payment participants, reference the payment methods they may use, preserve authoritative external identities, and expose current validation facts safely.

PH-05 separates:

who or what is participating in a payment from
the payment method or account used to send or receive value.

PH-05 establishes:

stable DragonPay identities for Parties and Payment Instruments;
Tenant-scoped ownership and isolation;
support for people, organizations, financial institutions, and additional approved Party types when needed;
support for bank accounts, tokenized payment cards, wallets, provider-managed accounts, and additional approved Payment Instrument types when required by Products;
authoritative references to CU cores, processors, providers, networks, directories, and other source systems;
relationships between Parties and Payment Instruments, including ownership or authority where required;
current validation evidence and freshness;
safe masked/display information for runtime use and PH-03 historical payment snapshots;
controlled lifecycle state for Parties and Payment Instruments; and
protection of sensitive payment-method information.

PH-05 does not determine whether a payment is allowed, which rail should be used, whether funds are available, or whether a provider can currently execute the transaction.

The exact database schema, API shape, encryption/tokenization implementation, validation-provider integration, concurrency mechanism, indexing/search implementation, and service decomposition are Engineering decisions provided the requirements in this epic are preserved.

2. Ownership boundaries¶

Owner	Responsibility
PH-01	Application identity, authorization, Tenant access control, and audit of applicable administrative/security activity.
PH-02	Product assignment and configuration.
PH-03	Payment-specific Party/Instrument roles and transaction-time payment references/snapshots.
PH-04	Determines when Product processing requires current Party, Instrument, association, or validation facts.
PH-05	Canonical current Party, Payment Instrument, their durable relationships/references, and validation evidence.
PH-06	Policy, risk, limits, and transaction eligibility decisions.
PH-07	Route/rail eligibility and route selection for a specific payment movement.
PH-08	CU/provider execution and provider-specific transaction processing.

PH-05 provides payment-relevant facts. It does not convert those facts into transaction approval.

3. Canonical model¶

3.1 Party¶

A Party is a person or organization that can participate in payment-related activity.

Initial Party categories include:

PERSON
ORGANIZATION
FINANCIAL_INSTITUTION

Additional Party types may be introduced when a supported Product requires a materially different kind of participant.

A Party type describes what the entity is.

Payment roles such as Sender, Recipient, Payer, Payee, Merchant, Beneficiary, or Cardholder are assigned in the context of a specific PH-03 payment and do not become permanent PH-05 Party types merely because a Party performed that role once.

A Party has:

one stable DragonPay Party identity;
one owning Tenant;
current lifecycle status;
payment-relevant identifying/display information;
zero or more authoritative external references;
payment-relevant contact/address information when required by supported Products; and
relationships to other Parties when a supported Product requires them.

3.2 Payment Instrument¶

A Payment Instrument represents an account, token, wallet, or other payment method that may be referenced as a source or destination of value.

Examples include:

bank account;
tokenized payment card;
digital wallet;
stablecoin wallet/address;
provider-managed payment account.

A Payment Instrument has:

one stable DragonPay Payment Instrument identity;
one owning Tenant;
one approved instrument type;
current lifecycle status;
an authoritative source where applicable;
safe display information;
the payment-method facts required by supported Products and downstream execution; and
zero or more authoritative external references.

The Payment Instrument model must allow new instrument types to be introduced without changing the PH-03 canonical payment hierarchy.

The exact physical representation of type-specific instrument data is an Engineering decision.

3.3 Party-to-Payment-Instrument association¶

A Party and Payment Instrument may be associated when DragonPay needs to know that the Party has a durable relationship to the instrument.

Examples include:

owner;
joint owner;
authorized user;
funding authority;
receiving authority;
beneficiary;
merchant settlement authority.

The exact association vocabulary is Product/domain controlled only as supported Products require it.

An association is evidence of the known relationship between the Party and Payment Instrument. It is not, by itself, approval for a specific payment.

3.4 Party relationships¶

PH-05 may represent durable Party-to-Party relationships when a supported Product needs them.

Examples may include:

a person acting for an organization;
a person associated with a financial institution;
another Product-required durable relationship.

PH-05 does not infer durable Party relationships merely from prior payment activity.

Payment-specific roles remain in PH-03.

3.5 Validation evidence¶

A Validation Result represents evidence about a Party, Payment Instrument, or Party-Instrument association obtained from an authoritative source or validation process.

Examples include:

Party/account currently active;
contact verified;
account open;
account ownership confirmed;
token valid;
wallet/address validated;
authority confirmed.

Validation evidence retains enough information to establish:

what was validated;
the result;
the authoritative source;
when the validation occurred;
when it ceases to be considered fresh, when applicable;
a normalized reason/result; and
a supporting evidence reference when required.

A refreshed validation creates new evidence. Prior validation evidence is not rewritten merely because a later validation produced a different result.

Missing, stale, unknown, or failed evidence must not be represented as a current successful validation.

4. Identity and reference rules¶

The following are Product/domain invariants.

DragonPay Party and Payment Instrument identities are stable for the lifetime of the object.
A Party or Payment Instrument belongs to one Tenant and cannot be reassigned to another Tenant.
External-system identifiers do not replace DragonPay canonical identifiers.
An authoritative external reference is interpreted within its applicable Tenant, source system, and reference type.
When an authoritative source guarantees uniqueness, the same definitive external reference must not create uncontrolled duplicate Parties or Payment Instruments.
DragonPay must not automatically merge Parties or Payment Instruments based only on fuzzy similarity such as matching names, contact data, masked account data, or other non-authoritative attributes.
Payment-specific Sender/Recipient/Merchant/etc. roles are stored by PH-03, not inferred as permanent PH-05 identity.
Party and Payment Instrument status changes affect current/future use but do not rewrite historical PH-03 payment references or snapshots.
Party/Instrument association does not itself establish transaction eligibility, available balance, route eligibility, or provider reachability.
Rail or route eligibility is not a durable property of the Payment Instrument. PH-07 determines transaction-specific route eligibility using current facts.

5. Required Party information¶

PH-05 must retain enough current Party information to support applicable Payment Products without making the Party model Product-specific.

At minimum, a Party may need:

Information	Product purpose
DragonPay Party identity	Stable canonical reference.
Tenant	CU/customer isolation boundary.
Party type	Identifies the kind of participant.
Current status	Controls whether the Party is currently available for applicable future use.
Display/legal identity information	Customer, operations, provider, or regulatory use when required.
Authoritative external references	Resolve the Party to CU/provider/source-system identities.
Contact information	Product communication or participant resolution when required.
Address information	Product/provider/regulatory use when required.
Relationships	Durable Party relationships needed by a supported Product.

Not every Product requires every category of Party information.

The owning Payment Product determines which facts are required for that use case.

6. Required Payment Instrument information¶

PH-05 must retain enough information to identify and safely use an approved Payment Instrument type.

Bank account¶

May require:

owning/servicing financial institution reference;
account type;
safe masked account display;
currency when relevant;
CU/core/provider account identity or token;
routing/account information only when required for execution.

Payment card¶

The standard PH-05 model uses tokenized/provider-managed card references.

It may retain:

token/provider reference;
card brand;
safe masked display/last four;
permitted expiration information;
applicable provider/merchant scope.

Raw card PAN or CVV is not part of the standard PH-05 Payment Instrument model.

Digital/provider wallet or account¶

May retain:

provider identity;
wallet/account token or external reference;
safe display information;
applicable currency/asset information.

Stablecoin wallet/address¶

May retain:

network/blockchain;
wallet address or provider-managed token/reference;
supported asset;
memo/tag or equivalent network information when required;
provider/custody reference when applicable.

These definitions describe Product-required information categories, not a prescribed physical schema.

A Payment Product only requires implementation of the instrument types it actually supports.

7. Sensitive payment data¶

PH-05 must minimize DragonPay possession and exposure of sensitive payment-method data.

The following Product/security requirements apply:

Prefer durable provider/source tokens or references when they can satisfy payment processing.
Raw card PAN/CVV is not accepted or persisted through the standard PH-05 Payment Instrument model.
Sensitive bank, wallet, provider-account, or other execution information retained by DragonPay must be protected according to its data classification.
Ordinary retrieval and operations views expose only approved masked or tokenized information.
Protected payment values must not appear in ordinary application logs, traces, analytics, search indexes, or general events.
Access to protected values required for payment execution is limited to authorized execution paths and exposes only the information required for that purpose.
PH-03 historical payment snapshots receive approved display/reference information, not protected payment credentials.
Material privileged or manual changes to Party or Payment Instrument information, and privileged access to unmasked protected data, must be durably attributable to the acting identity with the action, outcome, and time available for investigation.

The exact encryption, tokenization, key-management, vault, secret-storage, or data-access implementation is Engineering responsibility.

8. Lifecycle and current-use behavior¶

Party¶

A Party supports the current lifecycle states required for supported Products, including at least:

ACTIVE
SUSPENDED
CLOSED

A Product may use a preparation/pending condition when participant setup is not yet complete.

Suspension prevents applicable future use while preserving identity, relationships, validation history, and historical payment references.

Closure is terminal for ordinary use unless a future Product explicitly defines reopening behavior.

Payment Instrument¶

A Payment Instrument supports at least:

ACTIVE
SUSPENDED
CLOSED

Instrument types may also have authoritative lifecycle conditions such as expiration.

A suspended/closed/expired instrument remains identifiable for historical payment interpretation even when it is not eligible for new use.

Changing PH-05 status does not automatically rewrite, cancel, or determine the outcome of an already executing payment. The owning Product/orchestration evaluates current facts and determines the appropriate payment behavior.

9. Durable persistence, idempotency, and write safety¶

Party and Payment Instrument records are shared payment-domain identities and must be durably persisted.

Once DragonPay accepts creation of a Party, Payment Instrument, durable relationship/association, or validation evidence record, a service restart or retry must not cause the accepted identity/evidence to be lost or replaced by another logical object.

Create operations must be idempotent for the same logical request.

For the same logical create request:

DragonPay resolves to the same Party, Payment Instrument, association, relationship, or validation evidence;
technical retries do not create duplicate logical records; and
conflicting reuse of the same logical idempotency identity with materially different content is rejected rather than silently changing the existing object.

Concurrent/stale updates must not silently overwrite newer Party, Payment Instrument, association, or relationship state.

The exact idempotency record, fingerprint, persistence transaction, uniqueness constraint, and concurrency-control mechanism follow shared DragonPay standards (STD-01) and Engineering design.

10. Runtime retrieval and historical payment context¶

Authorized DragonPay capabilities must be able to retrieve current PH-05 facts by:

DragonPay Party/Payment Instrument identity; and
approved authoritative external references when applicable.

Normal retrieval must:

enforce Tenant isolation;
return only authorized information;
expose masked/protected data appropriately;
distinguish current lifecycle state;
expose applicable current association/relationship facts; and
expose applicable validation evidence and freshness without turning those facts into transaction approval.

PH-05 must also provide the approved payment-display/reference information PH-03 needs to persist the transaction-time context of a payment.

A later change to a Party name, Payment Instrument display, relationship, status, or validation result must not silently alter the historical representation already retained by PH-03.

The exact search/index implementation and operational query APIs are Engineering decisions.

11. Product stories¶

PH05-01 — Manage Canonical Parties¶

Objective

Provide stable Tenant-scoped Party identities for payment participants.

Required behavior

Create and retrieve a Party using a stable DragonPay identity.
Support the Party types required by current Payment Products.
Associate authoritative external references when available.
Preserve Tenant ownership and Party identity for the Party lifetime.
Support payment-relevant Party details and durable relationships when required by a Product.
Prevent definitive authoritative-reference duplication from creating uncontrolled duplicate Parties.
Do not automatically merge Parties based only on fuzzy similarity.
Handle logical creation requests idempotently.

Acceptance

One logical create produces one stable Party identity despite technical retries.
An authoritative reference that already identifies a Party resolves to the existing Party when that source/reference is defined as unique.
The same external reference value can exist in different valid namespaces without being assumed identical.
A Party cannot be resolved or returned across Tenant boundaries.
Payment-specific Sender/Recipient/etc. roles are not stored as permanent Party identity.

PH05-02 — Manage Payment Instruments¶

Objective

Provide stable Tenant-scoped identities for payment methods used by supported DragonPay Products.

Required behavior

Create and retrieve Payment Instruments using stable DragonPay identities.
Support the Payment Instrument types required by current Payment Products.
Retain the type-specific information necessary for Product use and payment execution without making PH-03 Product/provider specific.
Associate authoritative provider/CU/network references where applicable.
Prefer provider/source tokens when available.
Preserve safe display information separately from protected execution information.
Prevent definitive authoritative-reference duplication from creating uncontrolled duplicate Payment Instruments.
Handle logical registration requests idempotently.
Do not store rail/route eligibility as a durable Payment Instrument property.

Acceptance

One logical registration produces one stable Payment Instrument identity despite technical retries.
Current Products can represent the account/token/wallet types they require without changing the PH-03 payment hierarchy.
A definitive duplicate external reference resolves to the existing Payment Instrument where the source guarantees uniqueness.
Standard retrieval exposes safe masked/tokenized information.
A Payment Instrument alone does not imply payment approval or route eligibility.

PH05-03 — Maintain Party, Instrument, and Authority Relationships¶

Objective

Represent durable relationships needed to understand who owns, controls, or is otherwise associated with payment participants and Payment Instruments.

Required behavior

Associate a Party with one or more Payment Instruments when supported Product behavior requires ownership/authority information.
Support durable Party-to-Party relationships when required by a Product.
Retain the relationship/authority type and supporting source/evidence needed to interpret it.
Keep these relationships separate from PH-03 payment-specific roles.
Preserve prior relationship identity/history when a relationship is suspended or ended.
Prevent cross-Tenant relationships/associations.
Handle logical relationship creation idempotently.

Acceptance

A Party may be associated with multiple Payment Instruments.
A Payment Instrument may have multiple valid Party associations when supported by the relevant Product/domain model.
An ownership/authority association is distinguishable from transaction approval.
Ending/suspending a relationship does not rewrite historical payments.
Cross-Tenant association is rejected.

PH05-04 — Record and Resolve Validation Evidence¶

Objective

Provide current and historical evidence about Parties, Payment Instruments, and their associations without making PH-05 the owner of Product eligibility decisions.

Required behavior

Record validation evidence produced by an authoritative source/process.
Retain subject, validation type, normalized result, source, validation time, freshness/expiration when applicable, and supporting evidence reference when required.
Preserve prior validation evidence when a new validation occurs.
Identify when the most applicable evidence is stale or no longer valid.
Preserve failed, pending, unknown, and action-required outcomes distinctly from passed results.
Never treat missing or stale validation evidence as current successful evidence.
Allow PH-04/PH-06/PH-07 and supported Products to consume validation facts while those capabilities retain ownership of their decisions.

Acceptance

Refreshing a validation does not overwrite prior evidence.
Stale evidence is distinguishable from fresh evidence.
A newer failed/unknown result is not hidden by an older passed result.
Recording validation evidence does not automatically approve, suspend, or execute a payment.
Duplicate technical delivery does not create uncontrolled duplicate validation evidence.

PH05-05 — Protect and Expose Payment Data Safely¶

Objective

Make Party and Payment Instrument information usable by DragonPay while minimizing exposure of protected payment data.

Required behavior

Return masked/tokenized information through ordinary retrieval.
Reject raw card PAN/CVV through the standard Payment Instrument model.
Prefer durable provider/source tokens over retaining raw sensitive values.
Protect sensitive payment data retained for execution.
Restrict protected execution data to authorized internal execution use.
Keep protected values out of ordinary logs, traces, analytics, indexes, events, and PH-03 historical snapshots.
Provide PH-03 the approved stable references and display information required for transaction-time payment history.

Acceptance

Ordinary retrieval does not expose protected bank, wallet, card, or provider credentials.
Raw PAN/CVV is not persisted through the standard PH-05 model.
Unauthorized callers cannot retrieve protected execution values merely because they can view the Payment Instrument.
PH-03 can retain useful historical payment display information without storing protected credentials.
Later changes to current PH-05 data do not rewrite the PH-03 transaction-time snapshot.

PH05-06 — Manage Current Status and Retrieval¶

Objective

Maintain current Party and Payment Instrument availability and provide authorized DragonPay capabilities with current payment-relevant facts.

Required behavior

Support suspension and closure of Parties and Payment Instruments while preserving canonical identity and historical references.
Support restoration from suspension when no authoritative condition prevents future use.
Preserve authoritative instrument conditions such as expiration when applicable.
Prevent stale/concurrent administrative updates from silently overwriting newer state.
Allow authorized retrieval by DragonPay identity and approved authoritative references.
Enforce Tenant isolation and masking on all retrieval.
Expose current status, applicable relationships/associations, and validation facts required by downstream DragonPay capabilities.
Do not automatically rewrite or determine the outcome of already executing payments because current PH-05 status changes.

Acceptance

A suspended Party or Payment Instrument is visible as suspended for future Product decisions.
Historical PH-03 references remain intact after suspension or closure.
A stale conflicting update cannot silently replace current state.
Another Tenant cannot retrieve or discover the object by identifier collision.
Current PH-05 retrieval provides facts without asserting transaction approval, risk acceptance, or route eligibility.

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

PH-05 intentionally does not prescribe:

physical database tables or ORM entities;
record_version or another specific concurrency mechanism;
exact REST/API paths;
command/event envelope field repetition already governed by shared standards;
a PH-05-specific idempotency-record schema;
request-fingerprint composition;
database indexes and uniqueness-constraint implementation;
exact Party contact/address schema beyond Product-required information;
exact PartyRelationship or Party-Instrument-association table structures;
exact Payment Instrument type-schema implementation;
encryption/tokenization/key-management technology;
provider-token storage mechanism;
search/index technology;
validation-provider integration;
exact operational/audit event taxonomy;
detailed response/view models; or
implementation/build sequence.

Engineering should use established identity, payment-data protection, persistence, idempotency, and concurrency patterns that satisfy the Product/domain requirements in this epic.

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

13. Scope boundaries¶

Out of scope¶

Application identity and access control.
Product assignment/configuration.
Payment-specific Party/Instrument roles.
Payment workflow sequencing.
Policy, risk, limits, or transaction eligibility.
Available-balance or funds-availability determination.
Route/rail eligibility and route selection.
Provider/Connection reachability.
Connector execution.
Provider-specific transaction state.
Payment lifecycle history.
Reconciliation.
Customer balances, wallets held by DragonPay, stored value, settlement balances, prefunding, reserves, liquidity, or custody of customer funds.

14. PH-05 completion criteria¶

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

DragonPay can durably represent the Party types required by supported Products using stable Tenant-scoped canonical identities;
DragonPay can durably represent the Payment Instrument types required by supported Products without changing the PH-03 canonical hierarchy;
authoritative external Party and Payment Instrument references can be resolved without uncontrolled duplication;
Party-to-Instrument ownership/authority relationships required by supported Products can be represented separately from payment-specific roles and transaction eligibility;
required validation evidence retains source, result, time, freshness, and prior evidence;
logical create/registration operations are idempotent and concurrent updates cannot silently corrupt current state;
sensitive payment-method information is minimized, protected, masked for ordinary use, and unavailable through general retrieval;
PH-03 can obtain stable PH-05 references and approved transaction-time display information without copying protected payment credentials;
suspension/closure affect current/future use without rewriting historical payments;
PH-04/PH-06/PH-07 can retrieve the current Party, Payment Instrument, association, and validation facts they require without relying on Product-specific persistence structures; and
PH-05 provides the required payment-domain behavior while allowing Engineering to select proven implementation patterns for persistence, protection, APIs, validation integration, search, and concurrency.