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

# Phase 2 & 3 Integration

> -PHASE-2-3-EXPANSION.md Parent -bank-reconciliation.md Status: \U0001F4DD Planned

**Spec:** [FA-06-PHASE-2-3-EXPANSION.md](../../../specs/fa/specs/FA-06-PHASE-2-3-EXPANSION.md)\
**Parent Spec:** [FA-06-bank-reconciliation.md](../../../specs/fa/specs/FA-06-bank-reconciliation.md)\
**Status:** 📝 Planned

***

## Overview

This document describes integration points for FA-06 Phase 2 (bank feed API, positive pay, multi-currency, optional ML matching) and Phase 3 (check image matching, ACH batch, credit card, investment account reconciliation). It extends the parent FA-06 integration with external providers and platform dependencies.

***

## Integration Points (from spec)

| Point                      | Type            | Consumer/Publisher                         | Status                       |
| -------------------------- | --------------- | ------------------------------------------ | ---------------------------- |
| Bank feed (Phase 2.1)      | API / Data      | FA-06 ↔ External (Plaid, Yodlee, or other) | 📝 Contract TBD per provider |
| Positive pay (Phase 2.2)   | Export (file)   | FA-06 → Bank (external)                    | 📝 Bank-specific format      |
| Multi-currency (Phase 2.3) | Data / Platform | FA-06 ↔ PF-XX (if exists) or FA-scoped     | 📝 Depends on PF             |
| FA-02 (GL), FA-03 (AP)     | Data            | As in parent FA-06 Phase 1                 | ✅ Existing                   |

***

## Platform Foundation Dependencies

* **PF-01 (Organizations):** All new tables include `organization_id`; multi-tenant.
* **PF-02 (RBAC):** Permission keys for bank feed connect/sync, positive pay export; Phase 3 keys TBD. Use `fa_is_finance_admin()` and new permission constants.
* **PF-XX (Multi-currency):** If platform provides currency service, Phase 2.3 consumes it; otherwise FA adds `currency_code` and conversion fields.

***

## External Integrations

### Bank feed provider (Phase 2.1)

* **Existing patterns:** [FA-20 Plaid Integration](./plaid-integration.md). Phase 2 expansion may use Plaid, Yodlee, or other; API contract and OAuth/credential flow to be finalized before implementation.
* **Data:** `fa_bank_feed_links` (or equivalent); transaction sync into `fa_bank_statement_lines` with source (feed vs manual). All integration secrets (API keys, client secrets, tokens) must be stored in the project's **secure environment management** (not in code, migrations, or docs). Per constitution §4.1: **"All configuration secrets MUST be stored in secure environment management."** The `credentials_ref` column in `fa_bank_feed_links` references the secret key (identifier); no credential values are stored in the database. See parent FA-06 §11 Security for credential-handling patterns.

### Positive pay (Phase 2.2)

* **Direction:** FA → Bank (export file). Format: BAI2, CSV, or bank-specific; may require per-bank templates.
* **API/Event:** Export triggered from UI; file generated by edge function or backend; audit log of file generation.

***

## Event contracts

* No new event contracts required for Phase 2/3 in this expansion. Parent FA-06 already participates in `payment_processed` (FA-03 → FA-02, PF-10, FA-06). Phase 2/3 may add events later (e.g. `bank_feed_sync_completed`) — to be documented here when implemented.

***

## API contracts

### Bank feed sync

* **Provider:** Plaid (see [FA-20 Plaid Integration](./plaid-integration.md)). Alternative: Yodlee; contract and auth flow must be documented for the chosen provider.
* **Authentication:** OAuth 2.0 Link flow (Plaid: user links institution via Link; backend receives `public_token`, exchanges for `access_token`; store only secret key reference in `fa_bank_feed_links.credentials_ref`). API keys and client secrets in secure environment management only.
* **Request/response schemas:**
  * **Sync trigger (on-demand):** Request: `{ "bank_feed_link_id": "uuid", "organization_id": "uuid" }`. Response 200: `{ "job_id": "uuid", "status": "started" }`. Response 4xx: `{ "error": "code", "message": "sanitized message" }`.
  * **Sync status:** Request: GET with `job_id` (or equivalent). Response 200: `{ "status": "completed" | "failed" | "in_progress", "synced_at": "ISO8601", "transactions_count": number }`. Error format: `{ "error": "code", "message": "sanitized message" }`.
* **Example error codes:** `invalid_link`, `provider_error`, `rate_limited`, `unauthorized`.

### Positive pay export

* **Request:** `{ "bank_account_id": "uuid", "date_from": "YYYY-MM-DD", "date_to": "YYYY-MM-DD" }` (or query params). Requires `organization_id` from auth context.
* **Response:** File download. MVP format: **CSV**. Structure: header row with required fields (e.g. `check_number`, `amount`, `payee_name`, `issue_date`); one row per check. BAI2 and bank-specific formats to be added per integration roadmap (see [FA-06-PHASE-2-3-EXPANSION.md](../../../specs/fa/specs/FA-06-PHASE-2-3-EXPANSION.md) Clarifications).
* **Required fields (MVP CSV):** At minimum: check number, amount, payee (or payee name), date. Exact column names and order to be defined in migration/task generation.
* **Error format:** 4xx response body: `{ "error": "code", "message": "sanitized message" }` (e.g. `invalid_account`, `date_range_invalid`, `no_data`).

### Pre-Implementation Checklist

Before creating generate-tasks for Phase 2.1/2.2, ensure:

* [ ] **Bank feed sync:** Provider (e.g. Plaid) selected and named; OAuth/API authentication flow documented; request/response schemas for sync trigger and status documented (see **Bank feed sync** above).
* [ ] **Positive pay export:** Request/response (or file) contract documented; positive pay file format (MVP CSV) and structure/required fields documented (see **Positive pay export** above).

***

## Security and compliance

* Bank feed credentials: store per platform secret/PII guidelines; never log credentials.
* Positive pay file: contains check details; access control and audit log required.
* Multi-currency: no additional regulatory mapping in this expansion; see [FA-06-PHASE-2-3-EXPANSION.md](../../../specs/fa/specs/FA-06-PHASE-2-3-EXPANSION.md) § Regulatory & Compliance Requirements.

***

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