SHARE

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:

  1. Initial submit of user information

  2. Complete Multi-Factor Authentication (MFA) responses as necessary

  3. 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:

client_id
secret
username
password
type

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:

login_only: true
webhook: your webhook address

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:

1 curl -X POST https://tartan.plaid.com/connect \
2 -d client_id=test_id \
3 -d secret=test_secret \
4 -d username=plaid_test \
5 -d password=plaid_good \
6 -d type=wells \
7 -d options='{
8 "webhook":"http://requestb.in/",
9 "login_only":true }'
10

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:

client_id
secret
access_token
mfa

Here’s another sample curl request using Plaid’s sandbox credentials:

1curl -X POST https://tartan.plaid.com/connect/step \
2 -d client_id=test_id \
3 -d secret=test_secret \
4 -d mfa=tomato \
5 -d access_token=test_us
6

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:

client_id
secret
access_token

Sample request using Plaid’s sandbox credentials:

1curl -X POST https://tartan.plaid.com/connect/get \
2 -d client_id=test_id \
3 -d secret=test_secret \
4 -d access_token=test_wells
5

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.