This is a sample Account Funding application demonstrating an end-to-end Plaid integration, focused on using the auth (or working with a Plaid partner using processor tokens), identity and balance endpoints to safely transfer funds.
For an interactive tutorial showing how to make this app, see Plaid Account Funding tutorial.
The full Plaid collection of sample apps includes:
Plaid Pattern Account Funding App - (you are here) Demonstrates the Plaid Auth, Balance, and Identity APIs
Plaid Pattern Personal Finance Manager - Demonstrates the Plaid Transactions API
Plaid Transfer Quickstart app - Demonstrates the Transfer API (up to date)
Plaid Pattern Transfer App (deprecated) - Demonstrates the Transfer API (this sample app is deprecated, use the Transfer Quickstart app instead)
Plaid sample apps are provided for illustrative purposes and are not meant to be run as production applications.
- Docker Version 2.0.0.3 (31259) or higher, installed, running, and signed in. If you're on Windows, check out this link to get set up in WSL.
- Plaid API keys - sign up for a free Sandbox account if you don't already have one
- An ngrok authtoken. If you don't already have an ngrok account, you can sign up for free.
Note: We recommend running these commands in a unix terminal. Windows users can use a WSL terminal to access libraries like make.
-
Clone the repo.
git clone https://github.com/plaid/pattern-account-funding.git cd pattern-account-funding -
Create the
.envfile.cp .env.template .env
-
Update the
.envfile with your Plaid API keys and OAuth redirect uri (in sandbox this is 'http://localhost:3002/oauth-link'). -
Update the
ngrok.ymlfile in the ngrok folder with your ngrok authtoken. -
(Optional, only required if using an OAuth redirect URI) You will also need to configure an allowed redirect URI for your client ID through the Plaid developer dashboard.
-
Start the services. The first run may take a few minutes as Docker images are pulled/built for the first time.
make start
-
Open http://localhost:3002 in a web browser.
-
View the logs
make logs
-
When you're finished, stop the services.
make stop
All available commands can be seen by calling make help.
As a modern full-stack application, Pattern consists of multiple services handling different segments of the stack:
clientruns a React-based single-page web frontendserverruns an application back-end server using NodeJS and Expressdatabaseruns a PostgreSQL databasengrokexposes a ngrok tunnel from your local machine to the Internet to receive webhooks
We use Docker Compose to orchestrate these services. As such, each individual service has its own Dockerfile, which Docker Compose reads when bringing up the services.
More information about the individual services is given below.
The Pattern web client is written in JavaScript using React. It presents a basic Link workflow to the user, including an implementation of OAuth as well as a demonstration of Link update mode. The sample app allows you to choose to use identification mode, where an enduser must input the name and email associated with their financial institution. The app runs on port 3002 by default, although you can modify this in docker-compose.yml.
Aside from websocket listeners (see below), all HTTP calls to the Pattern server are defined in src/services/api.js.
This app uses the classic mode of rendering Link. If you are building a Pay-by-bank app rather than an account funding app, the Embedded Institution Search feature is strongly recommended instead, to increase uptake of pay-by-bank. See the Plaid Transfer Quickstart for an example of this in action.
The Pattern server is configured to send a message over a websocket whenever it receives a webhook from Plaid. On the client side have websocket listeners defined in src/components/Sockets.jsx that wait for these messages and update data in real time accordingly.
The PENDING_DISCONNECT, PENDING_EXPIRATION, and ITEM_LOGIN_REQUIRED Item webhooks demonstrated in this sample app in the items webhook handler.
A view of all users is provided to developers on http://localhost:3002/admin. Developers have the ability to remove a user here.
The application server is written in JavaScript using Node.js and Express. It interacts with the Plaid API via the Plaid Node SDK, and with the database using node-postgres. While we've used Node for the reference implementation, the concepts shown here will apply no matter what language your backend is written in.
Plaid does not have a user data object for tying multiple items together, so it is up to application developers to define that relationship. For an example of this, see the root items route (used to store new items) and the users routes.
Plaid uses webhooks to notify you whenever an item enters an error state. If a user needs to update their login information at their financial institution, an item will display an ITEM_LOGIN_REQUIRED error. This sample app demonstrates the use of the sandboxItemResetLogin endpoint to test this webhook. For an example of this, see the items webhook handler.
For webhooks to work, the server must be publicly accessible on the internet. For development purposes, this application uses ngrok to accomplish that. Therefore, if the server is re-started, any items created in this sample app previous to the current session will have a different webhook address attached to it. As a result, webhooks are only valid during the session in which an item is created; for previously created items no webhook will be received from the call to sandboxItemResetLogin.
The linkTokenCreate call includes a redirect_uri parameter, which the server applications reads from the PLAID_SANDBOX_REDIRECT_URI entry in the .env file (This value should be http://localhost:3002/oauth-link). This is the page that the user will be redirected to upon completion of the OAuth flow at their OAuth institution. When running in Production, you will need to use an https:// redirect URI, but a http:// URI will work for Sandbox.
You will also need to add http://localhost:3002/oauth-link as an allowed redirect URI for your client ID in API section of the Plaid developer dashboard.
To test the OAuth flow, choose 'Playtypus OAuth Bank' from the list of financial instutions in Plaid Link.
This sample app can also demonstrate the creation of a processor token for use with Plaid partners. While still initializing Link with the Auth product, instead of of using Plaid Auth endpoints, an example of the creation of a processor token and integration with a plaid partner is included in the root items route.
This sample app uses Dwolla sandbox to demonstrate the transferring of funds with a Plaid partner. Dwolla is just one of the many payment providers who have partnered with Plaid. To test out the Dwolla sandbox flow, follow these steps:
-
Go to your Plaid developer dashboard Integrations page. Scroll down to Dwolla and click on the "enable" button.
-
Head to the Dwolla site and create a sandbox account by clicking the
Get API Keysbutton and following the sign up instructions. -
After logging in, create a temporary access token by clicking on the "Create Token" button on Dwolla's dashboard Applications Page. Copy this token and add it to the .env file as
DWOLLA_ACCESS_TOKEN. This is a temporary access token issued by Dwolla which is good for one hour. -
Go to your Dwolla Master Account Funding Source on the dashboard and obtain your id from your Superhero Savings Bank. This is the very last number in the smaller white box on the bottom left corner of the page. Enter this id in the .env file as the
DWOLLA_MASTER_ACCOUNT_ID. -
Finally, make sure that
IS_PROCESSORis set totruein the .env file.
This sample app demonstrates how to get the available balance in order to verify and transfer funds. However, it does not actually conduct a transfer of funds because it uses Dwolla sandbox. The balance in the linked account (whether in sandbox or production) will not decrement when a transfer is made in this app.
The node debugging port (9229) is exposed locally on port 9229.
If you are using Visual Studio Code as your editor, you can use the Docker: Attach to Server launch configuration to interactively debug the server while it's running. See the VS Code docs for more information.
The database is a PostgreSQL instance running inside a Docker container.
Port 5432 is exposed to the Docker host, so you can connect to the DB using the tool of your choice. Username and password can be found in docker-compose.yml.
API and Link Identifiers are crucial for maintaining a scalable and stable integration. Occasionally, an Institution error may occur due to a bank issue, or a live product pull may fail on request. To resolve these types of issues, Plaid Identifiers are required to open a Support ticket in the Dashboard.
access_tokens and item_ids are the core identifiers that map end-users to their financial institutions.
As such, we are storing them in the database associated with our application users.
These identifiers should never be exposed client-side.
Plaid returns a unique request_id in all server-side responses and Link callbacks.
A link_session_id is also returned in Link callbacks.
These values can be used for identifying the specific network request or Link session for a user, and associating that request or session with other events in your application.
We store these identifiers in database tables used for logging Plaid API requests, as they can be useful for troubleshooting.
For more information, see the docs page on storing Plaid API identifiers.
The *.sql scripts in the init directory are used to initialize the database if the data directory is empty (i.e. on first run, after manually clearing the db by running make clear-db, or after modifying the scripts in the init directory).
See the create.sql initialization script to see some brief notes for and the schemas of the tables used in this application. While most of them are fairly self-explanitory, we've added some additional notes for some of the tables below.
This table stores responses from the Plaid API for client requests to the Plaid Link client.
User flows that this table captures (based on the client implementation, which hooks into the onExit and onSuccess Link callbacks):
- User opens Link, closes without trying to connect an account.
This will have type
exitbut no request_id, error_type, or error_code. - User tries to connect an account, fails, and closes link.
This will have type
exitand will have a request_id, error_type, and error_code. - User successfully connects an account.
This will have type
successbut no request_id, error_type, or error_code.
This table stores responses from the Plaid API for server requests to the Plaid client. The server stores the responses for all of the requests it makes to the Plaid API. Where applicable, it also maps the response to an item and user. If the request returned an error, the error_type and error_code columns will be populated.
This demo includes ngrok, a utility that creates a secure tunnel between your local machine and the outside world. We're using it here to expose the local webhooks endpoint to the internet.
Browse to localhost:4040 to see the ngrok dashboard. This will show any traffic that gets routed through the ngrok URL.
Do NOT use ngrok in production! It's only included here as a convenience for local development and is not meant to be a production-quality solution.
Don’t want to use ngrok? As long as you serve the app with an endpoint that is publicly exposed, all the Plaid webhooks will work.
ngrok's free account has a session limit of 8 hours. To fully test out some of the transaction webhook workflows, you will need to get a more persistent endpoint as noted above when using the production environment.
This image is a copy of the Docker Hub image wernight/ngrok. We've copied it here to allow us to more closely version it and to make changes as needed.
- https://hub.docker.com/r/wernight/ngrok/dockerfile
- https://github.com/wernight/docker-ngrok/tree/202c4692cbf1bbfd5059b6ac56bece42e90bfb82
- For an overview of the Plaid platform and products, refer to this Quickstart guide.
- Check out this high-level introduction to Plaid Link.
- Find comprehensive information on Plaid API endpoints in the API documentation.
- Questions? Please head to the Help Center or open a Support ticket.
Plaid Pattern is a demo app that is intended to be used only for the purpose of demonstrating how you can integrate with Plaid. You are solely responsible for ensuring the correctness, legality, security, privacy, and compliance of your own app and Plaid integration. The Pattern code is licensed under the MIT License and is provided as-is and without warranty of any kind. Plaid Pattern is provided for demonstration purposes only and is not intended for use in production environments.