plaid-node

A node.js client library for the Plaid API.

Note: This module was recently refactored and released as version 2.0.x to support Plaid's updated API. The previous module version, 1.2.0, and API legacy documentation, is still available via npm and mirroed as plaid-legacy.

plaid-node
- Install
- Getting started
- Methods
- Callbacks
- Error Handling
- Examples
- Promise Support
- Support
- Contributing
- License

Install

$ npm install plaid

Getting started

The module supports all Plaid API endpoints. For complete information about the API, head to the docs.

All endpoints require a valid client_id, secret, and public_key to access and are accessible from a valid instance of a Plaid Client:

const plaid = require('plaid');

const plaidClient = new plaid.Client(client_id, secret, public_key, plaid_env, options);

The plaid_env parameter dictates which Plaid API environment you will access. Values are:

plaid.environments.production - production use, creates Items on https://production.plaid.com
plaid.environments.development - use for integration development and testing, creates Items on https://development.plaid.com
plaid.environments.sandbox - quickly build out your integration with stateful test data, creates Items on https://sandbox.plaid.com

The options parameter is optional and allows for clients to override the default options used to make requests. e.g.

const patientClient = new plaid.Client(client_id, secret, public_key, plaid_env, {
  timeout: 10 * 60 * 1000, // 30 minutes
  agent: 'Patient Agent'
});

See here for a complete list of options. The default timeout for requests is 10 minutes.

Methods

Once an instance of the client has been created you use the following methods:

const plaid = require('plaid');

// Initialize client
const plaidClient = new plaid.Client(client_id, secret, public_key, plaid_env, options);

// createPublicToken(String, Function)
plaidClient.createPublicToken(access_token, cb);
// exchangePublicToken(String, Function)
plaidClient.exchangePublicToken(public_token, cb);
// createProcessorToken(String, String, String, Function)
plaidClient.createProcessorToken(access_token, account_id, processor, cb);

// invalidateAccessToken(String, Function)
plaidClient.invalidateAccessToken(access_token, cb);
// updateAccessTokenVersion(String, Function)
plaidClient.updateAccessTokenVersion(legacy_access_token, cb);
// deleteItem(String, Function)
plaidClient.deleteItem(access_token, cb);
// getItem(String, Function)
plaidClient.getItem(access_token, cb);
// updateItemWebhook(String, String, Function)
plaidClient.updateItemWebhook(access_token, webhook, cb);

// getAccounts(String, Object?, Function)
plaidClient.getAccounts(access_token, options, cb);
// getBalance(String, Object?, Function)
plaidClient.getBalance(access_token, options, cb);
// getAuth(String, Object?, Function)
plaidClient.getAuth(access_token, options, cb);
// getIdentity(String, Function)
plaidClient.getIdentity(access_token, cb);
// getIncome(String, Function)
plaidClient.getIncome(access_token, cb);
// getCreditDetails(String, Function)
plaidClient.getCreditDetails(access_token, cb);

// getTransactions(String, Date(YYYY-MM-DD), Date(YYYY-MM-DD), Object?, Function)
plaidClient.getTransactions(access_token, start_date, end_date, options, cb);

// createStripeToken(String, String, Function)
plaidClient.createStripeToken(access_token, account_id, cb);

// getInstitutions(Number, Number, Function);
plaidClient.getInstitutions(count, offset, cb);
// getInstitutionsById(String, Object?, Function)
plaidClient.getInstitutionById(institution_id, options, cb);
// searchInstitutionsByName(String, [String], Object?, Function)
plaidClient.searchInstitutionsByName(query, products, options, cb);

// getCategories(Function)
plaidClient.getCategories(cb);

// resetLogin(String, Function)
// Sandbox-only endpoint to trigger an `ITEM_LOGIN_REQUIRED` error
plaidClient.resetLogin(access_token, cb);

All parameters except options are required. If the options parameter is omitted, the last argument to the function will be interpreted as the callback.

Callbacks

All requests have callbacks of the following form:

function callback(err, response) {
  // err can be a network error or a Plaid API error (i.e. invalid credentials)
}

Error Handling

The err argument passed to either callback style can either be an instance of Error or a [Plaid API error][3] object. An Error object is only passed back in the case of a HTTP connection error. The following code distinguishes between a Plaid error and a standard Error instance:

function callback(err, response) {
  if (err != null) {
    if (err.error_code != null) {
      // This is a Plaid error
      console.log(err.error_code + ': ' + err.error_message);
    } else {
      // This is a connection error, an Error object
      console.log(err.toString());
    }
  }
}

Examples

Exchange a public_token from Plaid Link for a Plaid access_token and then retrieve account data:

plaidClient.exchangePublicToken(public_token, function(err, res) {
  const access_token = res.access_token;

  plaidClient.getAccounts(access_token, function(err, res) {
    console.log(res.accounts);
  });
});

Retrieve transactions for a transactions user for the last thirty days:

const now = moment();
const today = now.format('YYYY-MM-DD');
const thirtyDaysAgo = now.subtract(30, 'days').format('YYYY-MM-DD');

plaidClient.getTransactions(access_token, thirtyDaysAgo, today, (err, res) => {
  console.log(`You have ${res.transactions.length} transactions from the last thirty days.`);
});

Get accounts for a particular Item:

plaidClient.getAccounts(access_token, {
  account_ids: ['123456790']
}, (err, res) => {
  console.log(res.accounts);
});

// The library also juggles arguments, when options is omitted

plaidClient.getAccounts(access_token, (err, res) => {
  console.log(res.accounts);
});

Promise Support

Every method returns a promise, so you don't have to use the callbacks.

API methods that return either a success or an error can be used with the usual then/else paradigm, e.g.

plaidPromise.then(successResponse => {
  // ...
}).catch(err => {
  // ...
});

Plaid API methods that may return an MFA response pass an array of responses to the next promise. The first element of the array is the mfaResponse, and the second element is the successResponse. You can use destructuring to improve readability.

For example:

const plaid = require('plaid');

const plaidClient = new plaid.Client(CLIENT_ID, SECRET, PUBLIC_KEY, plaid.environments.SANDBOX);

plaidClient.getInstitutions(1, 0).then(successResponse => {
  return successResponse.institutions;
}).catch(err => {
  throw new Error(`Unreachable code block for example: ${err}`);
}).then(institutions => {
  const institution = institutions[0];
  const institutionId = institution.institution_id;
  const products = ['transactions', 'info', 'numbers'];

  const credentials = {
    username: 'user_good',
    password: 'pass_good'
  };

  return plaidClient.createItem(credentials, institutionId, products);
}).then(([mfaResponse, successResponse]) => {
  if (mfaResponse) {
    throw new Error(`Unreachable code block for example: ${mfaResponse}`);
  }

  return plaidClient.getAccounts(successResponse.access_token);
}).catch(err => {
  throw new Error(`Unreachable code block for example: ${err}`);
}).then(successResponse => {
  console.log(successResponse.accounts);
});

The following is also valid:

const promise = plaidClient.createItem(credentials, institutionId, products);

promise.then(array => {
  const mfaResponse = array[0];
  const successResponse = array[1];

  // do something
}).catch(err => {
  console.log(err);
});

Support

Open an issue!

Contributing

Click here!

License

MIT

nathankot/plaid-node