Bank Sync

Taskr supports multiple banking providers to automatically sync transactions, enabling receipt matching, expense tracking, and bank reconciliation.

Supported Providers

Plaid

US & Canada11,000+ institutions Real-time webhooks Transaction enrichment

GoCardless

Europe & UK2,500+ banks Open Banking API PSD2 compliant

Teller

US Alternative5,000+ institutions Direct bank connections Lower latency

Connection Flow

Workflow States

Sync Process

Connection Established

User completes OAuth flow with banking provider. Access token stored encrypted.

// packages/workbooks-jobs/src/tasks/bank/sync/connection.ts

await db.insert(bankConnections).values({
  teamId,
  providerId: "plaid",
  accessToken: encrypt(accessToken),
  status: "connected",
  lastSyncAt: null,
});

Account Discovery

Fetch all linked accounts from the connection.

const accounts = await plaidClient.accountsGet({ access_token });

for (const account of accounts.data.accounts) {
  await db.insert(bankAccounts).values({
    connectionId,
    externalId: account.account_id,
    name: account.name,
    type: account.type,
    subtype: account.subtype,
    mask: account.mask,
    balance: account.balances.current,
  });
}

Transaction Sync

Fetch and store transactions for each account.

// Initial sync: Last 90 days
// Ongoing sync: Since last sync

const transactions = await plaidClient.transactionsGet({
  access_token,
  start_date: startDate,
  end_date: endDate,
});

for (const txn of transactions.data.transactions) {
  await upsertTransaction(db, {
    accountId,
    externalId: txn.transaction_id,
    amount: txn.amount,
    date: txn.date,
    name: txn.name,
    merchantName: txn.merchant_name,
    category: txn.category,
    pending: txn.pending,
  });
}

Webhook Registration

// Plaid sends webhooks for:
// - TRANSACTIONS_REMOVED
// - DEFAULT_UPDATE (new transactions)
// - HISTORICAL_UPDATE (backfill complete)
// - SYNC_UPDATES_AVAILABLE (incremental)

Provider-Specific Details

Plaid
GoCardless
Teller

Configuration

// packages/workbooks-engine/src/providers/plaid/plaid-api.ts

const plaidClient = new PlaidApi({
  basePath: PlaidEnvironments[env.PLAID_ENV],
  headers: {
    "PLAID-CLIENT-ID": env.PLAID_CLIENT_ID,
    "PLAID-SECRET": env.PLAID_SECRET,
  },
});

Webhook Events

Event	Description	Action
`TRANSACTIONS.DEFAULT_UPDATE`	New transactions available	Queue sync
`TRANSACTIONS.HISTORICAL_UPDATE`	Historical data ready	Queue full sync
`TRANSACTIONS.SYNC_UPDATES_AVAILABLE`	Incremental updates	Queue delta sync
`ITEM.ERROR`	Connection error	Mark connection failed
`ITEM.PENDING_EXPIRATION`	Token expiring	Notify user to reauth

Error Handling

if (error.error_code === "ITEM_LOGIN_REQUIRED") {
  await markConnectionNeedsReauth(connectionId);
  await notifyUser("Bank requires re-authentication");
}

Configuration

// packages/workbooks-engine/src/providers/gocardless/gocardless-provider.ts

const client = new NordigenClient({
  secretId: env.GOCARDLESS_SECRET_ID,
  secretKey: env.GOCARDLESS_SECRET_KEY,
});

Open Banking Flow

Create requisition with institution ID
Redirect user to bank’s authorization page
Receive webhook on completion
Fetch accounts and transactions

Supported Countries

Austria, Belgium, Czech Republic, Denmark, Estonia, Finland, France, Germany, Hungary, Ireland, Italy, Latvia, Lithuania, Luxembourg, Netherlands, Norway, Poland, Portugal, Slovakia, Spain, Sweden, UK

Configuration

// packages/workbooks-engine/src/providers/teller/teller-provider.ts

const tellerClient = new Teller({
  applicationId: env.TELLER_APP_ID,
  environment: env.TELLER_ENV,
});

Features

Direct bank connections (not aggregated)
Lower latency than Plaid
Real-time balance updates
Identity verification available

Sync Scheduling

Sync Type	Frequency	Trigger
Initial Sync	Once	On connection
Scheduled Sync	Daily	Cron job (2 AM UTC)
Webhook Sync	Real-time	Provider webhook
Manual Sync	On demand	User request

Background Job Configuration

// packages/workbooks-jobs/src/tasks/bank/sync/connection.ts

export const syncBankConnection = task({
  id: "sync-bank-connection",
  retry: {
    maxAttempts: 3,
    factor: 2,
    minTimeoutInMs: 1000,
    maxTimeoutInMs: 30000,
  },
  queue: {
    name: "bank-sync",
    concurrencyLimit: 5,
  },
});

Error Recovery

Connection Expired

Cause: Access token has expired or been revokedRecovery:

Mark connection as needs_reauth
Send email notification to team owner
Show banner in dashboard
User re-authenticates via provider

Rate Limited

Cause: Too many API requestsRecovery:

Implement exponential backoff
Queue sync for later
Spread syncs across time window

Sync Failed

Cause: API error, network issues, data issuesRecovery:

Retry with backoff (up to 3 times)
Log error details
After max retries, mark as failed
Notify user if consecutive failures

Duplicate Transactions

Cause: Same transaction synced multiple timesPrevention:

// Upsert by external transaction ID
await db
  .insert(transactions)
  .values(transactionData)
  .onConflictDoUpdate({
    target: [transactions.externalId, transactions.accountId],
    set: { ...transactionData, updatedAt: new Date() },
  });

Transaction Matching

Synced transactions can be matched to:

Invoices: Match payments to outstanding invoices
Expenses: Match purchases to expense records
Receipts: AI-powered receipt matching from email inbox

// Matching algorithm
async function matchTransaction(transaction: BankTransaction) {
  // 1. Exact amount match within date range
  const invoiceMatch = await findInvoiceByAmount(
    transaction.amount,
    transaction.date,
    { tolerance: 0.01, dayRange: 7 }
  );
  
  // 2. Reference number matching
  if (transaction.reference) {
    const refMatch = await findByReference(transaction.reference);
  }
  
  // 3. AI-powered merchant matching
  const merchantMatch = await aiMatchMerchant(
    transaction.merchantName,
    transaction.category
  );
}

Database Schema

// Bank Connections
export const bankConnections = pgTable("bank_connections", {
  id: uuid("id").primaryKey().defaultRandom(),
  teamId: uuid("team_id").references(() => teams.id),
  providerId: text("provider_id").notNull(), // plaid, gocardless, teller
  accessToken: text("access_token").notNull(), // encrypted
  institutionId: text("institution_id"),
  institutionName: text("institution_name"),
  status: text("status").notNull(), // connected, error, needs_reauth
  lastSyncAt: timestamp("last_sync_at"),
  errorCode: text("error_code"),
  errorMessage: text("error_message"),
  consecutiveFailures: integer("consecutive_failures").default(0),
});

// Bank Accounts
export const bankAccounts = pgTable("bank_accounts", {
  id: uuid("id").primaryKey().defaultRandom(),
  connectionId: uuid("connection_id").references(() => bankConnections.id),
  externalId: text("external_id").notNull(),
  name: text("name").notNull(),
  officialName: text("official_name"),
  type: text("type"), // checking, savings, credit
  subtype: text("subtype"),
  mask: text("mask"), // last 4 digits
  currentBalance: decimal("current_balance"),
  availableBalance: decimal("available_balance"),
  currency: text("currency").default("USD"),
});

// Bank Transactions
export const bankTransactions = pgTable("bank_transactions", {
  id: uuid("id").primaryKey().defaultRandom(),
  accountId: uuid("account_id").references(() => bankAccounts.id),
  externalId: text("external_id").notNull(),
  amount: decimal("amount").notNull(),
  date: date("date").notNull(),
  name: text("name"),
  merchantName: text("merchant_name"),
  category: jsonb("category"),
  pending: boolean("pending").default(false),
  // Matching
  matchedInvoiceId: uuid("matched_invoice_id"),
  matchedExpenseId: uuid("matched_expense_id"),
  matchConfidence: decimal("match_confidence"),
});

Webhooks

// apps/workbooks-api/src/rest/webhooks/plaid.ts

export const plaidWebhookHandler = async (c: Context) => {
  const body = await c.req.json();
  
  // Verify webhook signature
  const isValid = verifyPlaidWebhook(body, c.req.header("Plaid-Verification"));
  if (!isValid) {
    return c.json({ error: "Invalid signature" }, 401);
  }
  
  switch (body.webhook_type) {
    case "TRANSACTIONS":
      await handleTransactionWebhook(body);
      break;
    case "ITEM":
      await handleItemWebhook(body);
      break;
    case "AUTH":
      await handleAuthWebhook(body);
      break;
  }
  
  return c.json({ received: true });
};

API Endpoints

Endpoint	Method	Description
`bankConnections.list`	Query	List all bank connections
`bankConnections.create`	Mutation	Create new connection (get link token)
`bankConnections.exchange`	Mutation	Exchange public token for access token
`bankConnections.sync`	Mutation	Trigger manual sync
`bankConnections.delete`	Mutation	Remove connection
`bankAccounts.list`	Query	List accounts for connection
`bankTransactions.list`	Query	List transactions with filters
`bankTransactions.match`	Mutation	Match transaction to invoice/expense

Invoice Payment

Bank reconciliation and payment matching

Accounting Sync

Sync with QuickBooks and Xero

Developer - Overview

Core Workflows

Billing & Subscriptions

Integrations

Team Management

Onboarding Wizards

Reference

Supported Providers

Plaid

GoCardless

Teller

Connection Flow

Workflow States

Sync Process

Provider-Specific Details

Configuration

Webhook Events

Error Handling

Configuration

Open Banking Flow

Supported Countries

Configuration

Features

Sync Scheduling

Background Job Configuration

Error Recovery

Transaction Matching

Database Schema

Webhooks

API Endpoints

Invoice Payment

Accounting Sync

​Supported Providers

Plaid

GoCardless

Teller

​Connection Flow

​Workflow States

​Sync Process

​Provider-Specific Details

​Configuration

​Webhook Events

​Error Handling

​Configuration

​Open Banking Flow

​Supported Countries

​Configuration

​Features

​Sync Scheduling

​Background Job Configuration

​Error Recovery

​Transaction Matching

​Database Schema

​Webhooks

​API Endpoints

​Related Documentation

Invoice Payment

Accounting Sync

Supported Providers

Connection Flow

Workflow States

Sync Process

Provider-Specific Details

Configuration

Webhook Events

Error Handling

Configuration

Open Banking Flow

Supported Countries

Configuration

Features

Sync Scheduling

Background Job Configuration

Error Recovery

Transaction Matching

Database Schema

Webhooks

API Endpoints

Related Documentation