Registry / payments / plaid
library0.1.7jsnpmunverified

The `plaid` package is the official Node.js client library for interacting with the Plaid API, providing programmatic access to financial data. Currently at version 42.1.0, the library is actively maintained with updates typically released on a monthly basis, aligning with Plaid API developments. It is generated directly from Plaid's OpenAPI schema, ensuring comprehensive coverage of the latest API version (specifically `2020-09-14`). A key differentiator is its direct support for various Plaid environments (sandbox, development, production) and its use of semantic versioning, with major version increments indicating potentially breaking changes. This client simplifies authentication and API request handling, abstracting the underlying HTTP requests and providing TypeScript type definitions for robust development.

npm install plaid
INSTALL
IMPORT
SIG · PLAID
P
plaid
paymentsjavascriptv0.1.7
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Configuration
✓ import { Configuration } from 'plaid';
✗ const Configuration = require('plaid').Configuration;
The library primarily uses named exports and is designed for ESM. CommonJS 'require' syntax will not work as expected with modern versions.
PlaidApi
✓ import { PlaidApi } from 'plaid';
✗ import PlaidApi from 'plaid';
PlaidApi is a named export, not a default export. Ensure you destructure it correctly.
PlaidEnvironments
✓ import { PlaidEnvironments } from 'plaid';
✗ const PlaidEnvironments = require('plaid').PlaidEnvironments;
Used to select the target Plaid environment (e.g., sandbox, production). Like other core components, it's a named export and benefits from TypeScript typing.

This quickstart demonstrates how to initialize the Plaid client with API credentials and environment, then fetch a list of top institutions using the `institutionsGet` endpoint. It includes basic error handling and best practices for environment variables and API versioning.

import { Configuration, PlaidApi, PlaidEnvironments, Products, CountryCode } from 'plaid'; // Replace with your actual Plaid API credentials. Consider using environment variables. const CLIENT_ID = process.env.PLAID_CLIENT_ID ?? 'your_client_id'; const SECRET = process.env.PLAID_SECRET ?? 'your_secret'; // Configure the Plaid client const configuration = new Configuration({ basePath: PlaidEnvironments.sandbox, // Or PlaidEnvironments.production for live data baseOptions: { headers: { 'PLAID-CLIENT-ID': CLIENT_ID, 'PLAID-SECRET': SECRET, 'Plaid-Version': '2020-09-14', // Recommended to explicitly set the API version }, }, }); const plaidClient = new PlaidApi(configuration); async function getPlaidInstitutions() { try { // Define a request to fetch some institutions const request = { country_codes: [CountryCode.Us], products: [Products.Auth], count: 5, offset: 0, }; const response = await plaidClient.institutionsGet(request); console.log('Successfully fetched top 5 Institutions:'); response.data.institutions.forEach(inst => console.log(`- ${inst.name} (ID: ${inst.institution_id})`)); return response.data.institutions; } catch (error: any) { if (error.response) { // Log only necessary parts to avoid exposing secrets in error.response.config.headers console.error('Plaid API Error:', error.response.data); } else { console.error('Plaid Client Error:', error.message); } throw error; } } // Run the example PlaidEnvironments.sandbox === configuration.basePath ? getPlaidInstitutions().then(() => console.log('\nExample complete using Sandbox environment.')) : console.warn('Warning: Not running institution fetch in non-sandbox environment for quickstart.');
Debug
Known issues
breakingMajor version bumps of the `plaid-node` client library (e.g., from v8 to v9, or v9 to v42) often introduce breaking changes. Version 9.0.0, released in August 2021, represented a significant interface change due to the transition to an OpenAPI spec-generated client. Always consult the client library changelog and migration guide when upgrading major versions.
fix
Review the official Plaid client library changelog on GitHub and the API upgrade guide for specific migration instructions for your target version. Pay close attention to changes in model imports, enum usage, and request/response structures.
affects: >=9.0.0
gotchaThe `plaid-node` client library is explicitly designed to support the `2020-09-14` Plaid API version. Using an outdated client library or implicitly relying on an older API version can lead to unexpected behavior or missing features.
fix
Always ensure your client library is updated to a recent version. Explicitly include `'Plaid-Version': '2020-09-14'` in your request headers via `baseOptions` during `Configuration` initialization to guarantee API version compatibility.
affects: <42.0.0
gotchaWhen handling errors, logging the full error object directly (e.g., `console.error(error)`) can expose sensitive API keys and secrets embedded in `error.response.config.headers`.
fix
Only log specific parts of the error object, such as `error.response.data` for API-specific error details, and avoid logging `error.response.config.headers` or the entire `error` object.
affects: >=1.0.0
gotchaDates and datetimes in Plaid API requests have strict string formatting requirements. `format: date` requires `'YYYY-MM-DD'` and `format: date-time` requires `'YYYY-MM-DDTHH:mm:ssZ'`. Failing to adhere to these formats or omitting time zone information for datetimes will result in an API error.
fix
Ensure all date and datetime strings sent in API requests precisely match the specified `YYYY-MM-DD` or `YYYY-MM-DDTHH:mm:ssZ` (ISO 8601) formats, including the 'Z' for UTC if applicable. For TypeScript, consider using helper functions or libraries to ensure correct formatting.
affects: >=1.0.0
Errors
Common errors & fixes
Plaid API Error: { "error_code": "INVALID_CREDENTIALS", "error_message": "client_id or secret is invalid", ... }
The Plaid API client was initialized with incorrect or missing `PLAID-CLIENT-ID` or `PLAID-SECRET` headers.
fix
Verify that your `PLAID_CLIENT_ID` and `PLAID_SECRET` environment variables (or hardcoded values during development) exactly match your credentials from the Plaid Dashboard for the chosen environment (Sandbox, Development, or Production).
TypeError: Cannot read properties of undefined (reading 'Configuration') OR PlaidApi is not a constructor
Attempting to use CommonJS `require()` syntax with a library that is primarily designed for ES Modules (ESM) and uses named exports, especially in a modern Node.js project where `type: "module"` is set in `package.json`.
fix
Switch to ES Module `import` statements: `import { Configuration, PlaidApi, PlaidEnvironments } from 'plaid';`. If you must use CommonJS, ensure your environment supports it correctly, or investigate if an older version of the library explicitly supported CommonJS exports.
Plaid API Error: { "error_code": "INVALID_INPUT", "error_message": "'start_date' must be in the format 'YYYY-MM-DD'", ... }
A date field in an API request (e.g., `start_date`, `end_date` for transactions) was not provided in the required `YYYY-MM-DD` string format.
fix
Review the specific endpoint documentation for the correct date format. Ensure all date parameters are formatted as `YYYY-MM-DD` strings. For datetimes, use `YYYY-MM-DDTHH:mm:ssZ`.
Upgrade
Version history
0.1.7latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
27 hits · last 30 days
node
24
OpenAI (training)
1
Resources
plaid — npm install plaid · libregistry