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, ADR-020, ADR-021 |
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 §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
9fac160258