> ## 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. # Integration Documentation: PM-53 โ€” Refund, Recoupment & Takeback Management > 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 impโ€ฆ **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`](../../../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](../../../specs/pm/specs/PM-53-refund-recoupment-takeback-management.md#event-contracts) section for authoritative payload definitions today. *** ## Integration Points ### Platform Foundation (PF) Dependencies | 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](../../../specs/pm/specs/PM-53-refund-recoupment-takeback-management.md#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 | **PHI minimization:** Both payloads contain only opaque UUIDs (`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) * [ ] Concrete consumer contract for FA Edge Function (`fa-consume-pm-payment-events` or new `fa-consume-pm-refund-events`). * [ ] Phase C contract with PM-37 (deferred โ€” populated when PM-37 ships). * [ ] Notification template `pm.refund.approval_required` payload schema and PF-10 registration. * [ ] Jurisdiction profile schema additions for `recoupmentDisputeWindowDays` (PF-96 cross-link). These items are tracked in [`PENDING_CONTRACTS.md`](./PENDING_CONTRACTS.md) under PM-53. *** ## References * **Spec:** [`specs/pm/specs/PM-53-refund-recoupment-takeback-management.md`](../../../specs/pm/specs/PM-53-refund-recoupment-takeback-management.md) * **Cross-core matrix:** [`CROSS_CORE_INTEGRATIONS.md`](./CROSS_CORE_INTEGRATIONS.md) โ€” PM-53 row registered after PM-44. * **Event contracts (general):** [`EVENT_CONTRACTS.md`](./EVENT_CONTRACTS.md) * **Adjacent integrations:** * [`PM-09-payment-posting-era-processing-INTEGRATION.md`](./payment-posting-era-processing-integration.md) * [`PM-44-era-reconciliation-underpayment-detection-INTEGRATION.md`](./era-reconciliation-underpayment-detection-integration.md) * [`PM-45-patient-payment-plans-collections-INTEGRATION.md`](./patient-payment-plans-collections-integration.md) * [`PF-96-medicaid-state-compliance-configuration-INTEGRATION.md`](./medicaid-state-compliance-configuration-integration.md) * **Lite alternatives (superseded 2026-04-19):** [`PM-09-EN-11`](../../../specs/pm/specs/PM-09-EN-11-refund-workflow.md), [`PM-09-EN-15`](../../../specs/pm/specs/PM-09-EN-15-payer-overpayment-takeback.md)