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>
93 lines
4.0 KiB
Markdown
93 lines
4.0 KiB
Markdown
# Phase Handover — 14.5 Payment Transaction Ledger (MVP Complete)
|
||
|
||
## Metadata
|
||
|
||
| Field | Value |
|
||
| --- | --- |
|
||
| Phase ID | `payment-14.5` |
|
||
| Title | Transaction Ledger — HIGH priority MVP complete |
|
||
| Status | Complete |
|
||
| Service(s) | `payment` (Torbat Pay) |
|
||
| Version | 0.14.5.0 |
|
||
| Date | 2026-07-27 |
|
||
| ADR(s) | [ADR-010](../architecture/adr/ADR-010.md), [ADR-020](../architecture/adr/ADR-020.md), [ADR-021](../architecture/adr/ADR-021.md) |
|
||
|
||
## Summary
|
||
|
||
Completed Torbat Pay HIGH-priority MVP path **payment-14.0 through payment-14.5**: independent service on port **8012** with foundation licensing shells, BYO-PSP connections, Torbat Pay Merchant accounts, idempotent payment requests, callback/verification with replay protection, and immutable payment-domain transaction ledger distinct from Accounting journals.
|
||
|
||
## Completed Phases (this implementation batch)
|
||
|
||
| Phase | Version | Key deliverables |
|
||
| --- | --- | --- |
|
||
| `payment-14.0` | 0.14.0.0 | Service scaffold, foundation aggregates, bundles/toggles, audit, outbox |
|
||
| `payment-14.1` | 0.14.1.0 | PSP connections, routing policies, mock adapter, health test |
|
||
| `payment-14.2` | 0.14.2.0 | Merchant account lifecycle (facilitator mode) |
|
||
| `payment-14.3` | 0.14.3.0 | Payment requests, idempotency, mock initiate |
|
||
| `payment-14.4` | 0.14.4.0 | Callback ingress, verify API, paid/failed events |
|
||
| `payment-14.5` | 0.14.5.0 | PaymentTransaction + PaymentLedgerEntry (append-only) |
|
||
|
||
## Public APIs (14.5)
|
||
|
||
| Method | Path | Notes |
|
||
| --- | --- | --- |
|
||
| GET | `/health`, `/capabilities`, `/metrics` | Discovery |
|
||
| * | `/api/v1/payment-workspaces` … `/api/v1/settings` | Foundation (14.0) |
|
||
| * | `/api/v1/psp-connections`, `/api/v1/psp-routing-policies` | Bundle `payment.byo_psp.basic` |
|
||
| POST | `/api/v1/psp-connections/{id}/test` | Connection health |
|
||
| * | `/api/v1/merchant-accounts`, lifecycle actions | Bundle `payment.torbat_pay.merchant` |
|
||
| POST/GET | `/api/v1/payment-requests` | Idempotency-Key required |
|
||
| POST | `/api/v1/callbacks/{provider}/{connection_id}` | Signature + replay protection |
|
||
| POST | `/api/v1/payment-requests/{id}/verify` | Manual reconcile |
|
||
| GET | `/api/v1/payment-transactions`, `/by-source`, `/payment-ledger-entries` | Ledger queries |
|
||
|
||
## Events Published
|
||
|
||
| Event | Phase | Trigger |
|
||
| --- | --- | --- |
|
||
| `payment.request.created` | 14.3 | Request initiated |
|
||
| `payment.request.redirect_issued` | 14.3 | Mock redirect URL issued |
|
||
| `payment.request.paid` | 14.4 | Verified paid |
|
||
| `payment.request.failed` | 14.4 | Verification failed |
|
||
| `payment.transaction.recorded` | 14.5 | Ledger row on first paid |
|
||
|
||
## Permissions
|
||
|
||
Full tree under `payment.*` — see [payment-contracts.md](../reference/payment-contracts.md) §8 and `GET /api/v1/permissions/catalog`.
|
||
|
||
## Migration Notes
|
||
|
||
| Item | Detail |
|
||
| --- | --- |
|
||
| Alembic head | `0006_phase_145_ledger` |
|
||
| Upgrade | `python scripts/ensure_db.py && alembic upgrade head` |
|
||
| Compose | `payment-service` on port 8012, database `payment_db` |
|
||
|
||
## Quality Gates (all green)
|
||
|
||
- Architecture layering verified (`test_architecture.py`)
|
||
- Tenant isolation (`test_tenant_isolation.py`)
|
||
- Permissions catalog (`test_permissions.py`)
|
||
- Migrations present (`test_migration.py`)
|
||
- Security / bundle gating (`test_security.py`)
|
||
- Phase tests 14.1–14.5
|
||
- Docs version sync (`test_docs.py`)
|
||
|
||
## Known Limitations
|
||
|
||
- Mock PSP only — production PSP SDK adapters deferred
|
||
- `CREDIT_PROVIDER` rejected (422) — Torbat Credit reserved
|
||
- No refunds (14.6), splits (14.7), connectors (14.8), reconciliation (14.9)
|
||
- No Accounting journal creation inside Payment
|
||
|
||
## Next Phase
|
||
|
||
`payment-14.6` Refunds & Reversals (**LATER** priority) — requires Communication client integration.
|
||
|
||
## References
|
||
|
||
- [payment-roadmap.md](../payment-roadmap.md)
|
||
- [payment-contracts.md](../reference/payment-contracts.md)
|
||
- [service-snapshots/payment.yaml](../service-snapshots/payment.yaml)
|
||
- Service README: `backend/services/payment/README.md`
|