> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Patient Payment Plans & Collections — Integration Documentation

> Feature ID: PM-45 Owner: PM (Practice Management) Created: 2026-04-08 Status: 📝 Planned

**Feature ID:** PM-45\
**Owner:** PM (Practice Management)\
**Created:** 2026-04-08\
**Status:** 📝 Planned

***

## Integration Overview

PM-45 integrates with FA (Fund Accounting) for write-off financial adjustments, PF-10 for notifications/reminders, PM-16 for statement data, and PM-09 for payment posting context.

***

## Event Contracts

### Published Events

#### `pm.payment_plan.created`

* **Publisher:** PM (PM-45)
* **Subscribers:** FA (AR tracking)
* **Channel:** Platform event bus
* **Payload:**
  ```typescript theme={null}
  {
    payment_plan_id: string;
    patient_id: string;
    total_balance: number;
    organization_id: string;
  }
  ```
* **Idempotency Key:** `payment_plan_id`
* **Status:** 📝 Planned

#### `pm.bad_debt_writeoff.approved`

* **Publisher:** PM (PM-45)
* **Subscribers:** FA (posts financial adjustment to general ledger)
* **Channel:** Platform event bus
* **Payload:**
  ```typescript theme={null}
  {
    writeoff_id: string;
    patient_id: string;
    patient_account_id: string;
    writeoff_amount: number;
    reason_code: string;
    financial_adjustment_id?: string;
    approved_by: string;
    approval_date: string; // ISO 8601
    organization_id: string;
  }
  ```
* **Idempotency Key:** `writeoff_id`
* **Status:** 📝 Planned

### Consumed Events

None. PM-45 reads PM-16 statement data via direct same-core data access (see Cross-Core Dependencies below).

***

## Platform Integration Layer Dependencies

| Dependency                    | Integration Type                            | Purpose                                                      |
| ----------------------------- | ------------------------------------------- | ------------------------------------------------------------ |
| PF-01 (Organizations & Sites) | Direct                                      | Multi-tenant context, org/site timezone for cron scheduling  |
| PF-02 (RBAC)                  | Direct                                      | Role-based access control for plans, collections, write-offs |
| PF-10 (Notifications)         | Platform Layer (`@/platform/notifications`) | SMS and email reminders at each aging tier                   |
| PF-30 (Permissions)           | Direct                                      | Permission key infrastructure for all PM-45 actions          |

***

## Cross-Core Dependencies

| Core  | Direction     | Dependency                      | Notes                                                                                                                                                                                                                   |
| ----- | ------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| FA    | PM → FA       | Write-off financial adjustments | Event-driven via `pm.bad_debt_writeoff.approved`; FA posts GL adjustment                                                                                                                                                |
| PM-09 | PM-45 ← PM-09 | Patient balance data            | Synchronous data access: PM-45 reads patient AR balances from PM-09 posted payment data. See [API\_CONTRACTS.md](./API_CONTRACTS.md#pm-45--pm-09-patient-ar-balance) for API contract details (📝 planned).             |
| PM-16 | PM-45 → PM-16 | Statement data                  | Synchronous data access: PM-45 provides payment plan summary fields for PM-16 statement rendering. See [API\_CONTRACTS.md](./API_CONTRACTS.md#pm-45--pm-16-payment-plan-summary) for API contract details (📝 planned). |
| PM-32 | PM-32 → PM-45 | Charity care routing            | Patients not qualifying for PM-32 charity care routed to PM-45 payment plans                                                                                                                                            |

***

## Validation Checklist

* [ ] Event contracts documented with payload schemas
* [ ] Idempotency keys specified for all published events
* [ ] Platform layer dependencies confirmed available
* [ ] FA subscriber implementation status tracked
* [ ] Security: no PHI in event payloads beyond minimum necessary

***

**Last Updated:** 2026-04-08