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>
124 lines
4.8 KiB
Markdown
124 lines
4.8 KiB
Markdown
# Phase Handover — Pay-Reg Payment Platform Registration
|
||
|
||
## Metadata
|
||
|
||
| Field | Value |
|
||
| --- | --- |
|
||
| Phase ID | `payment-reg` |
|
||
| Title | Payment Platform Registration |
|
||
| Status | Complete |
|
||
| Service(s) | `payment` (registered; not yet implemented) |
|
||
| Commercial Product | Torbat Pay |
|
||
| Version | n/a (docs-only) |
|
||
| Date | 2026-07-27 |
|
||
| ADR(s) | [ADR-020](../architecture/adr/ADR-020.md), [ADR-021](../architecture/adr/ADR-021.md) |
|
||
|
||
## Reusable Components
|
||
|
||
| Component | Location | Reuse notes |
|
||
| --- | --- | --- |
|
||
| Platform registration pattern | Same as Delivery DP-Reg, Experience XP-Reg | Docs + ADR + manifests before code |
|
||
| Provider adapter pattern | Communication service PSP-like registry | PSP adapters in Payment only |
|
||
| Service template | [service-template.md](../ai-framework/service-template.md) | Use in Phase 14.0 |
|
||
| Phase template | [phase-template.md](../ai-framework/phase-template.md) | Use for 14.x phase docs |
|
||
|
||
## Public APIs
|
||
|
||
| Method | Path | Auth / Permission | Notes |
|
||
| --- | --- | --- | --- |
|
||
| — | — | — | N/A — registration only; APIs begin in `payment-14.0` |
|
||
|
||
Planned surfaces (not implemented): `/health`, `/capabilities`, `/metrics`, `/api/v1/*` under `payment.*` permissions.
|
||
|
||
## Events
|
||
|
||
| Event type | Domain / Integration | Payload summary | Version |
|
||
| --- | --- | --- | --- |
|
||
| `payment.*` (planned) | Payment domain | Publish-only; catalog grows per phase | Planned |
|
||
|
||
## Extension Points
|
||
|
||
| Extension point | How to extend | Forbidden uses |
|
||
| --- | --- | --- |
|
||
| PSP adapters | Register in Payment adapter registry | Verticals calling ZarinPal/IDPay directly |
|
||
| Facilitator mode | Merchant accounts + platform credentials | Storing PSP secrets in Core or vertical DBs |
|
||
| Vertical connectors | Versioned checkout contracts (14.8) | Shared DB with Hospitality/Marketplace |
|
||
| Accounting intents | Events/API for posting intents | JournalEntry creation inside Payment |
|
||
| Fraud hooks | Optional rule registry (14.10) | Hard dependency for capture |
|
||
|
||
## Known Limitations
|
||
|
||
- No `backend/services/payment` code yet — Phase 14.0
|
||
- No Alembic migrations yet
|
||
- No compose wiring / runtime health yet
|
||
- No live PSP integrations until 14.1+
|
||
- Payment capture path incomplete until 14.3–14.5
|
||
- International PSPs documented as future-ready only
|
||
- Phase numeric 14.x shared with Beauty Business track — always use manifest prefix `payment-14.x`
|
||
|
||
## Migration Notes
|
||
|
||
| Item | Detail |
|
||
| --- | --- |
|
||
| Alembic revision(s) | N/A (docs-only) |
|
||
| Upgrade steps | N/A |
|
||
| Downgrade support | N/A |
|
||
| Data backfill | N/A |
|
||
| Breaking changes | None |
|
||
|
||
## Dependencies
|
||
|
||
| Dependency | Type | Required for |
|
||
| --- | --- | --- |
|
||
| AI Framework | Docs | Development loop / gates |
|
||
| ADR-001 / 003 / 006 / 010 / 012 / 020 / 021 | Architecture | Boundaries |
|
||
| Core Platform | Service | Entitlement (from 14.0) |
|
||
| Communication | Service | Receipt notify (from 14.6+) |
|
||
| Accounting | Service | Posting intents (from 14.9) |
|
||
|
||
## Discovery Record (Registration)
|
||
|
||
| Field | Value |
|
||
| --- | --- |
|
||
| Discovery date | 2026-07-27 |
|
||
| Baseline | No payment service; verticals hold payment shells (e.g. Hospitality `pos_payment`) without PSP |
|
||
| Gap | Central payment platform missing |
|
||
| Promoted scope | Registration + full roadmap 14.0–14.10 |
|
||
| Excluded | Implementation of 14.0; modifications to existing services |
|
||
|
||
## Next Phase Entry
|
||
|
||
| Field | Value |
|
||
| --- | --- |
|
||
| Recommended next phase | `payment-14.0` Payment Foundation |
|
||
| Blockers for next phase | None for scaffold |
|
||
| Implementation Priority | **HIGH** (14.0–14.5) |
|
||
|
||
What the next phase must read and assume:
|
||
|
||
1. [phase-pay-arch handover](../phase-handover/phase-pay-arch.md) + [payment-roadmap.md](../payment-roadmap.md) Phase 14.0 section
|
||
2. [ADR-020](../architecture/adr/ADR-020.md) + [ADR-021](../architecture/adr/ADR-021.md)
|
||
3. [payment-contracts.md](../reference/payment-contracts.md)
|
||
4. Updated [module-registry.md](../module-registry.md#payment) / manifests
|
||
5. Implement foundation shells only — no PSP capture, callbacks, or ledger engines
|
||
|
||
## Completion Sign-Off
|
||
|
||
- [x] Quality gates passed (documentation / architecture / manifest / cross-reference)
|
||
- [x] Tests green (N/A — docs-only)
|
||
- [x] Documentation updated
|
||
- [x] Progress / next-steps / registries / project index updated
|
||
- [x] Service snapshot generated (registration baseline)
|
||
- [x] No existing business services modified
|
||
- [x] Phase 14.0 NOT implemented (by design)
|
||
|
||
## Related Documents
|
||
|
||
- [Payment Roadmap](../payment-roadmap.md)
|
||
- [Phase Area](../phases/Payment/README.md)
|
||
- [ADR-020](../architecture/adr/ADR-020.md)
|
||
- [Phase Manifest](../ai-framework/phase-manifest.yaml)
|
||
- [Service Manifest](../ai-framework/service-manifest.yaml)
|
||
- [Project Index](../ai-framework/project-index.yaml)
|
||
- [Quality Gates](../ai-framework/quality-gates.md)
|