> ## 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-03: Direct Deposit & Pay Stubs — Cross-Core Integration

> Plan ID: HR-PAY-03 Status: 🟡 Phase 2 Complete — 2026-02-27 Last Updated: 2026-02-06

**Plan ID:** HR-PAY-03\
**Status:** 🟡 Phase 2 Complete — 2026-02-27\
**Last Updated:** 2026-02-06

This document describes the integration interfaces between HR-PAY-03 (Direct Deposit & Pay Stubs) and linked systems: FA-20 (Banking / Plaid) and HR-12 (Employee Self-Service).

***

## Integration Summary

| From      | To        | Pattern              | Description                                                                                                                                                                                                                                                                                        |
| --------- | --------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HR-PAY-03 | FA-20     | Platform Layer / API | Plaid Link (bank linking), Transfer API for ACH disbursement; credentials via `@/platform/banking` and `supabase/functions/_shared/plaid-client.ts`                                                                                                                                                |
| FA-20     | HR-PAY-03 | Webhook              | Plaid Transfer webhook (TRANSFER\_EVENTS\_UPDATE) for payment status updates. **Payload schema:** See [EVENT\_CONTRACTS.md#fa-20-plaid-transfer-events](./EVENT_CONTRACTS.md#fa-20-plaid-transfer-events). **Status values:** `posted`, `settled`, `returned` (maps to `hr_payment_items.status`). |
| HR-PAY-03 | HR-12     | In-App               | Bank account management and pay stub UI in employee self-service portal; HR-12 consumes pay stub data and direct-deposit setup flows                                                                                                                                                               |

***

## FA-20 (Banking / Plaid)

* **Usage:** Bank account verification (Plaid Link), ACH transfer creation, webhook for transfer status.
* **References:** [FA-20 Plaid Integration](./plaid-integration.md), shared Plaid client `supabase/functions/_shared/plaid-client.ts`.
* **Configuration:** `PLAID_CLIENT_ID`, `PLAID_SECRET`, `PLAID_ENVIRONMENT` (Deno.env in edge functions); no hardcoded credentials.
* **HR-PAY-03 responsibilities:** Use shared client for transfer create; persist `plaid_transfer_id` and status on `hr_payment_items`; handle encryption of `plaid_access_token_encrypted` and `account_number_encrypted` per HR-PAY-03 security requirements.

### Plaid Transfer (programmatic only)

Payroll uses **programmatic** Plaid Transfer only: for each payment item, the `hr-plaid-transfer-create` edge function calls `/transfer/authorization/create` then `/transfer/create` (two-step flow per Plaid docs), with an idempotency key per item. Transfer UI (one-time user-driven flows) is not used for batch payroll.

***

## HR-12 (Employee Self-Service)

* **Usage:** Employees manage bank accounts (add/verify via Plaid Link) and view pay stubs in the portal.
* **Data flow:** HR-PAY-03 provides pay stub data (from `hr_payroll_runs` / `hr_payroll_line_items`) and direct-deposit account CRUD scoped to current user; HR-12 presents UI and enforces self-service permissions.

***

## Phase 2: Check Printing (Complete — 2026-02-27)

* **Table:** `hr_payment_checks` — linked to `hr_payment_batches` and `hr_payment_items`; stores check number, print status, vendor reference, amount, payee name, pay date.
* **Payment method:** `hr_payment_items.payment_method` column (`direct_deposit` | `check`); `bank_account_id` nullable when method is `check`.
* **PDF generation:** Client-side via `jsPDF` in `src/cores/hr/services/check-pdf-generator.ts`; single PDF per batch.
* **Vendor integration:** Configurable stub; on failure: toast + inline banner with "Retry" and "Download PDF instead".
* **Permissions:** `hr.payment_checks.print`, `hr.payment_checks.manage` (seeded to `org_admin`).

***

## CROSS\_CORE\_INTEGRATIONS.md Entries

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

* **HR → FA (FA-20):** Event / Platform — Direct deposit transfers and bank linking (Plaid); HR-PAY-03 consumes FA-20 platform banking layer.
* **HR ↔ HR-12:** In-App — Direct deposit setup and pay stub access in employee self-service; HR-PAY-03 backs HR-12 flows.