Skip to main content

Account Management

OneLibro's account management feature allows you to securely connect your bank accounts via Plaid, view all your accounts in one place, sync transactions, and track balances across multiple financial institutions.

Overview​

The account management system enables you to:

  • Connect bank accounts securely via Plaid Link
  • View all accounts from multiple banks in one unified dashboard
  • Track balances (current and available) in real-time
  • Sync transactions manually whenever you need updated data
  • Support multiple account types (checking, savings, credit, investment, cash)
  • Manage institutions (connect multiple accounts from one bank or multiple banks)
  • Secure connection with encrypted access tokens and bank-level security

Connecting Your First Bank Account​

Prerequisites​

  1. Active OneLibro account (sign up with invite code)
  2. Online banking credentials for your bank
  3. Bank supported by Plaid (12,000+ institutions supported)

Step-by-Step Connection Process​

Step 1: Navigate to Accounts

  1. Log in to OneLibro
  2. Click "Accounts" in the main navigation
  3. You'll see an empty state with "No Accounts Connected"

Step 2: Click "Connect Your First Account"

  • Large green button in the center of the page
  • Opens the Plaid Link modal

Step 3: Search for Your Bank

  • Plaid Link modal opens in a popup
  • Search bar at the top
  • Type your bank name (e.g., "Chase", "Bank of America", "Wells Fargo")
  • Select your institution from the list

Step 4: Enter Your Bank Credentials

  • Enter your online banking username
  • Enter your online banking password
  • Click "Submit" or "Continue"
Security Note

OneLibro never sees or stores your bank login credentials. Plaid handles authentication securely and provides OneLibro with a secure access token only.

Step 5: Complete Multi-Factor Authentication (if required)

  • Some banks require 2FA (text code, email code, etc.)
  • Follow your bank's authentication process
  • Enter the code when prompted

Step 6: Select Accounts

  • Plaid displays all accounts associated with your login
  • Select which accounts to connect (can select multiple)
  • Typical options:
    • ✅ Checking accounts
    • ✅ Savings accounts
    • ✅ Credit cards
    • ✅ Investment accounts
    • ✅ Loan accounts
  • Click "Continue" after selecting

Step 7: Grant Permissions

  • Plaid requests permission to:
    • Access account balances
    • Access transaction history
    • Access account owner information
  • Review permissions and click "Allow" or "Continue"

Step 8: Connection Complete!

  • Plaid Link closes automatically
  • OneLibro begins syncing your accounts and transactions
  • You're redirected to the Accounts page
  • Your connected accounts now appear in the grid

What Happens After Connection​

  1. Account Creation:

    • OneLibro stores encrypted access token in database
    • Account details (name, type, balance) are saved
    • Institution information is recorded

  2. Initial Transaction Sync:

    • Plaid fetches up to 2 years of transaction history
    • Transactions are inserted into OneLibro database
    • Transaction categories are automatically assigned

  3. Account Display:

    • Accounts appear as cards in the Accounts page
    • Balances are displayed (current and available)
    • Account type badge shows (Checking, Savings, etc.)
    • Institution name is shown

Connecting Additional Accounts​

Adding More Accounts from the Same Bank​

If you have multiple accounts at one bank (e.g., checking + savings at Chase):

Option 1: Connect During Initial Setup

  • When selecting accounts in Plaid Link, select all accounts you want to track
  • All selected accounts are added at once

Option 2: Reconnect Later

  • Click "Connect Another Account"
  • Search for the same bank
  • Log in again
  • Select additional accounts
  • Previous accounts remain connected

Adding Accounts from Different Banks​

To connect accounts from multiple banks:

  1. Complete first bank connection process
  2. Click "Connect Another Account" button (top-right of Accounts page)
  3. Repeat Plaid Link process for the new bank
  4. All accounts from all banks appear in your unified dashboard

Benefits of Multi-Bank Tracking:

  • See total balance across all banks
  • Track all transactions in one place
  • Budgets work across all accounts
  • Dashboard shows combined financial picture

Viewing Your Accounts​

Accounts Page Layout​

URL: /finance/accounts

When You Have Accounts:

  • Header shows: "{N} accounts connected"
  • "Connect Another Account" button in top-right
  • Grid layout of account cards (1 column on mobile, 2-3 columns on desktop)
  • Each account displayed as a card

Account Card Details​

Each account card shows:

Top Section:

  • Icon: Bank building icon (or wallet for cash accounts)
  • Account Name: Official account name from bank (e.g., "Checking ...1234")
  • Institution: Bank name (e.g., "Chase", "Bank of America")
  • Type Badge: Account type (Checking, Savings, Credit, etc.) with color coding

Middle Section:

  • Current Balance: Large, bold display of current account balance
  • Available Balance: Shown if different from current (e.g., credit card available credit)

Bottom Section:

  • Last Synced: How long ago transactions were last synced (e.g., "2 hours ago")
  • Sync Button: Manual sync trigger with loading spinner during sync

Account Types​

OneLibro supports all account types provided by Plaid:

TypeBadge ColorExamples
CheckingGreenPrimary checking, business checking
SavingsGreenSavings, money market, high-yield savings
CreditPurpleCredit cards, charge cards
LoanRedStudent loans, personal loans, mortgages
InvestmentBlueBrokerage, 401(k), IRA
CashGreenManual cash tracking

Current vs Available Balance​

Current Balance:

  • The actual balance in your account right now
  • Includes pending transactions
  • What you currently have (or owe on credit)

Available Balance:

  • Amount you can actually spend or withdraw
  • May differ from current due to:
    • Holds on deposits
    • Pending transactions
    • Credit limit minus current balance (for credit cards)
    • Reserved funds

Examples:

Checking Account:

  • Current: $1,500.00
  • Available: $1,200.00
  • (You deposited $300 check that's on hold)

Credit Card:

  • Current Balance: $450.00 (what you owe)
  • Available Balance: $4,550.00 (credit limit $5,000 - $450 owed)

Savings Account:

  • Current: $10,000.00
  • Available: $10,000.00 (same - no holds)
tip

Always use Available Balance when deciding if you can afford a purchase. Current Balance may include pending transactions or holds.

Syncing Transactions​

Automatic Syncing​

OneLibro automatically syncs transactions:

  • Frequency: Daily (typically overnight)
  • Method: Background job checks for new transactions
  • What's Synced:
    • New transactions since last sync
    • Updates to pending transactions (pending → posted)
    • Transaction amount changes (e.g., gas station final charge)
    • Balance updates

Manual Syncing​

Sometimes you need to sync immediately (e.g., before budget review, after large purchase):

How to Sync:

  1. Go to Accounts page
  2. Find the account you want to sync
  3. Click the "Sync" button at bottom of account card
  4. Wait for spinner to complete (5-15 seconds)
  5. Success toast shows sync results

Sync Results Toast:

  • "Account is up to date!" (no new transactions)
  • "Synced! Added: 5, Modified: 2" (new/updated transactions)
  • Error message if sync fails

What Gets Synced​

Transaction Data:

  • Transaction date
  • Merchant name
  • Amount
  • Category (from Plaid)
  • Pending status
  • Account reference

Balance Updates:

  • Current balance refreshed
  • Available balance refreshed
  • Last synced timestamp updated

Sync Frequency Best Practices​

Daily Sync:

  • Automatic background sync is usually sufficient
  • No action needed from you

Manual Sync Before:

  • Budget review (end of week/month)
  • Large purchase verification
  • Checking for refunds or returns
  • Expense report creation

Don't Over-Sync:

  • Plaid limits sync frequency (typically 1-4 syncs per day)
  • Excessive syncing can trigger rate limits
  • Wait at least 30 minutes between manual syncs

Account Security​

How Your Data is Protected​

1. Plaid Security:

  • Bank-level 256-bit encryption
  • No password storage by OneLibro
  • Secure token exchange
  • SOC 2 Type II certified

2. OneLibro Security:

  • Access tokens encrypted with AES-256-CBC
  • Encryption key stored securely in environment variables
  • Tokens never exposed to frontend
  • Secure API endpoints with authentication

3. Bank Security:

  • Continues to protect your actual accounts
  • OneLibro only has read-only access
  • Cannot transfer funds or make changes
  • Can be revoked anytime through your bank

Revoking Access​

To disconnect OneLibro from your bank:

Option 1: Through Your Bank

  1. Log in to your bank's website
  2. Go to Security or Connected Apps settings
  3. Find "Plaid" or "OneLibro"
  4. Click "Revoke Access" or "Disconnect"

Option 2: Contact OneLibro Support (coming soon)

  • Email support to request account disconnection
  • Account will be removed from system
  • Transactions remain for historical purposes (can be deleted on request)
Disconnection Impact

Revoking access stops transaction syncing. Historical data remains in OneLibro unless you request deletion. Budgets and reports will still use historical data.

Cash and Manual Accounts​

OneLibro also supports manual "Cash" accounts for tracking transactions not connected via Plaid.

Use Cases for Cash Accounts​

  • Track cash spending
  • Record Venmo/PayPal transactions
  • Monitor accounts not supported by Plaid
  • Temporary placeholder until bank connection
  • Track gift cards or store credit

Creating a Cash Account (Coming Soon)​

Currently, cash accounts can be created via admin. Future versions will allow users to create their own.

Empty State​

If you haven't connected any accounts yet:

Display:

  • Large bank building icon
  • Heading: "No Accounts Connected"
  • Subtitle: "Connect your bank account to start tracking your finances. Your data is secure and encrypted."
  • Large "Connect Your First Account" button

Actions:

  • Click button → Opens Plaid Link
  • Complete connection process → Accounts appear

Responsive Design​

Desktop (1024px+)​

  • 3-column grid of account cards
  • All account details visible
  • Large sync buttons
  • Spacious layout

Tablet (768px - 1024px)​

  • 2-column grid
  • Slightly compressed cards
  • All features still accessible

Mobile (<768px)​

  • 1-column stack
  • Full-width cards
  • Touch-friendly buttons
  • Optimized for scrolling

Troubleshooting​

"Failed to connect account"​

Possible Causes:

  1. Incorrect bank credentials
  2. Bank requires 2FA and wasn't completed
  3. Selected bank not supported by Plaid
  4. Temporary Plaid or bank outage

Solutions:

  • Double-check username and password
  • Complete MFA if prompted
  • Try a different bank
  • Wait 10 minutes and try again
  • Contact support if issue persists

"Account sync failed"​

Possible Causes:

  1. Bank connection expired or revoked
  2. Bank changed login requirements
  3. Plaid rate limit reached
  4. Temporary network issue

Solutions:

  • Reconnect account using "Update" mode (coming soon)
  • Wait 30 minutes and try again
  • Check if bank revoked Plaid access
  • Contact support if repeated failures

Balance shows $0.00​

Possible Causes:

  1. Account is actually empty
  2. Sync in progress
  3. Connection error during initial setup

Solutions:

  • Click "Sync" button to refresh
  • Wait a few minutes and refresh page
  • If persists, reconnect the account

Missing accounts after connection​

Possible Causes:

  1. Didn't select accounts during Plaid Link
  2. Connection interrupted before completion
  3. Bank doesn't support certain account types

Solutions:

  • Click "Connect Another Account" and reconnect
  • Select all desired accounts in Plaid Link
  • Check if account type is supported (most are)

"This is a cash account" when syncing​

Cause: You're trying to sync a manually created cash account

Solution: Cash accounts cannot sync from banks. Add transactions manually to cash accounts.

API Reference​

Fetching User Accounts​

import { getUserAccounts } from '@/lib/supabase';

// Get all accounts for a user
const accounts = await getUserAccounts(userId);

Returns: Array of Account objects

Account Type​

interface Account {
  id: string;
  user_id: string;
  plaid_item_id: string | null; // null for cash accounts
  plaid_account_id: string | null;
  account_name: string | null;
  account_type: string | null; // "checking", "savings", "credit", etc.
  account_subtype: string | null;
  current_balance: number; // In cents
  available_balance: number | null; // In cents
  currency_code: string; // "USD"
  created_at: string;
  updated_at: string;

  // Joined data
  plaid_items?: {
    institution_name: string | null;
    last_synced: string | null;
  };
}

Sync Transactions API​

// Call sync endpoint
const response = await fetch('/api/plaid/sync-transactions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${session.access_token}`,
  },
  body: JSON.stringify({ itemId: plaidItemId }),
});

const data = await response.json();
// data: { added: 5, modified: 2, removed: 0 }

The PlaidLink component wraps the Plaid Link React library and handles token exchange automatically.

Props:

  • onSuccess (function): Callback when connection succeeds
  • onExit (function): Callback when user closes Plaid Link
  • buttonText (string): Text to display on button
  • variant ("primary" | "secondary"): Button styling

Usage:

<PlaidLink
  onSuccess={() => fetchAccounts()}
  buttonText="Connect Bank Account"
  variant="primary"
/>

Flow:

  1. User clicks button
  2. Component fetches Plaid Link token from /api/plaid/create-link-token
  3. Plaid Link modal opens
  4. User completes bank connection
  5. Component exchanges public token via /api/plaid/exchange-token
  6. Accounts and transactions are synced
  7. onSuccess callback fires
  8. Accounts list refreshes

Best Practices​

Account Organization​

Connect All Primary Accounts:

  • Main checking account
  • Primary savings account
  • Credit cards you use regularly
  • Investment accounts you want to track

Skip:

  • Rarely-used accounts
  • Accounts with sensitive restrictions
  • Accounts you don't want to track spending from

Regular Syncing​

Daily: Automatic sync handles this

Weekly: Manual sync before budget review (Sundays)

Monthly: Sync all accounts before month-end financial review

Before Major Decisions: Sync before large purchases or bill payments

Security Hygiene​

Do:

  • Use strong, unique password for OneLibro
  • Enable 2FA on your bank accounts
  • Review connected apps in your bank settings periodically
  • Log out of OneLibro on shared computers

Don't:

  • Share your OneLibro login credentials
  • Connect accounts on public WiFi without VPN
  • Leave OneLibro logged in on public computers

Multiple Bank Strategy​

Centralized View:

  • Connect all banks to see complete financial picture
  • Total balance across all accounts
  • All transactions in one place

Separate Tracking:

  • Personal vs business accounts
  • Track net worth across institutions
  • Monitor spending across all cards

Supported Banks​

Plaid supports 12,000+ financial institutions including:

Major Banks:

  • Chase
  • Bank of America
  • Wells Fargo
  • Citibank
  • Capital One
  • US Bank
  • PNC
  • TD Bank
  • Truist

Credit Unions:

  • Navy Federal
  • Alliant
  • BECU
  • Schools First FCU

Online Banks:

  • Ally Bank
  • Marcus by Goldman Sachs
  • Discover Bank
  • American Express

Credit Cards:

  • All major card issuers
  • Amex, Visa, Mastercard, Discover

Investment Platforms:

  • Vanguard
  • Fidelity
  • Charles Schwab
  • Robinhood
  • E*TRADE
Not Seeing Your Bank?

Search for your bank in Plaid Link. If not found, check if your bank has online banking (required) or contact support to request addition.

  • Transactions - View and manage transactions
  • Dashboard - Overview of all accounts
  • Budgets - Track spending from accounts
  • Plaid Integration Guide (coming in Phase 2) - Developer documentation

Summary​

Account management in OneLibro provides:

  • ✅ Secure bank account connection via Plaid
  • ✅ Support for 12,000+ financial institutions
  • ✅ Real-time balance tracking (current + available)
  • ✅ Manual and automatic transaction syncing
  • ✅ Multiple account types (checking, savings, credit, etc.)
  • ✅ Multi-bank dashboard
  • ✅ Bank-level encryption and security
  • ✅ Easy connection and syncing UI

Connect your bank accounts today to start tracking your complete financial picture in OneLibro!