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.
Version: 0.1 (stub created by spec-review 2026-04-19)
Created: 2026-04-19
Last Updated: 2026-04-19
Status: 📝 Planned (stub — to be expanded during Phase A implementation)
Spec: specs/pm/specs/PM-53-refund-recoupment-takeback-management.md
Overview
PM-53 introduces three first-class money-out / money-clawed-back workflows on top of PM-09: patient refund, payer recoupment / takeback detection, and disputed-takeback escalation to PM-29. PM-53 owns the operational data model and state machines; FA owns GL posting and is reached exclusively via event publishing to cl_pm_events. PM-37 (proposed) owns the patient liability ledger and consumes append events when it ships (Phase C, deferred).
This stub captures the canonical integration points; full payload schemas and consumer contracts will be expanded during Phase A implementation. See the spec’s Event Contracts section for authoritative payload definitions today.
Integration Points
| PF Spec | Integration Type | Description |
|---|
| PF-04 (Audit) | Direct dependency | All refund/recoupment state transitions captured in PF audit pipeline |
| PF-10 (Notifications) | Platform Integration Layer | pm.refund.approval_required notifications to tier-2/3 approvers (FR-8) |
| PF-30 (RBAC) | Direct dependency | Permission keys: pm.refunds.{view,create,approve}, pm.recoupments.{view,manage} (5 keys) |
| PF-44 (HIPAA Audit Controls) | Direct dependency | Append-only audit of refund decisions and recoupment dispositions (US-4) |
| PF-96 (Jurisdiction Profiles) | Platform Layer | Recoupment dispute window resolution via useJurisdictionProfile().recoupmentDisputeWindowDays (FR-5.3) |
Same-Core Dependencies (PM)
| PM Spec | Integration Type | Description |
|---|
| PM-09 (Payment Posting & ERA) | Data dependency / Edge Function extension | Source of pm_payments for original payment selection; ERA parser extension (process-era) detects CARC/PLB takebacks |
| PM-15 (Clearinghouse) | Co-resident in process-era | Recoupment detection lives inside the existing PM-15 ERA pipeline (no new edge function) |
| PM-23 (Contract & Fee Schedule) | Indirect data dependency (via PM-44 outputs) | Contract rate/variance interpretation for recoupment context is supplied through PM-44 outputs; PM-44 depends on PM-23, PM-53 receives context via PM-44 |
| PM-28 (Module Settings) | Data dependency | Owns pm_module_settings table; PM-53 contributes refund threshold + tier role columns |
| PM-29 (Denial & Appeals) | API / action | Disputed recoupments create pre-populated pm_claim_appeals rows (FR-5.1) |
| PM-37 (Self-Pay AR Ledger — proposed) | Event consumer (deferred) | When PM-37 ships, consumes payment_refund_issued and payer_recoupment_detected to append patient-liability ledger rows (Phase C) |
| PM-44 (ERA Reconciliation & Underpayment) | Cooperative filter | Excludes claim lines with active recoupments to avoid double-counting reversed payments (FR-6.1) |
| PM-45 (Patient Payment Plans & Collections) | Data / token dependency | Refund via card_token_reverse uses PM-45 payment-processor token from the original payment; refund may settle written-off bad debt (link maintained) |
Cross-Core Dependencies
| Core | Integration Type | Description |
|---|
| FA (Cash Receipts / GL) | Event-based (consumer) | Consumes payment_refund_issued from cl_pm_events; creates the GL journal entry; writes fa_journal_entry_id back to pm_refunds (existing batch consumer pattern from RH episode events) |
Event Contracts
Events Published
| Event | Subscribers | Payload | Idempotency Key | Purpose |
|---|
payment_refund_issued | FA Cash Receipts / GL consumer | See spec § Event Contracts for full schema | refund_id | Triggers FA GL posting and fa_journal_entry_id writeback |
payer_recoupment_detected | PM-44 (filter cooperation), FA (informational), PF-10 (AR Manager alert), PM-37 (Phase C) | See spec § Event Contracts for full schema | recoupment_id | Notifies downstream consumers of a new payer takeback |
patient_id, refund_id, original_payment_id) and amounts, but patient-linked identifiers should be treated as sensitive metadata and handled with PHI/PII-safe logging, notification, and access controls per the documentation guidelines. Additional safeguards (e.g., masking, access checks, audit logging) are recommended when UUIDs are used to correlate patient records.
Events Consumed
PM-53 does not consume cross-core events in MVP. The process-era extension reads incoming 835 segments (already processed by PM-09 / PM-15) and creates recoupment rows synchronously during ERA ingestion.
API Contracts
PM-53 does not expose new external APIs. All cross-core communication is via events. Internal frontend hooks (useRefunds, usePayerRecoupments, etc.) call Supabase RPC / table queries directly under RLS.
Permission Keys (5 keys)
| Key | Purpose |
|---|
pm.refunds.view | Read refund list and details |
pm.refunds.create | Insert pm_refunds row |
pm.refunds.approve | Insert pm_refund_approvals decision (tier 1/2/3 actions) |
pm.recoupments.view | Read recoupment queue and details |
pm.recoupments.manage | Mutate pm_payer_recoupments (accept / dispute / mark resolved) |
Pending Items (to be expanded)
These items are tracked in PENDING_CONTRACTS.md under PM-53.
References
