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>
6.1 KiB
6.1 KiB
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 (extends ADR-020) |
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 |
| Contract reference | payment-contracts.md |
| Roadmap (updated) | payment-roadmap.md |
| Module boundaries | module-boundaries.md |
| Event catalog | event-catalog.md |
| Services contracts | 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_PROVIDERreserved 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,TenantPaymentBundlePaymentFeatureTogglePaymentProviderAssignment(shell)- Core entitlement check client (stub)
- Bundle-gated permissions and
/capabilities
Known limitations
- No
backend/services/paymentcode yet - Vertical connector clients not implemented in Hospitality/Marketplace (Payment 14.8 / vertical phases)
- International PSP adapters not registered
- Core
payment.module.enabledfeature 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 + ADR-021 + phase-14-0-payment-foundation.md |
Completion Sign-Off
- ADR-021 accepted
- All contracts documented
- Manifests, snapshot, registry, project index updated
- No business code; no existing services modified
- 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
- External Credit Providers — Payment registry recognizes
CreditProviderRegistrationalongside PSP catalog. - Payment source
CREDIT_PROVIDER— reserved in routing policy and PaymentIntent v1; not implemented. - Opaque reference fields on intents/transactions:
credit_provider_id,financing_reference,credit_authorization_reference,installment_contract_reference. - InstallmentPlanContract (Payment) = schedule shell only. Scoring, KYC, BNPL, financing calculation = Torbat Credit exclusive.
- CreditProviderAdapter — Payment calls Torbat Credit using the same provider adapter pattern as PSPs when implemented.
Updated artifacts
- ADR-021 §12
- payment-contracts.md — §4.9–4.11, PaymentIntent credit fields
- payment-roadmap.md — Torbat Credit section
- payment.yaml — snapshot_version 3
No completed business phases modified. No credit service registration in manifests (future phase).