Bank Connections

Open Ledger integrates with Plaid, a platform that provides seamless access to bank account and credit card data. This integration enables Open Ledger to harness financial data directly from banks, enhancing the functionality of our financial solutions.

Setting Up Plaid Integration

To begin importing bank accounts and credit card information, embed Open Ledger’s ConnectBankAccount React component within your product. This component manages all aspects of Open Ledger’s Plaid connection and guides users through the process of granting read-only access to their bank account and credit card activity.

1
import { OpenLedgerProvider, ConnectBankAccount } from "@openledger/accounting-react";
2
3
function App() {
4
  return (
5
    <OpenLedgerProvider
6
      apiUrl="your-api-url"
7
      authToken="your-auth-token"
8
      entityId="your-entity-id"
9
    >
10
      <ConnectBankAccount
11
        onSuccess={(accounts) => console.log("Accounts linked:", accounts)}
12
        onFailure={(error) => console.error("Error:", error)}
13
      >
14
        {(openPlaid, isReady) => (
15
          <button onClick={openPlaid} disabled={!isReady}>
16
            Connect Bank Account
17
          </button>
18
        )}
19
      </ConnectBankAccount>
20
    </OpenLedgerProvider>
21
  );
22
}

API Endpoints

Open Ledger provides API endpoints to manage Plaid integration:

Creating a Plaid Link Token

To initiate the Plaid connection process, you first need to obtain a link token:

1
GET /v1/banks/create-link?entityId={entityId}
2
Authorization: Bearer {access_token}

Response

1
{
2
  "link_token": "link-sandbox-123456-abcdef"
3
}

This link token is used with the Plaid Link interface to guide users through selecting their financial institution and authenticating their accounts.

Adding Bank Accounts

After obtaining a public token from Plaid Link, use it to establish the connection with Open Ledger:

1
PUT /v1/banks/accounts?entityId={entityId}&public_token={plaidPublicToken}
2
Authorization: Bearer {access_token}

Query Parameters

Response

1
{
2
  "createdAccounts": [
3
    {
4
      "id": "acc_12345",
5
      "plaid_access_token": "access-sandbox-12345",
6
      "plaid_item_id": "item-sandbox-12345",
7
      "plaid_institution_id": "ins_12345",
8
      "plaid_account_id": "account_12345",
9
      "account_name": "Checking Account",
10
      "account_type": "CHECKING",
11
      "account_subtype": "checking",
12
      "account_mask": "1234",
13
      "linked_at": "2024-01-15T12:00:00Z",
14
      "status": "ACTIVE",
15
      "entityId": "entity_12345",
16
      "cursor": null,
17
      "needs_initial_sync": true
18
    }
19
  ],
20
  "message": "Accounts created successfully. Transaction sync is running in the background."
21
}

When a bank account is successfully linked, Open Ledger automatically initiates a transaction sync process to import historical transaction data.

Integration Flow

The complete Plaid integration flow works as follows:

1. Your application requests a link token from the /v1/banks/create-link endpoint
2. The link token is used to initialize Plaid Link in your frontend
3. The user selects their financial institution and authenticates
4. Plaid provides a public token to your application
5. Your application sends the public token to the /v1/banks/accounts endpoint
6. Open Ledger exchanges the public token for an access token and retrieves account information
7. Open Ledger creates account records and initiates transaction syncing
8. Transactions are automatically categorized and imported into the ledger

Data Structure

When you link a bank account, Open Ledger stores the following data:

1
{
2
  "id": "acc_12345",
3
  "plaid_access_token": "access-sandbox-12345",
4
  "plaid_item_id": "item-sandbox-12345",
5
  "plaid_institution_id": "ins_12345",
6
  "plaid_account_id": "account_12345",
7
  "account_name": "Checking Account",
8
  "account_type": "CHECKING",
9
  "account_subtype": "checking",
10
  "account_mask": "1234",
11
  "linked_at": "2024-01-15T12:00:00Z",
12
  "status": "ACTIVE",
13
  "entityId": "entity_12345",
14
  "cursor": null,
15
  "needs_initial_sync": true
16
}

Using Plaid Data

With Plaid integration, you can automate many processes that rely on up-to-date financial information:

• Transaction Categorization: Automatically categorize bank transactions using AI, ensuring accuracy and reducing manual entry.
• Financial Reporting: Generate accurate financial reports based on actual bank data.
• Account Reconciliation: Reconcile bank transactions with financial records to ensure accuracy and completeness.

Security and Compliance

Open Ledger takes security seriously when handling sensitive financial data:

• All data transferred between Plaid and Open Ledger is encrypted
• Open Ledger never stores bank credentials
• Plaid access is read-only, ensuring no transactions can be initiated
• Strict access controls ensure data is only accessible to authorized users

Implementation Example

Here’s a complete example of implementing Plaid in a React application:

1
import { useState, useCallback } from "react";
2
import { usePlaidLink } from "react-plaid-link";
3
import { ConnectBankAccount } from "@openledger/accounting-react";
4
5
function PlaidLinkComponent({ entityId, apiUrl, accessToken }) {
6
  const [accounts, setAccounts] = useState([]);
7
  const [error, setError] = useState(null);
8
9
  return (
10
    <ConnectBankAccount
11
      onSuccess={(createdAccounts) => {
12
        console.log("Successfully connected accounts:", createdAccounts);
13
        setAccounts(createdAccounts || []);
14
      }}
15
      onFailure={(error) => {
16
        console.error("Failed to connect accounts:", error);
17
        setError(error.message);
18
      }}
19
    >
20
      {(openPlaid, isReady) => (
21
        <div>
22
          <button 
23
            onClick={openPlaid} 
24
            disabled={!isReady}
25
            className="bg-blue-500 text-white px-4 py-2 rounded disabled:opacity-50"
26
          >
27
            {isReady ? "Connect Bank Account" : "Loading..."}
28
          </button>
29
          
30
          {error && (
31
            <div className="error text-red-500 mt-2">{error}</div>
32
          )}
33
          
34
          {accounts.length > 0 && (
35
            <div className="mt-4">
36
              <h3 className="text-lg font-semibold">Connected Accounts</h3>
37
              <ul className="mt-2">
38
                {accounts.map((account) => (
39
                  <li key={account.id} className="py-1">
40
                    {account.account_name} ({account.account_type}) - ***{account.account_mask}
41
                  </li>
42
                ))}
43
              </ul>
44
            </div>
45
          )}
46
        </div>
47
      )}
48
    </ConnectBankAccount>
49
  );
50
}