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 Bank Linking 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, BankLinking } 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
      <SettingsView
11
        onSuccess={(accounts) => console.log("Accounts linked:", accounts)}
12
        onError={(error) => console.error("Error:", error)}
13
      />
14
    </OpenLedgerProvider>
15
  );
16
}

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
2
Authorization: Bearer {access_token}

Response

1
{
2
  "link_token": "link-sandbox-123456-abcdef",
3
  "expiration": "2023-01-01T00:00:00Z"
4
}

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": "plaid_acc_12345",
5
      "plaidAccessToken": "access-sandbox-12345",
6
      "plaidItemId": "item-sandbox-12345",
7
      "plaidInstitutionId": "ins_12345",
8
      "plaidAccountId": "account_12345",
9
      "accountName": "Checking Account",
10
      "accountType": "CHECKING",
11
      "accountSubtype": "checking",
12
      "accountMask": "1234",
13
      "linkedAt": "2024-01-15T12:00:00Z",
14
      "status": "ACTIVE",
15
      "entityId": "entity_12345",
16
      "needsInitialSync": true
17
    }
18
  ]
19
}

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": "plaid_acc_12345",
3
  "plaidAccessToken": "access-sandbox-12345",
4
  "plaidItemId": "item-sandbox-12345",
5
  "plaidInstitutionId": "ins_12345",
6
  "plaidAccountId": "account_12345",
7
  "accountName": "Checking Account",
8
  "accountType": "CHECKING",
9
  "accountSubtype": "checking",
10
  "accountMask": "1234",
11
  "linkedAt": "2024-01-15T12:00:00Z",
12
  "status": "ACTIVE",
13
  "entityId": "entity_12345",
14
  "cursor": null,
15
  "needsInitialSync": 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 axios from "axios";
4
5
function PlaidLinkComponent({ entityId, token }) {
6
  const [accounts, setAccounts] = useState([]);
7
  const [error, setError] = useState(null);
8
9
  // Step 1: Get a link token from your server
10
  const getPlaidLinkToken = async () => {
11
    try {
12
      const response = await axios.get("/v1/banks/create-link", {
13
        headers: { Authorization: `Bearer ${token}` },
14
      });
15
      return response.data.link_token;
16
    } catch (err) {
17
      setError("Failed to get link token");
18
      console.error(err);
19
    }
20
  };
21
22
  // Step 2: Handle successful Plaid Link connection
23
  const handleSuccess = useCallback(
24
    async (publicToken) => {
25
      try {
26
        const response = await axios.put(
27
          `/v1/banks/accounts?entityId=${entityId}&public_token=${publicToken}`,
28
          {},
29
          {
30
            headers: { Authorization: `Bearer ${token}` },
31
          }
32
        );
33
        setAccounts(response.data.createdAccounts || []);
34
      } catch (err) {
35
        setError("Failed to link accounts");
36
        console.error(err);
37
      }
38
    },
39
    [entityId, token]
40
  );
41
42
  // Configure Plaid Link
43
  const { open, ready } = usePlaidLink({
44
    token: linkToken,
45
    onSuccess: (public_token) => handleSuccess(public_token),
46
    onExit: (err) => {
47
      if (err) setError(err.message || "Exit from Plaid Link");
48
    },
49
  });
50
51
  return (
52
    <div>
53
      <button onClick={() => open()} disabled={!ready}>
54
        Connect Bank Account
55
      </button>
56
      {error && <div className="error">{error}</div>}
57
      {accounts.length > 0 && (
58
        <div>
59
          <h3>Connected Accounts</h3>
60
          <ul>
61
            {accounts.map((account) => (
62
              <li key={account.id}>
63
                {account.accountName} ({account.accountType})
64
              </li>
65
            ))}
66
          </ul>
67
        </div>
68
      )}
69
    </div>
70
  );
71
}

Support and Troubleshooting

If you encounter any issues with Plaid integration or have any questions, please contact Open Ledger support. Our team is available to provide assistance and ensure that your experience with Plaid integration is seamless and beneficial.