Fondo CI Integration

Overview

Set up CI/CD for Fondo startup tax and bookkeeping integrations: run unit tests with mocked filing and compliance data on every PR, validate live API connectivity for tax filing status and bookkeeping records on merge to main. Fondo handles R&D tax credits, quarterly filings, and ongoing bookkeeping, so CI pipelines verify compliance data transforms, filing deadline monitoring, and automated alert workflows.

Prerequisites

• Protected CI environments, scoped secrets available only to trusted jobs, and synthetic finance fixtures.
• A finance owner and deployment/rollback approver for any authenticated staging verification.

Instructions

1. Run unit/schema tests with fictional data and no credentials on pull requests.
2. Restrict authenticated checks to protected branches, use minimum scopes, and redact all output.
3. Validate destination, idempotency, failure handling, and professional-review boundaries before promotion.

Output

Publish a CI receipt with commit SHA, fixture version, checks run, aggregate result, approval, and redacted failure reference. Exclude financial data and credentials.

Examples

A pull request tests a fictional filing-status mapping without secrets. A protected job validates one synthetic staging record and blocks promotion if an unexpected field, destination, or professional-review gap appears.

GitHub Actions Workflow

# .github/workflows/fondo-ci.yml
name: Fondo CI
on:
  pull_request:
    paths: ['src/fondo/**', 'tests/**']
  push:
    branches: [main]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm test -- --reporter=verbose

  integration-tests:
    if: github.ref == 'refs/heads/main'
    needs: unit-tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run test:integration
        env:
          FONDO_API_KEY: ${{ secrets.FONDO_API_KEY }}

Mock-Based Unit Tests

// tests/fondo-service.test.ts
import { describe, it, expect, vi } from 'vitest';
import { checkFilingDeadlines } from '../src/fondo-service';

vi.mock('../src/fondo-client', () => ({
  FondoClient: vi.fn().mockImplementation(() => ({
    listFilings: vi.fn().mockResolvedValue({
      filings: [
        { id: 'fil_q1', type: '941', quarter: 'Q1-2026', status: 'filed', due_date: '2026-04-30' },
        { id: 'fil_q2', type: '941', quarter: 'Q2-2026', status: 'pending', due_date:…

Fondo Common Errors

Overview

Quick reference for common Fondo platform issues and their resolutions.

Prerequisites

• A finance owner, opaque case ID, redacted telemetry, and an authorized support path.
• A safe synthetic or read-only reproduction; do not use live tax/payroll records for routine diagnostics.

Instructions

1. Classify the issue as access, sync, categorization, reconciliation, filing workflow, or data-retention concern.
2. Reproduce with the smallest permitted probe, then review configuration, integration scope, source mapping, and queue state.
3. Apply a reversible correction, record the review decision, and verify a safe failure path.
4. Escalate possible financial-data exposure or filing-impacting discrepancies to the finance owner.

Output

Return a redacted diagnostic receipt with case ID, category, safe reproduction, action, verification, owner, and follow-up. Never include transactions, payroll, tax documents, account details, or credentials.

Error Handling

• Do not make tax eligibility, filing, or payment decisions from an automated error flow.
• Quarantine mismatches for professional review and use bounded retries for transient integration failures.
• Stop sharing evidence if it contains sensitive financial data or secrets.

Examples

Use a fictional categorization discrepancy, record only an aggregate error category, correct the mapping in a test fixture, and route the result to the authorized finance reviewer before any live change.

Integration Sync Issues

Categorization Errors

R&D Credit Issues

Fondo Core Workflow A: Monthly Bookkeeping

Overview

The primary Fondo workflow: automated monthly bookkeeping close. Fondo's CPA team handles reconciliation, categorization, and financial statement preparation. Your role is to answer questions and review deliverables.

Prerequisites

• A designated finance owner, close calendar, approved source systems, access controls, and professional-review responsibility.
• Documented retention and correction process; use synthetic data for automation tests.

Instructions

1. Confirm source completeness and reconciliation state before treating a close as ready for review.
2. Respond to questions through the authorized finance workflow, preserving supporting evidence in approved systems.
3. Review statements and exceptions with the responsible professional; correct discrepancies using the documented process.
4. Publish only approved, access-controlled reports and record the review state.

Output

Create a close receipt with period, source-completeness result, reviewer, open exceptions, report approval state, and next action. Do not include ledger rows, accounts, payroll, tax data, or credentials.

Examples

Use a fictional month-end ledger summary to test the review workflow, create one deliberate reconciliation exception, and verify the close remains pending until the finance reviewer resolves it.

Monthly Close Timeline

Deliverables

Financial Statements (Monthly)

Key Metrics (Auto-Calculated)

Dashboard > Financial Overview

Monthly Burn Ra…

Fondo Core Workflow B: R&D Tax Credits

Overview

Claim R&D tax credits through Fondo. Startups with US W-2 employees doing qualifying R&D can offset up to $500,000/year in payroll taxes (FICA). Fondo's CPA team prepares the Form 6765 study.

Prerequisites

• An authorized finance/tax owner, current professional guidance, complete source records, and a retention/access policy.
• A reviewed scope for any calculator or export; this workflow does not determine eligibility or replace tax advice.

Instructions

1. Gather approved source evidence and classify activities/expenses for review without altering originals.
2. Use an opaque case identifier and aggregate counts for workflow tracking; keep payroll, tax, and employee records in authorized systems.
3. Reconcile inputs with the responsible finance professional, document assumptions and exceptions, and obtain sign-off before filing or payment actions.
4. Preserve an audit trail and follow the organization's retention and correction process for any discrepancy.

Output

Create a review receipt with period, case ID, source-system references, owner, open questions, professional-review status, and next action. Do not include employee, payroll, tax-return, or bank details.

Examples

Use a fictional project and aggregate cost buckets to exercise the evidence-collection checklist. Record unresolved classification questions for the finance reviewer and confirm no filing, calculation, or payroll action is generated from the test.

R&D Credit Calculation

Qualifying R&D Expenses:
  W-2 wages for R&D employees:        $480,000
  Contractor payments (65%):           $78,000
  Cloud compute (AWS/GCP):             $36,000
  Software tools for R&D:              $12,000
                                       --------
  Total Qualified Research Expenses:   $606,000

Credit Rate (Alternative Simplified):  ~6-8%
Estimated R&D Credit:                  ~$42,000

Qualifying Activities

Timeline

Fondo Cost Tuning

Overview

Maximize Fondo ROI: the R&D tax credit alone should exceed the annual Fondo cost for most startups.

Prerequisites

• Current contract/billing information reviewed by the finance owner and an approved decision process.
• Aggregate usage data only; individual employee, payroll, tax, and account data stays in authorized systems.

Instructions

1. Measure cost and workflow value using current data and document assumptions for review.
2. Consider operational simplification only when it preserves compliance, retention, reconciliation, and professional-review requirements.
3. Obtain finance approval before changing plan, scope, integrations, or tax workflow.

Output

Record the measurement period, aggregate inputs, decision owner, approved action, verification date, and exceptions. This is not a tax, legal, or financial conclusion.

Error Handling

• Stop if data is incomplete or a proposed saving reduces auditability, access controls, or required review.
• Route eligibility or filing questions to the designated professional rather than automating a decision.
• Keep evidence redacted and reversible.

Examples

Compare two fictional aggregate workload profiles, have the finance owner approve the selected option, and verify no account, payroll, or tax information was copied into the analysis.

ROI Analysis

Fondo TaxPass cost:      ~$4,000-8,000/year (varies by plan)
Average R&D credit:      $21,000/year
Bookkeeping savings:     $12,000-24,000/year (vs. dedicated bookkeeper)
Tax prep savings:         $5,000-10,000/year (vs. separate CPA)
                         ------------------
Net ROI:                 $24,000-47,000/year benefit

Maximize R&D Credits

Choose the Right Plan

Fondo Debug Bundle

Overview

Collect Fondo API connectivity status, filing compliance state, integration health, and accounting sync diagnostics into a single archive for Fondo support tickets. This bundle helps troubleshoot bank connection failures, reconciliation discrepancies, R&D credit calculation issues, and tax filing errors.

Prerequisites

• An incident owner, approved secure evidence store, retention deadline, and redaction rules for financial, tax, payroll, and credential data.
• An opaque correlation ID and a safe sandbox/read-only diagnostic path.

Instructions

1. Capture runtime/configuration references, aggregate health, opaque case IDs, and error categories only.
2. Review generated files for account data, tax records, payroll details, exports, and secrets before encrypting the bundle.
3. Restrict evidence access to the approved incident/finance responders and delete or retire it according to policy.

Output

Create a redacted bundle index with correlation ID, artifact list, access owner, retention date, reproduction result, and next action. Store any sensitive originals only in the approved secure location.

Error Handling

• Stop collection if a secret or financial record is present; rotate credentials if exposure is possible.
• Record missing diagnostics rather than expanding collection beyond the authorized scope.
• Escalate suspected data exposure or filing-impacting discrepancy to the designated finance/incident owner.

Examples

For a synthetic import failure, keep only runtime version, opaque case ID, and aggregate error category. Verify the archive contains no transactions or tax forms, give access to the owner only, and remove it at the retention deadline.

Debug Collection Script

#!/bin/bash
set -euo pipefail
BUNDLE="debug-fondo-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"

# Environment check
echo "=== Fondo Debug Bundle ===" | tee "$BUNDLE/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE/summary.txt"
echo "FONDO_API_KEY: ${FONDO_API_KEY:+[SET]}" >> "$BUNDLE/summary.txt"

# API connectivity
HTTP=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ${FONDO_API_KEY}" \
  https://api.fondo.com/v1/compliance/status 2>/dev/null || echo "000")
echo "API Status: HTTP $HTTP" >> "$BUNDLE/summary.txt"

# Compliance and filing status
curl -s -H "Authorization: Bearer ${FONDO_API_KEY}" \
  "https://api.fondo.com/v1/compliance/status" \
  > "$BUNDLE/compliance-status.json" 2>&1 || true

# Integration health (bank, payroll connections)
curl -s -H "Authorization: Bearer ${FONDO_API_KEY}…

Fondo Deploy Integration

Overview

Deploy a containerized Fondo tax and accounting integration service with Docker. This skill covers building a production image that connects to Fondo's API for managing tax filings, compliance status, and financial reporting. Includes environment configuration for multi-entity accounting setups, health checks that verify API connectivity to Fondo's compliance endpoints, and rolling update strategies for zero-downtime deployments during critical tax filing periods.

Prerequisites

• A deployment owner, scoped runtime identity, approved data destinations, synthetic staging fixtures, and rollback operator.
• Health checks that expose generic status only and a policy prohibiting financial data/secrets in images and logs.

Instructions

1. Build reproducibly, inject secrets through the approved platform, and run the service with least privilege.
2. Validate schema, destination, and access controls using fictional data in staging before a canary.
3. Monitor aggregate health and reconciliation signals; stop and roll back on permission, data-boundary, or integrity failures.

Output

Record release/image ID, environment, approved configuration reference, canary result, owner, and rollback outcome. Exclude any financial, tax, payroll, account, or credential data.

Examples

Deploy a staging image with a fictitious export, simulate an upstream failure, and confirm health returns no sensitive payload. Roll back the canary before production if a destination or permission check fails.

Docker Configuration

FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

FROM node:20-slim
RUN addgroup --system app && adduser --system --ingroup app app
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
USER app
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1
CMD ["node", "dist/index.js"]

Environment Variables

export FONDO_API_KEY="fondo_live_xxxxxxxxxxxx"
export FONDO_BASE_URL="https://api.tryfondo.com/v1"
export FONDO_COMPANY_ID="comp_xxxxxxxxxxxx"
export FONDO_FILING_YEAR="2026"
export LOG_LEVEL="info"
export PORT="3000"
export NODE_ENV="production"

Health Check Endpoint

import express from 'express';

const app = express();

app.get('/health', async (req, res) => {
  try {
    const response = await fetch(`${process.env.FONDO_BASE_URL}/compliance/status`, {
      headers: { 'Authorization': `Bearer ${pro…

Fondo Hello World

Prerequisites

A scoped staging credential, a fictional data fixture, secret-manager access, and an authorized finance owner.

Output

Return only an opaque test ID, schema result, review state, and redacted failure reference; never emit account, transaction, payroll, or tax data.

Examples

Run the smallest read-only check against a fictional staging record, verify logs have no sensitive values, and revoke the test credential after validation.

Overview

Verify your Fondo setup is working: check that bank transactions are syncing, payroll data is flowing, and your company qualifies for R&D tax credits.

Instructions

Step 1: Verify Bank Transaction Sync

Navigate to Fondo Dashboard > Transactions:

• Confirm recent bank transactions appear (may take 24-48h for initial sync)
• Check that Plaid connection shows "Connected" status
• Verify transaction dates match your bank statement

Step 2: Review Auto-Categorization

Fondo automatically categorizes transactions:

Review and correct any miscategorized transactions in Dashboard > Transactions.

Step 3: Check R&D Tax Credit Eligibility

Fondo Dashboard > Tax Credits > R&D Assessment

Eligible if ALL apply:
✓ US-based employees (W-2, not just contractors)
✓ Developing new/improved products, processes, or software
✓ Technical uncertainty exists in the development
✓ Systematic experimentation/iteration to resolve uncertainty

Average startup credit: $21,000/year
Maximum (payroll tax offset): $500,000/year

Step 4: Verify Payroll Data

Dashboard > Payroll Integration
  → Confirm employee count matches your payroll provider
  → Verify salary data for R&D credit calculations
  → Check contractor payments are categorized separately

Expected Output

After 48 hours of setup:

• Bank transactions auto-categorized (85%+ accuracy)
• Payroll data synced monthly
• R&D eligibility assessment complete
• Estimated R&D credit amount displayed

Error Handling

Fondo Install & Auth

Output

Record authentication method, approved scope, secret-manager reference, validation time, owner, and revocation procedure. Never include keys, financial response data, or account identifiers.

Examples

Use a scoped staging credential for a read-only fictional record, record the redacted outcome, and verify the old credential is denied after revocation.

Overview

Set up Fondo for automated startup bookkeeping, tax filing, and R&D tax credits. Fondo is a managed platform (not an API-first service) that integrates with payroll providers, banks, and expense tools. Configuration happens through the Fondo dashboard and OAuth connections.

Prerequisites

• US-incorporated startup (C-corp or LLC)
• Fondo account at fondo.com
• Active payroll provider (Gusto, Rippling, ADP, etc.)
• Business bank account

Instructions

Step 1: Create Fondo Account

1. Sign up at fondo.com
2. Select your plan: TaxPass (bookkeeping + taxes + R&D credits)
3. Complete company profile (EIN, incorporation date, state)

Step 2: Connect Payroll Provider

Navigate to Fondo Dashboard > Integrations > Connect Payroll and authorize.

Step 3: Connect Bank Accounts

Fondo Dashboard > Integrations > Banking
  → Connect via Plaid (most banks)
  → Or manual CSV upload for unsupported banks
  → Mercury, SVB, Brex, Chase all supported via Plaid

Step 4: Connect Expense Tools

Step 5: Verify Connection

After connecting, verify in Dashboard > Integrations:

• Green check = connected and syncing
• Yellow warning = needs re-authorization
• Red X = connection failed, re-connect neede…

Fondo Local Dev Loop

Overview

Local development workflow for Fondo startup tax and bookkeeping integration. Provides a fast feedback loop using CSV exports and mock financial data so you can build dashboards, R&D credit calculators, and burn-rate tools without waiting on live Fondo reports. Toggle between mock mode for rapid iteration and real export parsing for production validation.

Prerequisites

• Fictional fixtures only, local directories excluded from version control, and a named finance owner for any approved export validation.
• Secrets supplied from an approved manager; local development must not access production financial data by default.

Instructions

1. Keep mock mode enabled for normal development and generate only synthetic account, vendor, and transaction values.
2. Validate schema and field mappings against an approved, access-controlled sample before any live workflow change.
3. Redact logs, avoid committing exports, and delete temporary local artifacts through the defined retention process.

Output

Produce a local validation receipt with fixture version, schema result, approved mapping, owner, and redacted failure reference. Do not include transactions, account details, payroll/tax data, or credentials.

Examples

Run a calculator against fictional monthly totals and confirm tests pass with network access disabled. Inspect the fixture for real names, account identifiers, or exports, then remove test artifacts after the schema validation is complete.

Environment Setup

cp .env.example .env
# Set your credentials:
# FONDO_API_KEY=fondo_xxxxxxxxxxxx
# FONDO_EXPORT_DIR=./exports
# MOCK_MODE=true
npm install express csv-parse dotenv tsx typescript @types/node
npm install -D vitest supertest
mkdir -p exports

Dev Server

// src/dev/server.ts
import express from "express";
const app = express();
app.use(express.json());
const MOCK = process.env.MOCK_MODE === "true";
if (MOCK) {
  const { mountMockRoutes } = require("./mocks");
  mountMockRoutes(app);
} else {
  const { mountExportRoutes } = require("./export-parser");
  mountExportRoutes(app, process.env.FONDO_EXPORT_DIR!);
}
app.listen(3002, () => console.log(`Fondo dev server on :3002 [mock=${MOCK}]`));

Mock Mode

// src/dev/mocks.ts — realistic startup financial data
export function mountMockRoutes(app: any) {
  app.get("/api/transactions", (_req: any, res: any) => res.json([
    { date: "2025-03-01", description: "AWS Infrastructure", amount: -4200, category: "Cloud Hosting", account: "Operating", isRnD: true },
    { date: "2025-03-05", description: "Engineer Salary", amount: -12…

Fondo Performance Tuning

Overview

Speed up Fondo workflows: faster month-end close (target: 15 days), reduced back-and-forth with CPA team, and efficient data export processing.

Prerequisites

• A named finance owner, approved close calendar, data-access policy, and aggregate baseline for close time and exception volume.
• Synthetic/sample data for workflow tests; real financial records remain in the approved accounting environment.

Output

Produce an operational receipt with period, aggregate bottleneck metrics, approved workflow change, owner, verification date, and unresolved exceptions. Do not include account numbers, transactions, tax documents, or credentials.

Error Handling

• Pause automation when an import, categorization, or reconciliation result is incomplete or unexpected; route it to the finance owner.
• Do not replace professional review with an automated classification or calculator result.
• Redact all financial data in performance diagnostics and roll back changes that harm accuracy or auditability.

Examples

Use a fictional month of aggregate expenses to test a categorization workflow. Compare only close duration and exception count, then have the authorized finance reviewer approve the result before changing a live process.

Instructions

Faster Month-End Close

Auto-Categorization Rules

Dashboard > Settings > Categorization Rules

Examples:
  "AWS" → Cloud Infrastructure (R&D)
  "GitHub" → Software Tools (R&D)
  "Gusto" → Payroll
  "WeWork" → Office/Rent
  "United Airlines" → Travel
  "Uber Eats" → Meals (50% deductible)

Batch CPA Communication

Instead of replying to each question individually:

1. Set aside 30 minutes weekly (e.g., Monday AM)
2. Open Dashboard > Messages > Open Items
3. Answer all outstanding questions in one session
4. This reduces close time by 3-5 days

Efficient Data Exports

// Cache Fondo exports to avoid repeated downloads
const CACHE_DIR = '.cache/fondo';
const CACHE_TTL = 24 * 60 * 60 * 1000;  // 24 hours

async function getCachedExport(reportType…

Fondo Production Checklist

Overview

Fondo handles startup tax preparation, R&D credit claims, bookkeeping, and compliance filings. A production integration syncs financial data from banking, payroll, and expense platforms into Fondo for automated tax workflows. Failures mean missed filing deadlines, incorrect R&D credit claims, or unreconciled books that block board reporting.

Prerequisites

• A finance owner, authorized reviewer, completed staging evidence using synthetic data, and documented rollback/correction process.
• Approved data flows, retention rules, access controls, filing calendar, and escalation contacts.

Instructions

1. Attach evidence or a named owner decision to each applicable control and maintain professional review for financial/tax conclusions.
2. Verify scoped secrets, source reconciliation, redacted diagnostics, access boundaries, and safe failure handling before promotion.
3. Run a synthetic canary and review aggregate health, delivery, and reconciliation results; halt on discrepancy or access failures.
4. Record approval, exceptions, correction/rollback owner, and follow-up date.

Output

Create a launch receipt with completed controls, evidence references, aggregate canary results, approver, exception status, and recovery owner. Exclude financial records, tax data, payroll data, and credentials.

Examples

Process a fictional expense export in staging, simulate an incomplete reconciliation, and verify the workflow pauses for finance review. Promote only after the reviewer records evidence and the rollback/correction path has been tested.

Authentication & Secrets

• [ ] FONDO_API_KEY stored in secrets manager (not config files)
• [ ] Financial integration OAuth tokens stored securely (Stripe, Mercury, Brex)
• [ ] Key rotation scheduled before each tax season
• [ ] Separate credentials for staging/prod environments
• [ ] Payroll provider API tokens scoped to read-only

API Integration

• [ ] Production base URL configured (https://api.fondo.com/v1)
• [ ] Rate limit handling with exponential backoff
• [ ] All bank accounts connected and syncing (verified daily)
• [ ] Payroll provider connected with W-2 and 1099 data flowing
• [ ] Revenue sources synced (Stripe, invoicing platforms)
• [ ] Expense tool integrations verified (Brex, Ramp, Expensify)
• [ ] Bookkeeping categorization queue drained before close

Error Handling & Resilience

• [ ] Circuit breaker configured for Fondo API outages
• [ ] Retry with backoff for 429/5xx responses
• [ ] Bank sync failure detection within 24 hours
• [ ] Intercompany transaction reconciliation validated
• [ ] R&D qualifying activity documentation…

Fondo Rate Limits

Prerequisites

Confirmed provider limits, an approved concurrency/retry policy, opaque queue telemetry, a finance owner, and synthetic test workload.

Instructions

Honor throttle signals, use bounded backoff and idempotency, route exhausted work to reviewed handling, and reduce load before resuming.

Output

Publish a rate-control receipt with policy version, aggregate throttles, queue outcome, owner, and manual disposition—never financial payloads or credentials.

Examples

Simulate a throttle for a fictional export, verify the retry runs once under its operation ID, and send repeated failure to review without exposing records.

Overview

Fondo itself is a managed tax and accounting service without direct API rate limits, but startups building parallel integrations to the same financial providers Fondo connects to (Gusto, QuickBooks, Plaid, Stripe, Mercury) must coordinate their own API calls to avoid shared-limit conflicts. During Fondo's nightly sync windows, your direct API calls compete for the same provider quotas, making careful scheduling and throttling critical for tax-season workloads and month-end reconciliation batches.

Rate Limit Reference

Rate Limiter Implementation

class MultiProviderLimiter {
  private limiters: Map<string, { tokens: number; max: number; lastRefill: number; rate: number }> = new Map();

  register(provider: string, maxPerMinute: number) {
    this.limiters.set(provider, {
      tokens: maxPerMinute, max: maxPerMinute,
      lastRefill: Date.now(), rate: maxPerMinute / 60_000,
    });
  }

  async acquire(provider: string): Promise<void> {
    const l = this.limiters.get(provider);
    if (!l) throw new Error(`Unknown provider: ${provider}`);
    const now = Date.now();
    l.tokens = Math.min(l.max, l.tokens + (now - l.lastRefill) * l.rate);
    l.lastRefill = now;
    if (l.tokens >= 1) { l.tokens -= 1; return; }
    const waitMs = (1 - l.tokens) / l.rate;
    await new Promise(r => setTimeout(r, waitMs));
    l.tokens = 0;
  }
}

const limiter = new MultiProviderLimiter();
limiter.register("gusto", 40);      // 40/min leaves room for Fondo syncs
limiter.register("quickbooks", 400); //…

Fondo Reference Architecture

Overview

Reference architecture for a startup's financial operations with Fondo at the center, connecting payroll, banking, payments, and internal reporting.

Prerequisites

• A data-flow inventory, authorized business purpose, system owners, access/retention policy, and professional-review boundary.
• Separate scoped identities for data sources, processing, storage, reporting, and support, plus synthetic integration fixtures.

Instructions

1. Enforce field allowlists, access checks, encryption, and retention requirements at every financial-data boundary.
2. Keep financial/tax conclusions under the designated finance professional’s review; integrations may prepare evidence but not replace that review.
3. Use idempotent queues, redacted telemetry, staged promotion, and a correction/rollback path for each downstream consumer.

Output

Maintain an architecture record describing sources, trust boundaries, approved destinations, access/retention controls, owners, professional-review points, and recovery mechanisms. Do not include finance data or secrets.

Error Handling

• Quarantine unknown fields, unapproved destinations, and reconciliation mismatches for finance review.
• Disable unsafe consumers and preserve only redacted evidence during recovery.
• Restore the prior mapping/configuration before replaying any financial workflow.

Examples

Route a fictional aggregate expense event through an approved staging pipeline, deny an unapproved reporting consumer, and verify a duplicate event is suppressed. Record only the opaque event ID and aggregate outcome.

Architecture

┌─────────────────────────────────────────────────────────┐
│                     Data Sources                         │
├──────────┬──────────┬──────────┬──────────┬─────────────┤
│  Mercury │  Gusto   │  Stripe  │  Brex    │  AWS/GCP    │
│  Banking │  Payroll │  Revenue │  Expense │  Cloud      │
├──────────┴──────────┴──────────┴──────────┴─────────────┤
│              Plaid / OAuth Connections                    │
├─────────────────────────────────────────────────────────┤
│                                                          │
│                   FONDO PLATFORM                         │
│  ┌──────────┐  ┌──────────┐  ┌────────────────┐        │
│  │ Monthly  │  │ Tax      │  │ R&D Tax Credit │        │
│  │ Close    │  │ Filing   │  │ Study (6765)   │        │
│  └──────────┘  └──────────┘  └────────────────┘        │
│                                                          │
├─────────────────────────────────────────────────────────┤
│                     Outputs                              │
├──────────┬──────────┬──────────┬────────────────────────┤
│  P&L     │  Balance │  Cash    │  R&D Credit            │
│  Report  │  Sheet   │ …

Fondo SDK Patterns

Overview

Production-ready patterns for integrating with Fondo tax and accounting data. Fondo is a managed bookkeeping platform that syncs through QuickBooks Online and payroll providers. Integration uses the FONDO_API_KEY-authenticated REST endpoints for exports, the QuickBooks Online API for GL data, and structured CSV parsing with Zod validation for bulk imports.

Prerequisites

• Scoped credentials, authorized source/destination mappings, synthetic fixtures, and a designated finance-data owner.
• Schema validation, idempotent import design, redacted diagnostics, and professional review for financial conclusions.

Instructions

1. Validate source schema and field allowlists before parsing or forwarding data.
2. Use opaque operation IDs, bounded retries, and reconciliation gates to prevent duplicate or partial imports.
3. Quarantine unknown fields and mismatches for finance review rather than broadening data access.

Output

Produce a client-validation receipt with contract/fixture version, aggregate schema and reconciliation outcome, operation ID, owner, and redacted failure reference. Do not log transactions, accounts, tax/payroll data, or tokens.

Examples

Import a fictional aggregate ledger fixture into staging, repeat it under the same operation ID, and verify duplicate suppression. Introduce an unexpected field and confirm the parser blocks it for review without revealing record contents.

Singleton Client

const FONDO_BASE = 'https://api.fondo.com/v1';
let _client: FondoClient | null = null;
export function getClient(): FondoClient {
  if (!_client) {
    const apiKey = process.env.FONDO_API_KEY;
    if (!apiKey) throw new Error('FONDO_API_KEY must be set — get it from your Fondo dashboard');
    _client = new FondoClient(apiKey);
  }
  return _client;
}
class FondoClient {
  private headers: Record<string, string>;
  constructor(apiKey: string) { this.headers = { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' }; }
  async getTransactions(start: string, end: string): Promise<FondoTransaction[]> {
    const res = await fetch(`${FONDO_BASE}/transactions?start=${start}&end=${end}`, { headers: this.headers });
    if (!res.ok) throw new FondoError(res.status, await res.text()); return res.json();
  }
  async getAccounts(): Promise<FondoAccount[]> {
    const res = await fetch(`${FONDO_BASE}/accounts`, { headers: this.headers });
    if (!res.ok) throw new FondoError(res.status, await res.text()); return res.json();
  }
}

Error Wrapper

export class FondoError extends Error {
  constructor(public status: number, message: string) { super(message); this.name = 'FondoError'; }
}
export async…

Fondo Security Basics

Prerequisites

A security owner, scoped secret manager, financial-data access policy, review cadence, and synthetic fixtures.

Instructions

Use least-privilege credentials per environment; verify signed events and idempotency; restrict financial and tax data to approved systems; redact diagnostics; rotate credentials on suspected exposure.

Output

Maintain a security receipt with scope, secret reference, access-review date, control result, owner, and redacted incident state. Do not include financial data or secrets.

Examples

Verify a fictional signed event is processed once, an invalid signature is rejected without payload logging, and revoking a staging credential blocks future requests.

Overview

Fondo handles startup tax preparation, bookkeeping, and R&D tax credits containing SSNs, EINs, bank account details, revenue figures, and complete tax returns. A breach exposes founder personal tax data, company financials, and IRS filing details. Protect OAuth connections to banking/payroll systems, exported financial documents, and team access controls with the same rigor as a CPA firm.

API Key Management

function createFondoClient(): { apiKey: string; baseUrl: string } {
  const apiKey = process.env.FONDO_API_KEY;
  if (!apiKey) {
    throw new Error("Missing FONDO_API_KEY — store in secrets manager, never in code");
  }
  // Fondo keys access tax returns and SSN/EIN data — treat as highest sensitivity
  console.log("Fondo client initialized (key suffix:", apiKey.slice(-4), ")");
  return { apiKey, baseUrl: "https://api.fondo.com/v1" };
}

Webhook Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyFondoWebhook(req: Request, res: Response, next: NextFunction): void {
  const signature = req.headers["x-fondo-signature"] as string;
  const secret = process.env.FONDO_WEBHOOK_SECRET!;
  const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex");
  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    res.status(401).send("Invalid signature");
    return;
  }
  next();
}

Input Validation

import { z } from "zod";

const TaxFilingSchema = z.object({
  entity_id: z.string().uuid(),
  tax_year: z.number().int().min(2015).max(2030),
  filing_type: z.enum(["1120", "1120S", "1065", "941", "R&D_credit"]),
  ein: z.string().regex(/^\d{2}-\d{7}$/),
  revenue: z.number().nonnegative(),
  status: z.enum(["draft", "review", "filed", "amended"]),
});…

Fondo Upgrade & Migration

Prerequisites

Current provider change information, approved finance-data inventory, synthetic staging fixtures, a finance owner, and a tested correction/rollback path.

Output

Record versions and mappings reviewed, aggregate validation/reconciliation result, reviewer approval, and rollback state. Exclude financial records and credentials.

Error Handling

Stop promotion on schema, access, reconciliation, retention, or professional-review gaps; restore the prior mapping and quarantine opaque failures for review.

Examples

Compare old and proposed mappings using fictional aggregate data, deliberately introduce an unknown field, and verify the change remains pending until the finance reviewer approves it.

Overview

Migrate to Fondo from DIY bookkeeping, other accounting firms, or platforms like Pilot, Bench, or Kruze. Fondo handles the historical data import.

Migration Scenarios

Instructions

Step 1: Prepare Migration Data

Gather from your current provider:

• [ ] QuickBooks Online backup (or GL export as CSV)
• [ ] Bank statements (last 2 years for R&D credit)
• [ ] Payroll records (all W-2 and 1099 data)
• [ ] Prior tax returns (1120, state returns)
• [ ] R&D credit studies (Form 6765 if previously claimed)
• [ ] Cap table and equity event history

Step 2: Onboard with Fondo

1. Sign up at fondo.com and select plan
2. Upload historical data via Dashboard > Migration
3. Connect active integrations (bank, payroll, expense)
4. Fondo CPA team reviews and reconciles historical data
5. First month close produces baseline reports

Step 3: Transition from Previous Accountant

Timeline:
  Week 1: Sign Fondo engagement letter, connect integrations
  Week 2: Previous accountant provides data export and handoff notes
  Week 3: Fondo reviews historical data, catches up any gaps
  Week 4: First Fondo-managed month close complete

Plan Upgrades

Fondo Webhooks & Events

Prerequisites

A signing secret in the secret manager, raw-body validation, event ledger, approved destinations, redaction policy, and synthetic fixtures.

Output

Return opaque event ID, signature result, idempotency outcome, destination status, and redacted error category. Keep financial payloads and credentials out of logs.

Error Handling

Reject invalid signatures, quarantine unknown schemas or destinations, bound retries, and pause downstream processing on access or reconciliation failures.

Examples

Deliver a fictional signed event twice and confirm only the first is processed; reject an invalid signature without logging its payload or forwarding data.

Overview

Fondo itself does not send webhooks. Instead, build event-driven workflows using webhooks from the same providers Fondo connects to: Stripe (revenue), Gusto (payroll), Plaid (bank transactions), and Mercury (banking).

Provider Webhooks

Instructions

Stripe Revenue Webhook

import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_API_KEY!);

app.post('/webhooks/stripe', express.raw({ type: '*/*' }), (req, res) => {
  const sig = req.headers['stripe-signature'] as string;
  const event = stripe.webhooks.constructEvent(
    req.body, sig, process.env.STRIPE_WEBHOOK_SECRET!
  );

  switch (event.type) {
    case 'charge.succeeded':
      const amount = (event.data.object as Stripe.Charge).amount / 100;
      console.log(`Revenue: $${amount}`);
      // Update internal dashboard
      break;
    case 'invoice.paid':
      // MRR tracking
      break;
  }
  res.sendStatus(200);
});

Gusto Payroll Webhook

// Gusto sends webhooks when payroll is processed
app.post('/webhooks/gusto', express.json(), async (req, res) => {
  const { event_type, data } = req.body;

  if (event_type === 'payroll.processed') {
    const totalPayroll = data.totals.gross_pay;
    console.log(`Payroll processed: $${totalPayroll}`);
    // Alert if significantly different from budget
    if (totalPayroll > monthlyPayrollBudget * 1.1) {
      await sendAlert(`Payroll exceeded budget by ${((totalPayro…