​
Provider Specific Instructions

Plaid integration

Overview

Through Teal’s official processor partnership with Plaid, your users can connect their external financial accounts with Teal using your business’ Plaid account and custom user experience. Syncing accounts imports up to two years of data and keeps the account up to date daily.

This integration is useful if you are building full-service accounting using PlatformGL and require users to connect their financial institutions. If an Instance uses QuickBooks as their accounting package, users must connect their accounts via Quickbooks’ connections interface.

Steps

This guide walks you through the steps necessary to set up Plaid, how to pass that information back to Teal, and how to connect to our webhooks so you can diagnose and respond to events from Plaid.

Prerequisites

This guide assumes you have a Plaid account set up and a Teal Platform with an instance that is using PlatformGL as their accounting platform.

Enable the Plaid-Teal integration

The Plaid-Teal integration can be found in the integrations section of your Plaid dashboard. Ensure that it is set to Enabled.

Build your Plaid-Teal integration

You will need to use Plaid Link to give authorization for Plaid to access a user’s accounts. Follow the Plaid-Teal integration guide which walks you through the necessary steps. To summarize, there are four steps involved:

  1. Request a link_token to allow your app to use Plaid Link.

When requesting a link_token be sure to set the days_requested parameter if you are initializing the link token with transactions. If days_requested is not set and the link is initialized with transactions, Plaid will only return 90 days of transactions to Teal.

{
  "client_id": "${PLAID_CLIENT_ID}",
  "secret": "${PLAID_SECRET}",
  "user": {
  "client_user_id": "user-id"
},
  "client_name": "Personal Finance App",
  "products": [
  "transactions"
  ],
  "transactions": {
  "days_requested": 730
},
  "country_codes": [
  "US"
  ],
  "language": "en"
}
  1. After the user completes the Plaid Link flow, exchange the resulting public_token for an access_token.
  2. Store your access_token for later use and use it to request a processor_token.
  3. Send the processor_token to Teal and optionally request an opening balance by setting calculate_opening_balance to true.

Plaid supports three environments: sandbox, development, and production. All three can generate processor_tokens. To work with real transactions, you need to generate your processor_token using Plaid production environment.

After Teal has saved the processor_token, a new ledger for the financial account will be created and sync up to two years of transactions, if possible; it can take a few minutes for all the transactions to be processed. If calculate_opening_balance was set to true, we’ll calculate the starting balance based on the entries_start date of the Instance.

Once Teal has received the transactions, they will be run through Teal’s auto-categorization system. These will be synced once per day and when Plaid sends us a webhook event saying there are new transactions available.

For the end-user, this flow is commonly done as part of an “account connections” workflow, either as part of onboarding or as part of an account page. Your users will need to possibly go through this flow multiple times to connect all their business accounts.

Maintain the connection

After creating the Plaid connection, it will request new transactions for the linked account(s) every 4-6 hours without the need for user or developer input. You can also use the connection to:

  • Retrieve a ledger’s balanced status: using this endpoint, Teal will query Plaid for the account balance and compare the balance to what is recorded. An account is considered balanced if it was balanced within the past week.
  • Check a ledger for new transactions: this endpoint requests new transactions from Plaid. This is helpful if you are trying to provide the most up-to-date information for your users. The request is asynchronous and will trigger the transactions.source.processing.completed webhook if successful.
  • Update a Transaction Source: this endpoint allows you to manually update the auth_token for a ledger source with a new access_token from Plaid. This may be helpful when using Plaid Link’s Update Mode and your users may add duplicate accounts. See Plaid’s documentation on update mode and Preventing Duplicate Items.

Webhooks

Plaid can sometimes run into issues connecting to your users’ financial accounts. For example, banks may require users to re-authenticate their Plaid connection every 90 days or if a user changes their banking password. Using SVIX, a popular webhooks service, we aggregate these webhook responses from Plaid into two endpoints: transactions.source.processing.completed and transactions.source.processing.error.

Receive messages from these endpoints for two primary use cases:

  • Using transactions.source.processing.error, you can alert users when their connections have expired and they need to reconnect their bank account via Plaid. See Plaid’s Error documentation for a comprehensive list.
  • transactions.source.processing.completed sends a message when we have successfully imported transactions from Plaid. You can use this to inform users when their last sync date was with Plaid.

Go to your Webhook Dashboard and click the “Setup webhooks” button, if you haven’t yet, to get started. Through this dashboard, you can add endpoints, test events, and see your webhook logs.

When configuring your receiving endpoint on your server, please send back 2xx codes, so we know the webhook messages were well received.

We highly recommend reading SVIX’s webhook documentation, which describes how to use the Webhooks Dashboard, specifically how to verify and test webhooks.

Delete or disable a connection

There are times when you may need to delete or disable a connection to a ledger. For example, you may need to delete a connection if a user no longer wants their account connected to your application; or, you may disable Plaid connections for a customer who has exceeded their free trial period.

Delete a connection

Use the Delete the Transaction Source endpoint to delete the Plaid connection from a ledger.

Deleting a connection will not delete the transactions in the ledger; it will only delete the connection to Plaid.

Disable a connection

Use the Update the Transaction Source to toggle the status of the connection to a ledger. This will not delete the connection, but if the connection has been disabled for long enough, the institution may require the user to log back in using the Plaid Link flow.

Further reading

Opening balancesImport via API