Add Transactions to your app

Learn how to fetch Transactions data for your users

Try out the Pattern Demo for a demonstration of a sample app that uses Plaid's Transactions product for the personal financial management use case.

In this guide, we'll start from scratch and walk through how to use Transactions to perform an initial fetch of a user's transaction history. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to Fetching transaction data.

For a detailed, step-by-step view, you can also watch our full-length, comprehensive tutorial walkthrough on integrating transactions.

Get Plaid API keys and complete application and company profile

If you don't already have one, you'll need to create a Plaid developer account. After creating your account, you can find your API keys under the Team Settings menu on the Plaid Dashboard.

You will also need to complete your application profile and company profile on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the Plaid Portal. Your application profile and company profile must be completed before connecting to certain institutions in Production.

Install and initialize Plaid libraries

You can use our official server-side client libraries to connect to the Plaid API from your application:

Terminal
Select Language
1// Install via npm
2npm install --save plaid

After you've installed Plaid's client libraries, you can initialize them by passing in your client_id, secret, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your client_id and secret with each request, and you won't need to explicitly include them in any other calls.

server.js
Select Language
1// Using Express
2const express = require('express');
3const app = express();
4app.use(express.json());
5
6const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
7
8const configuration = new Configuration({
9  basePath: PlaidEnvironments.sandbox,
10  baseOptions: {
11    headers: {
12      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
13      'PLAID-SECRET': process.env.PLAID_SECRET,
14    },
15  },
16});
17
18const client = new PlaidApi(configuration);

Create an Item with Link

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the Link documentation.

Using Link, we will create a Plaid Item, which is a Plaid term for a login at a financial institution. An Item is not the same as a financial institution account, although every account will be associated with an Item. For example, if a user has one login at their bank that allows them to access both their checking account and their savings account, a single Item would be associated with both of those accounts. If you want to customize Link's look and feel, you can do so from the Dashboard.

Before initializing Link, you will need to create a new link_token on the server side of your application. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the /link/token/create endpoint. Then, on the client side of your application, you'll need to initialize Link with the link_token that you just created.

The /link/token/create sample code below will create an Item with a maximum of 90 days of transaction history. To request more, set the transactions.days_requested parameter in the /link/token/create request.

Create a link_token

server.js
Select Language
1app.post('/api/create_link_token', async function (request, response) {
// Get the client_user_id by searching for the current user
const user = await User.find(...);
const clientUserId = user.id;
const request = {
  user: {
    // This should correspond to a unique id for the current user.
    client_user_id: clientUserId,
  },
  client_name: 'Plaid Test App',
  products: ['transactions'],
  language: 'en',
  webhook: 'https://webhook.example.com',
  redirect_uri: 'https://domainname.com/oauth-page.html',
  country_codes: ['US'],
};
try {
  const createTokenResponse = await client.linkTokenCreate(request);
  response.json(createTokenResponse.data);
} catch (error) {
  // handle error
}
23});

Install Link dependency

index.html
Select Language
1<head>
2  <title>Connect a bank</title>
3  <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
4</head>

Configure the client-side Link handler

app.js
1const linkHandler = Plaid.create({
token: (await $.post('/create_link_token)).link_token,
onSuccess: (public_token, metadata) => {
  // Send the public_token to your app server.
  $.post('/exchange_public_token', {
    public_token: public_token,
  });
},
onExit: (err, metadata) => {
  // Optionally capture when your user exited the Link flow.
  // Storing this information can be helpful for support.
},
onEvent: (eventName, metadata) => {
  // Optionally capture Link flow events, streamed through
  // this callback as your users connect an Item to Plaid.
},
17});
18
19linkHandler.open();

Get a persistent access token

Next, on the server side, we need to exchange our public_token for an access_token and item_id. The access_token will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the /item/public_token/exchange endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.

Save the access_token and item_id in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The access_token will remain valid unless you actively chose to expire it via rotation or remove the corresponding Item via /item/remove. The access_token should be stored securely, and never in client-side code. A public_token is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.

Select group for content switcher

server.js
Select Language
1app.post('/api/exchange_public_token', async function (
2  request,
3  response,
4  next,
5) {
6  const publicToken = request.body.public_token;
7  try {
8    const response = await client.itemPublicTokenExchange({
9      public_token: publicToken,
10    });
11
12    // These values should be saved to a persistent database and
13    // associated with the currently signed-in user
14    const accessToken = response.data.access_token;
15    const itemID = response.data.item_id;
16
17    res.json({ public_token_exchange: 'complete' });
18  } catch (error) {
19    // handle error
20  }
21});

Fetching transaction data

Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API and fetch transaction data using the /transactions/sync endpoint.

The /transactions/sync endpoint is used to both initialize your view of transactions data, and keep you current with any changes that have occurred. When you first call it on an Item with no cursor parameter, transactions data available at that time is returned. If more updates are available than requested with the count parameter (maximum of 500), has_more will be set to true, indicating the endpoint should be called again, using the next_cursor from the previous response in the cursor field of the next request, to receive another page of data. After successfully pulling all currently available pages, you can store the cursor for later requests, allowing Plaid to send you new updates from when you last queried the endpoint.

Note that if you encounter an error during pagination, it's important to restart the pagination loop from the beginning. For more details, see the documentation for TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION. For sample code for handling the error, see the /transactions/sync API reference.

Typically, the first 30 days of transaction history is available to be fetched almost immediately, but full transaction history may take a minute or more to become available. If you get an empty response when calling /transactions/sync shortly after linking an Item, it's likely that the first 30 days of transaction history has not yet been pulled. You will need to call the endpoint when the data is pulled. Similarly, if you only get the first 30 days of transaction history, you will need to wait until it is complete, and call the endpoint again.

To be notified whenever additional data becomes available, see Transaction webhooks.

/transactions/sync
Select Language
1// Provide a cursor from your database if you've previously
2// received one for the Item. Leave null if this is your
3// first sync call for this Item. The first request will
4// return a cursor.
5let cursor = database.getLatestCursorOrNull(itemId);
6
7// New transaction updates since "cursor"
8let added: Array<Transaction> = [];
9let modified: Array<Transaction> = [];
10// Removed transaction ids
11let removed: Array<RemovedTransaction> = [];
12let hasMore = true;
13
14// Iterate through each page of new transaction updates for item
15while (hasMore) {
16  const request: TransactionsSyncRequest = {
17    access_token: accessToken,
18    cursor: cursor,
19  };
20  const response = await client.transactionsSync(request);
21  const data = response.data;
22
23  // Add this page of results
24  added = added.concat(data.added);
25  modified = modified.concat(data.modified);
26  removed = removed.concat(data.removed);
27
28  hasMore = data.has_more;
29
30  // Update cursor to the next cursor
31  cursor = data.next_cursor;
32}
33
34// Persist cursor and updated data
35database.applyUpdates(itemId, added, modified, removed, cursor);

Updating transaction data

After your initial /transactions/sync request, you may want your application to be notified when any transactions are added, removed, or modified in order to immediately fetch them from /transactions/sync. To learn how, see Transaction Webhooks.

Example code in Plaid Pattern

For a real-life example of an app that incorporates transactions, see the Node-based Plaid Pattern sample app. Pattern is a sample financial management app that fetches transactions data upon receipt of transactions webhooks. Transactions code in Plaid Pattern can be found in handleTransactionsWebhook.js.