TorbatYar/docs/phase-handover/phase-pay-arch.md

# Phase Handover — Pay-Arch Payment Architecture Prerequisites

## Metadata

| Field | Value |
| --- | --- |
| Phase ID | `payment-arch` |
| Title | Payment Architecture Prerequisites |
| Status | Complete |
| Service(s) | `payment` (architecture only) |
| Version | n/a (docs-only) |
| Date | 2026-07-27 |
| ADR(s) | [ADR-021](../architecture/adr/ADR-021.md) (extends [ADR-020](../architecture/adr/ADR-020.md)) |

## Summary

Finalized Torbat Pay architectural prerequisites: three-layer licensing (Core entitlement → Payment bundles → feature toggles), provider assignment without code changes, versioned v1 contracts for current and future flows, and verified compatibility with Core, Identity, Tenant, Accounting, CRM, Communication, Hospitality, Delivery, Sports Center, and Marketplace.

## Architectural artifacts

| Artifact | Path |
| --- | --- |
| ADR-021 | [ADR-021.md](../architecture/adr/ADR-021.md) |
| Contract reference | [payment-contracts.md](../reference/payment-contracts.md) |
| Roadmap (updated) | [payment-roadmap.md](../payment-roadmap.md) |
| Module boundaries | [module-boundaries.md](../architecture/module-boundaries.md) |
| Event catalog | [event-catalog.md](../reference/event-catalog.md#payment-platform-planned) |
| Services contracts | [services-contracts.md](../reference/services-contracts.md) |

## Contract versions locked (v1)

| Contract | Phase | Status |
| --- | --- | --- |
| PaymentIntentContract | 14.3 | Schema locked |
| CheckoutSessionContract | 14.8 | Schema locked |
| CallbackIngressContract | 14.4 | Schema locked |
| SettlementIntentContract | 14.9 | Schema locked |
| RefundIntentContract | 14.6 | Reserved |
| SplitAllocationContract | 14.7 | Reserved |
| SubscriptionBillingContract | Future | Reserved |
| WalletTopUpContract | Future | Reserved |
| InstallmentPlanContract | Future | Reserved — **Payment schedule shell only** |
| CreditProviderAdapter / CreditAuthorizationContract | Future | Reserved — Torbat Credit via CREDIT_PROVIDER |

## Torbat Credit reservation (post-arch patch)

- Future service `credit` / **Torbat Credit** reserved; `credit_db`; `credit.*` events owned by Credit service only
- Payment source `CREDIT_PROVIDER` reserved in contracts — not implemented
- Reference fields: `credit_provider_id`, `financing_reference`, `credit_authorization_reference`, `installment_contract_reference`
- Payment invokes Torbat Credit via **CreditProviderAdapter** (same pattern as PSP)
- Installment calculation / scoring / KYC / BNPL / financing = **Torbat Credit exclusive**

## Compatibility verification

| Service | Result | Notes |
| --- | --- | --- |
| Core | ✅ | L1 `payment.module.enabled`; `feature_access.changed` |
| Identity | ✅ | Payer `user_ref` only |
| Tenant | ✅ | Workspace per Core tenant id |
| Accounting | ✅ | SettlementIntent events; no journals in Payment |
| CRM | ✅ | `contact_ref` on payer |
| Communication | ✅ | Notify client for receipts/refunds |
| Hospitality | ✅ | POS/QR refs; no PSP ownership long-term |
| Delivery | ✅ | Optional COD ref |
| Sports Center | ✅ | Membership payment refs |
| Marketplace | ✅ | Checkout + splits via contracts |

No existing service code was modified.

## Foundation scope additions for 14.0

Phase `payment-14.0` MUST implement (per architecture):

- `PaymentBundleDefinition`, `TenantPaymentBundle`
- `PaymentFeatureToggle`
- `PaymentProviderAssignment` (shell)
- Core entitlement check client (stub)
- Bundle-gated permissions and `/capabilities`

## Known limitations

- No `backend/services/payment` code yet
- Vertical connector **clients** not implemented in Hospitality/Marketplace (Payment 14.8 / vertical phases)
- International PSP adapters not registered
- Core `payment.module.enabled` feature seed may be added at 14.0 wiring time (Core change in Payment phase only)

## Next Phase Entry

| Field | Value |
| --- | --- |
| Recommended next phase | `payment-14.0` Payment Foundation |
| Blockers | None |
| Required reads | This handover + [payment-contracts.md](../reference/payment-contracts.md) + [ADR-021](../architecture/adr/ADR-021.md) + [phase-14-0-payment-foundation.md](../phases/Payment/phase-14-0-payment-foundation.md) |

## Completion Sign-Off

- [x] ADR-021 accepted
- [x] All contracts documented
- [x] Manifests, snapshot, registry, project index updated
- [x] No business code; no existing services modified
- [x] payment-14.0 NOT implemented

---

## Addendum — Torbat Credit reservation (post payment-arch patch)

**Date:** 2026-07-27 · **Scope:** Documentation only · **No implementation**

### Reserved future service

| Field | Value |
| --- | --- |
| Service id | `credit` |
| Commercial product | **Torbat Credit** |
| Database | `credit_db` (reserved) |
| Event namespace | `credit.*` (reserved for Torbat Credit — Payment does not publish) |

### Payment architecture patches

1. **External Credit Providers** — Payment registry recognizes `CreditProviderRegistration` alongside PSP catalog.
2. **Payment source `CREDIT_PROVIDER`** — reserved in routing policy and PaymentIntent v1; not implemented.
3. **Opaque reference fields** on intents/transactions: `credit_provider_id`, `financing_reference`, `credit_authorization_reference`, `installment_contract_reference`.
4. **InstallmentPlanContract** (Payment) = schedule shell only. Scoring, KYC, BNPL, financing calculation = **Torbat Credit exclusive**.
5. **CreditProviderAdapter** — Payment calls Torbat Credit using the **same provider adapter pattern as PSPs** when implemented.

### Updated artifacts

- [ADR-021 §12](../architecture/adr/ADR-021.md)
- [payment-contracts.md](../reference/payment-contracts.md) — §4.9–4.11, PaymentIntent credit fields
- [payment-roadmap.md](../payment-roadmap.md) — Torbat Credit section
- [payment.yaml](../service-snapshots/payment.yaml) — snapshot_version 3

No completed business phases modified. No `credit` service registration in manifests (future phase).

## Related Documents

- [Payment Roadmap](../payment-roadmap.md)
- [Service Snapshot](../service-snapshots/payment.yaml)
- [Phase Handover Pay-Reg](phase-pay-reg.md)