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

# Capitation & PMPM Revenue Reconciliation — Integration

> Version: 1.1 Last Updated: 2026-03-02 (manual follow-up: FA journal entry guidance, deleted_at, pending contracts updated) Status: \U0001F4CB Planned Capit…

**Version:** 1.1\
**Last Updated:** 2026-03-02 (manual follow-up: FA journal entry guidance, deleted\_at, pending contracts updated)\
**Status:** 📋 Planned\
**Spec:** [PM-33 Capitation & PMPM Revenue Reconciliation](../../../specs/pm/specs/PM-33-capitation-pmpm-revenue-reconciliation.md)\
**Constitution Reference:** Section 1.2 (Core Independence), Section 1.3 (Integration Patterns)

***

## Overview

PM-33 adds capitation contract management, roster tracking (enrollment/dis-enrollment), monthly period generation, and payment reconciliation for PMPM contracts. It integrates with PM-01 (patient/member identity for roster events), PM-09 (payment posting), PM-11 (RCM dashboard — capitation revenue and utilization), PM-23 (contract terms reference), and FA (revenue recognition via `capitation_payment_received` event).

***

## Integration Points (from spec)

| Dependency | Pattern                               | Purpose                                                                      | Status                                  |
| ---------- | ------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------- |
| **PM-01**  | Data (same core)                      | Patient/member identity for `pm_capitation_roster_events.patient_id`         | 📋 Planned                              |
| **PM-09**  | Data (same core)                      | Future: link capitation payment posting to PM-09 payment records             | 📋 Deferred (MVP: PM-33 dedicated flow) |
| **PM-11**  | Data (same core)                      | Capitation revenue and utilization vs. cap in RCM dashboard                  | 📋 Planned                              |
| **PM-23**  | Data (same core)                      | Contract terms cross-reference (no FK in MVP; future: link to pm\_contracts) | 📋 Deferred                             |
| **FA**     | Event (`capitation_payment_received`) | Revenue recognition — FA consumes event for AR/revenue posting               | 📋 Planned                              |
| **PF-30**  | Platform Layer                        | Permission seeding — `pm.capitation.view`, `pm.capitation.manage`            | 📋 Planned                              |

***

## Data Source Tables (PM-33)

| Table                           | Key Columns                                                                                              | Used By                                                                    |
| ------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `pm_capitation_contracts`       | organization\_id, payer\_id, pmpm\_rate, effective\_from, effective\_to, roster\_source, deleted\_at     | Contract list (active only: `WHERE deleted_at IS NULL`), period generation |
| `pm_capitation_periods`         | contract\_id, period\_start\_date, enrolled\_member\_count, expected\_revenue, received\_revenue, status | RCM dashboard (PM-11), reconciliation                                      |
| `pm_capitation_roster_events`   | contract\_id, patient\_id, member\_id\_external (encrypted), event\_type, effective\_date, source        | Roster management, enrollment count                                        |
| `pm_capitation_reconciliations` | period\_id, expected\_amount, received\_amount, variance\_amount, variance\_disposition, reconciled\_by  | Variance tracking, audit trail                                             |

***

## Event Contract: `capitation_payment_received`

**Publisher:** PM (pm\_capitation\_reconciliations on payment post)\
**Subscriber:** FA (AR / revenue recognition)\
**Status:** 📋 Pending — EVENT\_CONTRACTS.md entry to be created as a generate-tasks task.

**Draft payload:**

```jsonc theme={null}
{
  "event": "capitation_payment_received",
  "version": "1.0",
  "payload": {
    "organization_id": "uuid",
    "contract_id": "uuid",       // → pm_capitation_contracts.id
    "period_id": "uuid",         // → pm_capitation_periods.id
    "amount": "numeric",         // received_amount
    "payment_date": "date",
    "payer_id": "uuid",          // → pm_payers.id
    "reconciliation_id": "uuid"  // → pm_capitation_reconciliations.id
  }
}
```

**Security:** Event payload must not include `member_id_external` or any PHI. `organization_id` is required for FA tenant isolation.

### FA Journal Entry Guidance (GAAP ASC 606)

Capitation revenue is recognized ratably over the **service period** (not upon cash receipt). The FA consumer of `capitation_payment_received` should post the following journal entry:

| Account                      | Dr / Cr | Amount   | Notes                                     |
| ---------------------------- | ------- | -------- | ----------------------------------------- |
| Cash / AR (asset)            | Dr      | `amount` | Cash received from MCO                    |
| Capitation Revenue (revenue) | Cr      | `amount` | Recognized for `period_id` service period |

**Period matching:** FA must use `period_id` (→ `pm_capitation_periods.period_start_date` / `period_end_date`) to post revenue to the correct accounting period. Payments received outside the service month (early or late) must still credit the revenue account for the period covered, not the cash receipt date — confirm with CFO/Controller.

**Deferred revenue consideration:** If MCO pays capitation in advance of the service month, FA may need a deferred revenue liability entry until the period begins. Confirm with FA team whether advance capitation payments occur in practice.

**FA team confirmation required (PENDING\_CONTRACTS.md):** FA team must confirm the chart of accounts structure (account codes for MCO capitation revenue, payer-specific AR) before EVENT\_CONTRACTS.md entry is finalized.

***

## Platform Layer Usage

* **PM-11:** Reads `pm_capitation_periods` (expected\_revenue, received\_revenue, status) and `pm_encounters` (encounter count vs. capitation amount) for dashboard widgets. No new event contracts; same-core data access.
* **PF-30 Permissions:** `pm.capitation.view` and `pm.capitation.manage` seeded via migration; checked via `useHasPermission` in UI.
* **`@/platform/csv`:** Bulk import pattern for CSV roster upload; column mapping derived from `pm_capitation_roster_events` schema.

***

## Integration Matrix

| From       | To    | Pattern                               | Status      | Doc                                        |
| ---------- | ----- | ------------------------------------- | ----------- | ------------------------------------------ |
| PM (PM-33) | FA    | Event (`capitation_payment_received`) | 📋 Planned  | This doc; EVENT\_CONTRACTS.md stub pending |
| PM (PM-33) | PM-11 | Data (same core)                      | 📋 Planned  | This doc                                   |
| PM (PM-33) | PM-01 | Data (same core, patient\_id FK)      | 📋 Planned  | This doc                                   |
| PM (PM-33) | PM-09 | Data (same core, future payment link) | 📋 Deferred | This doc                                   |
| PM (PM-33) | PM-23 | Data (same core, future contract FK)  | 📋 Deferred | This doc                                   |

***

## Pending Contracts

| Contract                                                | Blocked On           | What's Needed                                                                                                                                                                                                     |
| ------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| capitation\_payment\_received EVENT\_CONTRACTS.md entry | PM-33 implementation | Formalize event payload; FA team to confirm chart of accounts (capitation revenue account codes, payer-specific AR) and deferred revenue handling for advance MCO payments -- see FA Journal Entry Guidance above |
| PM-33 to PM-11 utilization query                        | PM-11 implementation | Define SQL: encounter count per contract per period vs. capitation amount; join pm\_capitation\_periods + pm\_encounters on organization\_id + period date range; confirm join key with PM-11 implementation      |

***

## Security Notes

* All four PM-33 tables are RLS-protected with `pm_has_org_access(organization_id, auth.uid())`.
* UPDATE policies include `WITH CHECK` preventing `organization_id` modification.
* `member_id_external` is PHI; encrypted at rest via pgcrypto; decrypt only via `pm_decrypt_member_id()` SECURITY DEFINER function.
* `capitation_payment_received` event must never include PHI in payload.

***

## References

* [PM-33 Spec](../../../specs/pm/specs/PM-33-capitation-pmpm-revenue-reconciliation.md)
* [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md)
* [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)
* [PM-11 Integration](./revenue-cycle-dashboard-analytics-integration.md)
* [PM-09 Integration](./payment-posting-era-processing-integration.md)
* [PM-23 Integration](./contract-fee-schedule-integration.md)