plaid-node

The PlaidEnvironments parameter dictates which Plaid API environment you will access:

• PlaidEnvironments.production: Production use and live data testing. Creates Items on https://production.plaid.com
• PlaidEnvironments.sandbox: Quickly build out your integration with stateful test data. Creates Items on https://sandbox.plaid.com

To use the Plaid API, you must create a Configuration object containing your client_id and secret in the baseOptions.headers. You must also specify a basePath using PlaidEnvironments to determine which environment (e.g., sandbox or production) you are accessing. The baseOptions field accepts standard Axios request options.

import { Configuration, PlaidApi, PlaidEnvironments } from 'plaid';

const configuration = new Configuration({
  basePath: PlaidEnvironments.sandbox,
  baseOptions: {
    headers: {
      'PLAID-CLIENT-ID': CLIENT_ID,
      'PLAID-SECRET': SECRET,
    },
  },
});

const plaidClient = new PlaidApi(configuration);

Version 9.0.0 introduced a major interface change. The library transitioned to using an OpenAPI 3.0.0 specification generated via typescript-axios. Key changes include:

1. Client Initialization: The plaid.Client constructor is replaced by a Configuration object passed to a PlaidApi instance.
2. Endpoints: Requests now require a request model object instead of positional arguments. Function names have changed to follow a resourceVerb pattern (e.g., getTransactions becomes transactionsGet). Callbacks are no longer supported; use Promises/async-await.
3. Error Handling: Errors are now handled via Promise rejection. Error details are located in error.response.data.
4. Enums: You can use either raw strings or the provided Node enums.

Install the official Plaid Node.js client library using npm.

$ npm install plaid

All API methods return promises, allowing you to use try/catch with async/await or .catch() for promise chaining.

Security Warning: The full error object includes the API configuration object, which contains your PLAID-CLIENT-ID and PLAID-SECRET in the headers. To avoid leaking credentials in logs, do not log the full error object. Instead, log only error.response.data or specific fields from the error response.

try {
  await plaidClient.transactionsSync(request);
} catch (error) {
  // Log only the response data to avoid leaking secrets in error.config.headers
  const err = error.response.data;
  console.error(err);
}

If you receive webhooks with empty bodies in Next.js, it is likely due to the bodyParser middleware. To fix this, disable the default body parser in your route config and use the micro buffer to read the raw request body.

import { buffer } from 'micro'

export default async function handler(req, res) {
  const rawBody = await buffer(req)
  const body = JSON.parse(rawBody.toString())

  // Process webhook...
  res.status(200).json({ status: 'ok' })
}

export const config = {
  api: { bodyParser: false }
}

To download an Asset Report as a PDF, use assetReportPdfGet. You must pass responseType: 'arraybuffer' in the second argument (the Axios request options) to receive the binary data.

import fs from 'fs';

const pdfResp = await plaidClient.assetReportPdfGet(
  {
    asset_report_token: assetReportToken,
  },
  {
    responseType: 'arraybuffer',
  },
);

fs.writeFileSync('asset_report.pdf', pdfResp.data);

The transactionsSync method is the recommended way to retrieve transaction data for a user.

const response = await plaidClient.transactionsSync({
  access_token
});
const transactions = response.data.transactions;

Use itemPublicTokenExchange to exchange a public_token received from Plaid Link for a permanent access_token, which is then used for subsequent API calls like accountsGet.

const response = await plaidClient.itemPublicTokenExchange({ public_token });
const access_token = response.data.access_token;
const accounts_response = await plaidClient.accountsGet({ access_token });
const accounts = accounts_response.data.accounts;

You can retrieve transactions for a specific date range using the older transactionsGet method by providing start_date and end_date in 'YYYY-MM-DD' format.

const today = new Date().toISOString().slice(0, 10);
const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000)
  .toISOString()
  .slice(0, 10);

const response = await plaidClient.transactionsGet({
  access_token,
  start_date: thirtyDaysAgo,
  end_date: today,
});
const transactions = response.data.transactions;

Since callbacks are no longer supported, use try/catch blocks or .catch() to handle errors. Error details (like error_code) are found in the response.data property of the caught error.

try {
  await plaidClient.transactionsGet(request);
} catch (error) {
  const err = error.response.data;
  // Handle error using err.error_code, etc.
}