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.

Spec: FA-06-PHASE-2-3-EXPANSION.md
Parent Spec: 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)

PointTypeConsumer/PublisherStatus
Bank feed (Phase 2.1)API / DataFA-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 / PlatformFA-06 ↔ PF-XX (if exists) or FA-scoped📝 Depends on PF
FA-02 (GL), FA-03 (AP)DataAs 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. 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). 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 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 § Regulatory & Compliance Requirements.
Last Updated: 2026-02-27