Skip to main content

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.

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

FromToPatternDescription
HR-PAY-03FA-20Platform Layer / APIPlaid Link (bank linking), Transfer API for ACH disbursement; credentials via @/platform/banking and supabase/functions/_shared/plaid-client.ts
FA-20HR-PAY-03WebhookPlaid Transfer webhook (TRANSFER_EVENTS_UPDATE) for payment status updates. Payload schema: See EVENT_CONTRACTS.md#fa-20-plaid-transfer-events. Status values: posted, settled, returned (maps to hr_payment_items.status).
HR-PAY-03HR-12In-AppBank 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, 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:
  • 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.