Get started with the Quickstart

A quick introduction to building with Plaid

Not a developer? Check out the Plaid Postman Collection for a no-code way to get started with Plaid's API.

Introduction

Let’s test out running Plaid locally by cloning the Quickstart app. You’ll need API keys, which you can receive by signing up in the Dashboard.

You'll have two different API keys, and there are three different Plaid environments. Today we'll start in the Sandbox environment. View the API Keys section of the Dashboard to find your Sandbox secret.

API Key
View Keys in Dashboard
client_id
Private identifier for your team
secret
Private key, one for each of the three environments
Environment
Sandbox
Get started with test credentials and life-like data
Development
Build out your app with up to 100 live credentials
Production
Launch your app with unlimited live credentials

If you get stuck at any point in the Quickstart, help is just a click away! Ask other developers in our Stack Overflow community or submit a Support ticket.

Quickstart setup

Once you have your API keys, it's time to run the Plaid Quickstart locally! The instructions below will guide you through the process of cloning the Quickstart repository, customizing the .env file with your own Plaid client ID and Sandbox secret, and finally, building and running the app.

Plaid offers both Docker and non-Docker options for the Quickstart. If you already have Docker on your system, we recommend the Docker option because it is simpler and easier to run the Quickstart. However, if you don't already have Docker installed, you may wish to use the non-Docker version; this path is especially recommended for Windows users who do not have Docker installations. Below are instructions on setting up the Quickstart with Docker and non-Docker configurations.

Setting up with Docker

Docker is a software platform that packages software into standardized units called containers that have everything the software needs to run, including libraries, system tools, code, and runtime. If you don't already have Docker, you can download it from the Docker site. Note that Windows users may need to take some additional steps, such installing a Linux environment; if you are using Windows and do not already have a Linux environment installed, we recommend selecting the non-Docker instructions instead. Once Docker is installed, launch the Docker app, then use the following commands at the command line to configure and run the Quickstart.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Note: If on Windows, run
# git clone -c core.symlinks=true https://github.com/plaid/quickstart
# instead to ensure correct symlink behavior
git clone https://github.com/plaid/quickstart.git
cd quickstart
# Copy the .env.example file to .env, then fill
# out PLAID_CLIENT_ID and PLAID_SECRET in .env
cp .env.example .env
# start the container for one of these languages:
# node, python, java, ruby, or go
make up language=node
# Go to http://localhost:3000
2. Visit localhost and log in with Sandbox credentials
1
$ make logs language=node
1
$ make stop language=node

If the commands above do not work, make sure that Docker is running. You may also need to prefix the make commands with sudo, depending on your environment.

If you're in Europe, see the Setting up in Europe section for additional instructions.

Setting up OAuth

OAuth is an authentication flow, used by some Plaid-supported institutions, in which the end user is redirected to the bank’s website or mobile app to authenticate. To support this flow, you should provide two environment variables in your .env file in addition to the PLAID_CLIENT_ID and PLAID_SECRET variables you filled in above. These are the PLAID_REDIRECT_URI and PLAID_COUNTRY_CODES variables:

1
2
3
# ...
PLAID_COUNTRY_CODES=GB # Or any supported country (US, CA, ES, FR, GB, IE, NL)
PLAID_REDIRECT_URI=http://localhost:3000/

When running in Production or Development, you will need to use an https:// redirect URI, but a localhost http URI will work fine for Sandbox.

You will also need to configure this PLAID_REDIRECT_URI for your client ID through the Plaid developer dashboard.

Setting up for Payment Initiation (UK and Europe only)

When using the UK and Europe-only Payment Initiation product with the Quickstart, two additional steps are necessary.

First, it is necessary to specify payment_initiation as the only product in the PLAID_PRODUCTS environment variable in .env. No other products can be specified when using the Payment Initiation Quickstart.

1
2
3
4
# ...
PLAID_COUNTRY_CODES=GB # Or any supported European countries (ES, FR, GB, IE, NL)
PLAID_REDIRECT_URI=http://localhost:3000/
PLAID_PRODUCTS=payment_initiation

In addition, the Payment Initiation product is not enabled in Sandbox by default. To run the Payment Initiation Quickstart, contact Sales to enable Payment Initiation for your account.

Create your first Item

Most API requests interact with an Item, which is a Plaid term for a login at a financial institution. A single end-user of your application might have accounts at different financial institutions, which means they would have multiple different Items. 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.

Now that you have the Quickstart running, you’ll add your first Item in the Sandbox environment. Once you’ve opened the Quickstart app on localhost, click the Launch Link button and select any institution. Use the Sandbox credentials to simulate a successful login.

Sandbox credentials
1
2
username: user_good
password: pass_good

Once you have entered your credentials and moved to the next screen, you have created your first Item! You can now make API calls for that Item by using the buttons in the Quickstart. In the next section, we'll explain what actually happened and how the Quickstart works.

How it works

As you might have noticed, you use both a server and a client-side component to access the Plaid APIs. The flow looks like this:

The Plaid flow begins when your user wants to connect their bank account to your app.
Step  diagram
1Make a request to create a link_token and pass the temporary token to your app's client.
Step 1 diagram
2Use the link_token to open Link for your user. In the onSuccess callback, send the temporary public_token to your app's server.
Step 2 diagram
3Make a request to exchange the public_token for a permanent access_token and item_id for the new Item.
Step 3 diagram
4Store the access_token and use it to make product requests for your user's Item.
Step 4 diagram

The first step is to create a new link_token by making a /link/token/create request and passing in the required configurations. This link_token is a short lived, one-time use token that authenticates your app with Plaid Link, our frontend module. Several of the environment variables you configured when launching the Quickstart, such as PLAID_PRODUCTS, are used as parameters for the link_token.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// Using Express
const express = require('express');
const app = express();
app.use(express.json());
const plaid = require('plaid');
const client = new plaid.Client({
clientID: process.env.PLAID_CLIENT_ID,
secret: process.env.PLAID_SECRET,
env: plaid.environments.sandbox,
});
app.post('/create_link_token', async (request, response) => {
try {
// Get the client_user_id by searching for the current user
const user = await User.find(...);
const clientUserId = user.id;
// Create the link_token with all of your configurations
const tokenResponse = await client.createLinkToken({
user: {
client_user_id: clientUserId,
},
client_name: 'Plaid Test App',
products: ["auth"],
country_codes: ['US'],
language: 'en',
webhook: 'https://webhook.sample.com',
});
response.json(tokenResponse);
} catch (e) {
// Display error on client
return response.send({ error: e.message });
}
});

Once you have a link_token, you can use it to initialize Link. Link is a drop-in client-side module available for web, iOS, and Android that handles the authentication process. The Quickstart uses Link on the web, which is a pure JavaScript integration that you trigger via your own client-side code. This is what your users use to log into their financial institution accounts.

After a user submits their credentials within Link, Link provides you with a public_token via the onSuccess callback. The code below shows how the Quickstart passes the public_token from client-side code to the server. Both React and vanilla JavaScript examples are shown.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// APP COMPONENT
// Upon rendering of App component, make a request to create and
// obtain a link token to be used in the Link component
import React, { useEffect, useState } from 'react';
import { usePlaidLink } from 'react-plaid-link';
const App = () => {
const [linkToken, setLinkToken] = useState(null);
const generateToken = async () => {
const response = await fetch('/api/create_link_token', {
method: 'POST',
});
const data = await response.json();
setLinkToken(data.link_token);
};
useEffect(() => {
generateToken();
}, []);
return linkToken != null ? <Link linkToken={linkToken} /> : <></>;
};
// LINK COMPONENT
// Use Plaid Link and pass link token and onSuccess function
// in configuration to initialize Plaid Link
interface LinkProps {
linkToken: string | null;
}
const Link: React.FC<LinkProps> = (props: LinkProps) => {
const onSuccess = React.useCallback((public_token, metadata) => {
// send public_token to server
const response = fetch('/api/set_access_token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({ public_token }),
});
// Handle response ...
}, []);
const config: Parameters<typeof usePlaidLink>[0] = {
token: props.linkToken!,
onSuccess,
};
const { open, ready } = usePlaidLink(config);
return (
<button onClick={() => open()} disabled={!ready}>
Link account
</button>
);
};
export default App;

Next, on the server side, the Quickstart calls /item/public_token/exchange to obtain an access_token, as illustrated in the code excerpt below. The access_token uniquely identifies an Item and is a required argument for most Plaid API endpoints. In your own code, you'll need to securely store your access_token in order to make API requests for that Item.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// Using Express
const express = require('express');
const app = express();
app.use(express.json());
const plaid = require('plaid');
const client = new plaid.Client({
clientID: process.env.PLAID_CLIENT_ID,
secret: process.env.PLAID_SECRET,
env: plaid.environments.sandbox,
});
app.post('/exchange_public_token', async (request, response) => {
try {
const publicToken = request.body.public_token;
// Exchange the client-side public_token for a server access_token
const tokenResponse = await client.exchangePublicToken(publicToken);
// Save the access_token and item_id to a persistent database
const accessToken = tokenResponse.access_token;
const itemId = tokenResponse.item_id;
} catch (e) {
// Display error on client
return response.send({ error: e.message });
}
});

Making API requests

Now that we've gone over the Link flow and token exchange process, we can explore what happens when you press a button in the Quickstart to make an API call. As an example, we'll look at the Quickstart's call to /accounts/get, which retrieves basic information, such as name and balance, about the accounts associated with an Item. The call is fairly straightforward and uses the access_token as a single argument to the Plaid client object.

1
2
3
4
5
6
7
8
9
10
11
12
app.get('/accounts', function (request, response, next) {
client.getAccounts(accessToken, function (error, accountsResponse) {
if (error != null) {
prettyPrintResponse(error);
return response.json({
error: error,
});
}
prettyPrintResponse(accountsResponse);
response.json({ error: null, accounts: accountsResponse });
});
});

Example response data:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
{
"accounts": [
{
"account_id": "A3wenK5EQRfKlnxlBbVXtPw9gyazDWu1EdaZD",
"balances": {
"available": 100,
"current": 110,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "0000",
"name": "Plaid Checking",
"official_name": "Plaid Gold Standard 0% Interest Checking",
"subtype": "checking",
"type": "depository"
},
{
"account_id": "GPnpQdbD35uKdxndAwmbt6aRXryj4AC1yQqmd",
"balances": {
"available": 200,
"current": 210,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "1111",
"name": "Plaid Saving",
"official_name": "Plaid Silver Standard 0.1% Interest Saving",
"subtype": "savings",
"type": "depository"
},
{
"account_id": "nVRK5AmnpzFGv6LvpEoRivjk9p7N16F6wnZrX",
"balances": {
"available": null,
"current": 1000,
"iso_currency_code": "USD",
"limit": null,
"unofficial_currency_code": null
},
"mask": "2222",
"name": "Plaid CD",
"official_name": "Plaid Bronze Standard 0.2% Interest CD",
"subtype": "cd",
"type": "depository"
}
...
],
"item": {
"available_products": [
"assets",
"balance",
"identity",
"investments",
"transactions"
],
"billed_products": ["auth"],
"consent_expiration_time": null,
"error": null,
"institution_id": "ins_12",
"item_id": "gVM8b7wWA5FEVkjVom3ri7oRXGG4mPIgNNrBy",
"webhook": "https://requestb.in"
},
"request_id": "C3IZlexgvNTSukt"
}

Next steps

Congratulations, you have completed the Plaid Quickstart! From here, we invite you to modify the Quickstart code in order to get more practice with the Plaid API. There are a few directions you can go in now:

If you're not sure which Plaid products you want to use, see the Docs Home for an overview.

You can also explore building with a particular product: Auth, Transactions, Balance, Investments, Liabilities, Assets, Identity, and Payment Initiation (UK and Europe).

The Quickstart covered working with web apps. If your Plaid app will be on mobile, see Plaid Link to learn about getting started with mobile client-side setup.