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

# HR-PAY-02: Payroll Deductions Management — Cross-Core Integration

> Spec Reference: HR-PAY-02 Payroll Deductions Management Status: 🟡 Partial — Phase 1 (schema/RLS) complete; event contracts (HR-11 → HR-PAY-02) planned but not…

**Spec Reference:** [HR-PAY-02 Payroll Deductions Management](../../../specs/hr/specs/HR-PAY-02-payroll-deductions.md)\
**Status:** 🟡 Partial — Phase 1 (schema/RLS) complete; event contracts (HR-11 → HR-PAY-02) planned but not yet implemented\
**Last Updated:** 2026-02-27

This document summarizes integration points between HR-PAY-02 (Payroll Deductions) and HR-07, HR-PAY-01, HR-11, and PF-11. Event payloads are defined in EVENT\_CONTRACTS.md; API/flow details are expanded in the spec Implementation Plan and Phase 2/3 expansion.

***

## Integration Summary

| From      | To        | Pattern                     | Description                                                                                                                                                                                        |
| --------- | --------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HR-11     | HR-PAY-02 | Event                       | Benefit enrollment created/terminated → auto-create or end-date deductions. Payloads in [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md#hr-11--hr-pay-02-benefit-enrollment-events-payroll-deductions). |
| HR-PAY-02 | HR-07     | Data (inbound to HR-07)     | Payroll run reads active employee deductions, applies order and caps, creates `hr_payroll_deduction_items` on finalization.                                                                        |
| HR-PAY-02 | HR-PAY-01 | Data (inbound to HR-PAY-01) | Pre-tax deductions reduce federal taxable income before tax calculation; HR-PAY-01 receives adjusted taxable base.                                                                                 |
| HR-PAY-02 | PF-11     | Outbound                    | Court order PDFs stored in `pf-documents`; link via `custom_fields` on `hr_employee_deductions`.                                                                                                   |

***

## HR-11 (Benefits Administration) — Event

* **Events:** `hr.benefit_enrollment.created`, `hr.benefit_enrollment.terminated`
* **Payload schema and subscriber:** [EVENT\_CONTRACTS.md § HR-11 / HR-PAY-02](./EVENT_CONTRACTS.md#hr-11--hr-pay-02-benefit-enrollment-events-payroll-deductions)
* **HR-PAY-02 behavior:** On created → create `hr_employee_deductions` row (amount from payload, pre\_tax flag); on terminated → set `end_date` on matching deduction. Reconciliation utility (Phase 4) can match existing deductions to enrollments.

***

## HR-07 (Payroll Processing) — Data

* **Usage:** Payroll run (wizard) loads active deductions per employee, calls deduction calculation service (Phase 3), shows breakdown in preview step, and on finalization writes `hr_payroll_deduction_items` and updates `hr_employee_deductions.ytd_amount`.
* **Data consumed:** `hr_deduction_types`, `hr_employee_deductions` (effective date filter, status = active). No new API contract; same-core read via Supabase client with RLS.
* **Implementation:** See [HR-PAY-02 Implementation Plan](../../../specs/hr/specs/HR-PAY-02-payroll-deductions.md#implementation-plan) Phase 3 and [HR-PAY-02-PHASE-2-3-EXPANSION](../../../specs/hr/specs/HR-PAY-02-PHASE-2-3-EXPANSION.md#phase-3-payroll-integration-week-3).

***

## HR-PAY-01 (Tax Calculation) — Data

* **Usage:** Pre-tax deductions reduce federal (and state, where applicable) taxable income before HR-PAY-01 runs. HR-07 (or deduction service) computes taxable gross after pre-tax deductions and passes it to tax calculation.
* **Contract:** In-process (same payroll run); no separate API. Flow documented in spec and expansion Phase 3.
* **Implementation:** Deduction service returns pre-tax total; payroll run subtracts from gross before calling HR-PAY-01 tax logic.

***

## PF-11 (Document Management) — Outbound

* **Usage:** Garnishment court order PDFs stored in `pf-documents` bucket with restricted access. `hr_employee_deductions.custom_fields` may store document reference (e.g., `document_id` or path).
* **Reference:** PF-11 Document Management — use platform document APIs for upload and link; no new event contract.

***

## CROSS\_CORE\_INTEGRATIONS.md

The following rows are recorded in [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md):

* **HR-11 → HR-PAY-02:** Event — Benefit enrollment created/terminated; EVENT\_CONTRACTS.md
* **HR-PAY-02 → HR-07:** Data — Payroll run consumes deductions and creates deduction items
* **HR-PAY-02 → HR-PAY-01:** Data — Pre-tax deductions reduce taxable income input to tax calculation
* **HR-PAY-02 → PF-11:** Outbound — Court order document storage and link from employee deduction record

***

**Last Updated:** 2026-02-27