April 22, 2015
Getting Started with Plaid Transactions
Zach
Updated on November 21, 2018
This quickstart guide will get you up and running with Plaid Transactions (previously known as Connect), which allows you to retrieve user-authorized transaction and account data from thousands of financial institutions in the United States. For additional information on Transactions and other Plaid endpoints, check out our full documentation here.
Access
To get started with Plaid, create an account on our website here. This will give you access to a set of API keys with which you can add up to 100 live users and utilize all of our products in the development environment. To complete your integration and launch into production, simply reach out to our Sales team—we’re happy to help.
Basic user flow
There are three primary steps to connecting an end user on Plaid Transactions:
Initial submit of user information
Complete Multi-Factor Authentication (MFA) responses as necessary
Retrieve available data
Each of these steps will be covered in depth below. Additionally, you’ll need the following information:
API keys: client_id and secret
Banking credentials: username, password, PIN (if required)
Plaid institution code: amex, bofa, chase, etc.
MFA answers: questions or codes issued by the financial institution
Optional parameters: webhook address, etc.
Another key piece of information that will be returned after the initial submission of user information is the access token. It is crucial that you store this access token as it is required for all subsequent calls to the API for that particular end user.
Initial submission of user info
To submit the initial user info, send a POST request to https://tartan.plaid.com/connect
with the following parameters:
An important consideration at this point is whether or not you want to utilize Plaid’s webhook functionality. Though not required, we highly recommended using webhooks, which will notify you whenever new transaction or account information is available. Webhooks are also used to communicate issues with an end user’s account, such as the need to update credentials or unlock an account.
To enable webhooks, you’ll need to include two additional pieces of information in the options parameter of the request body:
The ‘login_only’ parameter determines whether or not data will be returned directly in the body of the response. When set to false (default), account and transaction information will be included in the body of the response. When true, you will be notified when data is available via webhook. More information on webhooks can be found in our documentation here.
Here’s a sample curl request using Plaid’s sandbox credentials and a fake webhook address:
Depending on the financial institution and whether or not you included a webhook address, there are a few potential outcomes from this call:
Multi-Factor Authentication
Many of the financial institutions that we support require Multi-Factor Authentication (MFA) that can come in a number of forms. The two most common are Question and Code-Based MFA. To complete the MFA process (any type), submit a POST request to https://tartan.plaid.com/connect/step
with the following parameters:
Here’s another sample curl request using Plaid’s sandbox credentials:
If multiple questions are required (usaa, bofa, etc.) continue to send requests to https://tartan.plaid.com/connect/step
until a 200 success response is received.
Data retrieval
Once a user has been successfully added to Plaid, you can retrieve account and transaction data as often as you’d like. Keep in mind that this will not initiate a call to the bank for new data, but rather retrieve existing information in our systems. Plaid will continue to update data from the banks throughout the day in the background.
If you utilized Plaid’s webhook functionality described earlier, you will receive a notification each time new account data exists for a particular access token.
To retrieve account and transaction information for a particular user, send a GET request to https://tartan.plaid.com/connect
with the following parameters:
Sample request using Plaid’s sandbox credentials:
By default, Plaid will return all available transactions associated with an access token. To retrieve data from specific dates or by transaction id, you can use one of the many optional parameters explained further in our documentation here.
Additional resources
Once you’ve gone through this guide, we recommend that you visit our documentation page here to explore the many other features and capabilities of the Plaid API.
If you have additional questions or run into any issues, don’t hesitate to visit our Help Center or open a ticket in your Plaid Dashboard for more pressing matters.