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