# 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)