9fac160258
Add independent payment-service (port 8012, payment_db) with foundation licensing, BYO-PSP, merchant accounts, idempotent requests, callbacks, and immutable ledger. Co-authored-by: Cursor <cursoragent@cursor.com>
84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
# 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.
|