# Phase 14.0 — Payment Foundation

| Field | Value |
| --- | --- |
| Identifier | `payment-14.0` |
| Implementation Priority | **HIGH** |
| Status | Complete |
| Service | `payment` |
| Version (target) | 0.14.0.0 |
| Database | `payment_db` |
| API Port | 8012 |
| ADR | ADR-001, ADR-003, ADR-006, ADR-020, **ADR-021** |

> Full specification: [payment-roadmap.md](../../payment-roadmap.md#phase-14-0--payment-foundation)  
> **Required architecture reads:** [ADR-021](../../architecture/adr/ADR-021.md), [payment-contracts.md](../../reference/payment-contracts.md), [phase-pay-arch handover](../../phase-handover/phase-pay-arch.md)

## Purpose

Establish Torbat Pay as an independent enterprise microservice foundation including **three-layer licensing shells** (L2 bundles, L3 toggles), workspace enable/disable, provider assignment shells, and provider protocol stubs — no live PSP or capture flows.

## Business Scope

- Per-tenant payment workspace with `enabled` / `disabled` / `suspended` and `default_payment_mode` (`byo_psp` | `torbat_pay_merchant`).
- Payment bundle catalog and tenant bundle activation (L2).
- Feature toggles (L3) for refunds, splits, subscriptions, installments, wallet top-up (reserved).
- Provider assignment shells for routing without code changes (full routing in 14.1).

## Technical Scope

- Scaffold `backend/services/payment`; Alembic `0001_initial`.
- Aggregates: PaymentWorkspace, PaymentRole, PaymentPermission, **PaymentBundleDefinition**, **TenantPaymentBundle**, **PaymentFeatureToggle**, **PaymentProviderAssignment**, PspProviderRegistration, PaymentConfiguration, PaymentSetting, PaymentAuditLog, OutboxEvent.
- Core L1 client stub: check `payment.module.enabled`.
- Provider protocols (stubs): PspAdapter, AccountingClient, CommunicationClient, CrmClient, CoreEntitlementClient.

## Dependencies

`payment-arch`, `payment-reg`, `onboarding-4`, `ai-framework`, Core entitlement

## Out of Scope

PSP connections (14.1), merchant onboarding (14.2), payment requests (14.3+), callbacks, ledger

## Capabilities

`payment.foundation`, `payment.workspace`, `payment.bundles`, `payment.feature_toggles`, `payment.provider_assignment_shell`, `payment.psp_registry_shell`, `payment.audit`

## Permissions

Per [payment-contracts.md](../../reference/payment-contracts.md) §8 — foundation leaves only; bundle-gated leaves registered but inactive until bundles assigned.

## Events

`payment.workspace.enabled|disabled`, `payment.bundle.activated`, `payment.feature_toggle.changed`, `payment.psp_provider.registered`

## API Contracts

`/health`, `/capabilities`, `/metrics`, `/api/v1/payment-workspaces`, `/api/v1/bundle-definitions`, `/api/v1/tenant-bundles`, `/api/v1/feature-toggles`, `/api/v1/provider-assignments`, `/api/v1/psp-provider-registrations`, `/api/v1/configurations`, `/api/v1/settings`, `/api/v1/audit`

## Data Ownership

Payment sole owner of all foundation tables in `payment_db`.

## Provider Ownership

Adapter interfaces only in 14.0.

## Integration Rules

- L1 Core check before mutating APIs.
- Inactive L2 bundles hide gated routes from `/capabilities`.
- No cross-DB access; no existing service modifications.

## Quality Gates

Architecture, tenant isolation, bundle isolation, permissions, migration, dependency, security, docs.

## Definition of Done

Service boots on 8012; foundation + licensing shells tested; contracts unchanged from payment-arch.

## Future Compatibility

All v1 contracts in [payment-contracts.md](../../reference/payment-contracts.md) remain stable; 14.0 tables include fields for `region`, `currency`, facilitator mode per ADR-021.