Add Transactions to your app
=============================
#### Learn how to fetch Transactions data for your users
Try out the [Pattern Demo](https://pattern.plaid.com) for a demonstration of a sample app that uses Plaid's Transactions product for the personal financial management use case.
In this guide, we'll start from scratch and walk through how to use Transactions to perform an initial fetch of a user's transaction history. If you are already familiar with using Plaid and are set up to make calls to the Plaid API, you can skip ahead to [Fetching transaction data](https://plaid.com/docs/transactions/add-to-app/index.html.md#fetching-transaction-data) .
For a detailed, step-by-step view, you can also watch our full-length, comprehensive tutorial walkthrough on integrating transactions.
[Watch video](https://www.youtube.com/watch?v=Pin0-ceDKcI)
#### Get Plaid API keys and complete application and company profile
If you don't already have one, you'll need to [create a Plaid developer account](https://dashboard.plaid.com/signup) . After creating your account, you can find your [API keys](https://dashboard.plaid.com/developers/keys) under the Developers menu on the Plaid Dashboard.
You will also need to complete your [application profile](https://dashboard.plaid.com/settings/company/app-branding) and [company profile](https://dashboard.plaid.com/settings/company/profile) on the Dashboard. The information in your profile will be shared with users of your application when they manage their connection on the [Plaid Portal](https://my.plaid.com) . Your application profile and company profile must be completed before connecting to certain institutions in Production.
#### Install and initialize Plaid libraries
You can use our official server-side client libraries to connect to the Plaid API from your application:
```node
// Install via npm
npm install --save plaid
```
```bash
## Not applicable with curl calls
```
```ruby
# Available as a gem
gem install plaid
```
```java
/*
For Gradle, add the following dependency to your build.gradle and replace {VERSION} with the version number you want to use from
- https://github.com/plaid/plaid-java/releases/latest
*/
implementation "com.plaid:plaid-java:{VERSION}"
/*
For Maven, add the following dependency to your POM and replace {VERSION} with the version number you want to use from
- https://github.com/plaid/plaid-java/releases/latest
*/
com.plaid
plaid-java
{VERSION}
```
```python
# Install through pip, only supports Python 3
pip install --upgrade plaid-python
```
```go
go get github.com/plaid/plaid-go
```
After you've installed Plaid's client libraries, you can initialize them by passing in your `client_id`, `secret`, and the environment you wish to connect to (Sandbox or Production). This will make sure the client libraries pass along your `client_id` and `secret` with each request, and you won't need to explicitly include them in any other calls.
```node
// Using Express
const express = require('express');
const app = express();
app.use(express.json());
const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
const configuration = new Configuration({
basePath: PlaidEnvironments.sandbox,
baseOptions: {
headers: {
'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
'PLAID-SECRET': process.env.PLAID_SECRET,
},
},
});
const client = new PlaidApi(configuration);
```
```bash
## Not applicable with curl calls
```
```ruby
require 'sinatra'
require 'plaid'
set :port, ENV['APP_PORT'] || 8000
configuration = Plaid::Configuration.new
configuration.server_index = Plaid::Configuration::Environment[ENV['PLAID_ENV'] || 'sandbox']
configuration.api_key['PLAID-CLIENT-ID'] = ENV['PLAID_CLIENT_ID']
configuration.api_key['PLAID-SECRET'] = ENV['PLAID_SECRET']
api_client = Plaid::ApiClient.new(
configuration
)
client = Plaid::PlaidApi.new(api_client)
```
```java
import java.net.*;
import java.io.*;
import retrofit2.Response;
import java.util.Arrays;
import com.sun.net.httpserver.*;
import com.plaid.client.ApiClient;
import com.plaid.client.request.PlaidApi;
public class PlaidExample {
private static final String CLIENT_ID = System.getenv("PLAID_CLIENT_ID");
private static final String SECRET = System.getenv("PLAID_SECRET");
public static void main(String[] args) {
HttpServer server = HttpServer.create(
new InetSocketAddress("localhost", 8000), 0);
server.createContext("/create_link_token", new GetLinkToken());
server.setExecutor(null);
server.start();
}
// Additional server code goes here
}
```
```python
import plaid
from plaid.api import plaid_api
from flask import Flask
from flask import render_template
from flask import request
from flask import jsonify
app = Flask(name)
configuration = plaid.Configuration(
host=plaid.Environment.Sandbox,
api_key={
'clientId': PLAID_CLIENT_ID,
'secret': PLAID_SECRET,
}
)
api_client = plaid.ApiClient(configuration)
client = plaid_api.PlaidApi(api_client)
# Additional server code goes here
if __name__ == "__main__":
app.run(port=8000)
```
```go
import (
"context"
"net/http"
"os"
"github.com/gin-gonic/gin"
"github.com/plaid/plaid-go/v3/plaid"
)
configuration := plaid.NewConfiguration()
configuration.AddDefaultHeader("PLAID-CLIENT-ID", os.Getenv("CLIENT_ID"))
configuration.AddDefaultHeader("PLAID-SECRET", os.Getenv("SECRET"))
configuration.UseEnvironment(plaid.Sandbox)
client := plaid.NewAPIClient(configuration)
func main() {
r := gin.Default()
// Server endpoints would be declared here
// e.g. r.POST("/create_link_token", createLinkToken)
r.POST("/create_link_token", createLinkToken)
err := r.Run(":8000")
if err != nil {
panic("unable to start server")
}
}
```
#### Create an Item with Link
Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid. Note that these instructions cover Link on the web. For instructions on using Link within mobile apps, see the [Link documentation](https://plaid.com/docs/link/index.html.md) .
Using Link, we will create a Plaid _Item_, which is a Plaid term for a login at a financial institution. 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. If you want to customize Link's look and feel, you can do so from the [Dashboard](https://dashboard.plaid.com/link) .
Before initializing Link, you will need to create a new `link_token` on the server side of your application. A `link_token` is a short-lived, one-time use token that is used to authenticate your app with Link. You can create one using the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) endpoint. Then, on the client side of your application, you'll need to initialize Link with the `link_token` that you just created.
The [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) sample code below will create an Item with a maximum of 90 days of transaction history. To request more, set the `transactions.days_requested` parameter in the [/link/token/create](https://plaid.com/docs/api/link/index.html.md#linktokencreate) request.
##### Create a link\_token
```node
app.post('/api/create_link_token', async function (request, response) {
// Get the client_user_id by searching for the current user
const user = await User.find(...);
const clientUserId = user.id;
const linkTokenRequest = {
user: {
// This should correspond to a unique id for the current user.
client_user_id: clientUserId,
},
client_name: 'Plaid Test App',
products: ['transactions'],
language: 'en',
webhook: 'https://webhook.example.com',
redirect_uri: 'https://domainname.com/oauth-page.html',
country_codes: ['US'],
};
try {
const createTokenResponse = await client.linkTokenCreate(linkTokenRequest);
response.json(createTokenResponse.data);
} catch (error) {
// handle error
}
});
```
```bash
curl -X POST https://sandbox.plaid.com/link/token/create \
-H 'Content-Type: application/json' \
-d '{
"client_id": "${PLAID_CLIENT_ID}",
"secret": "${PLAID_SECRET}",
"client_name": "Plaid Test App",
"user": { "client_user_id": "${UNIQUE_USER_ID}" },
"products": ["transactions"],
"country_codes": ["US"],
"language": "en",
"webhook": "https://webhook.example.com",
"redirect_uri": "https://domainname.com/oauth-page.html"
}'
```
```ruby
post '/api/create_link_token' do
# Get the client_user_id by searching for the current user
current_user = User.find(...)
client_user_id = current_user.id
# Create a link_token for the given user
request = Plaid::LinkTokenCreateRequest.new(
{
user: { client_user_id: client_user_id },
client_name: 'Plaid Test App',
products: ['transactions'],
country_codes: ['US'],
language: "en",
redirect_uri: nil_if_empty_envvar('PLAID_REDIRECT_URI'),
webhook: 'https://webhook.example.com'
}
)
response = client.link_token_create(request)
content_type :json
response.to_json
end
```
```java
import com.plaid.client.model.Products;
import com.plaid.client.model.CountryCode;
import com.plaid.client.model.LinkTokenCreateRequest;
import com.plaid.client.model.LinkTokenCreateRequestUser;
import com.plaid.client.model.LinkTokenCreateResponse;
public class PlaidExample {
...
static class GetLinkToken implements HttpHandler {
private static PlaidApi plaidClient;
public void handle(HttpExchange t) throws IOException {
// Create your Plaid client
HashMap apiKeys = new HashMap();
apiKeys.put("clientId", CLIENT_ID);
apiKeys.put("secret", SECRET);
ApiClient apiClient = new ApiClient(apiKeys);
apiClient.setPlaidAdapter(ApiClient.Sandbox);
plaidClient = apiClient.createService(PlaidApi.class);
// Get the clientUserId by searching for the current user
User userFromDB = db.find(...);
String clientUserId = userFromDB.id;
LinkTokenCreateRequestUser user = new LinkTokenCreateRequestUser()
.clientUserId(clientUserId);
// Create a link_token for the given user
LinkTokenCreateRequest request = new LinkTokenCreateRequest()
.user(user)
.clientName("Plaid Test App")
.products(Arrays.asList(Products.fromValue("transactions")))
.countryCodes(Arrays.asList(CountryCode.US))
.language("en")
.redirectUri("https://domainname.com/oauth-page.html")
.webhook("https://webhook.example.com");
Response response = plaidClient
.linkTokenCreate(request)
.execute();
// Send the data to the client
return response.body();
}
}
}
```
```python
from plaid.model.link_token_create_request import LinkTokenCreateRequest
from plaid.model.link_token_create_request_user import LinkTokenCreateRequestUser
from plaid.model.products import Products
from plaid.model.country_code import CountryCode
@app.route("/create_link_token", methods=['POST'])
def create_link_token():
# Get the client_user_id by searching for the current user
user = User.find(...)
client_user_id = user.id
# Create a link_token for the given user
request = LinkTokenCreateRequest(
products=[Products("transactions")],
client_name="Plaid Test App",
country_codes=[CountryCode('US')],
redirect_uri='https://domainname.com/oauth-page.html',
language='en',
webhook='https://webhook.example.com',
user=LinkTokenCreateRequestUser(
client_user_id=client_user_id
)
)
response = client.link_token_create(request)
# Send the data to the client
return jsonify(response.to_dict())
```
```go
func createLinkToken(c *gin.Context) {
ctx := context.Background()
// Get the client_user_id by searching for the current user
user, _ := usermodels.Find(...)
clientUserId := user.ID.String()
// Create a link_token for the given user
request := plaid.NewLinkTokenCreateRequest("Plaid Test App", "en", []plaid.CountryCode{plaid.COUNTRYCODE_US}, *plaid.NewLinkTokenCreateRequestUser(clientUserId))
request.SetWebhook("https://webhook.sample.com")
request.SetRedirectUri("https://domainname.com/oauth-page.html")
request.SetProducts([]plaid.Products{plaid.PRODUCTS_TRANSACTIONS})
resp, _, err := testClient.PlaidApi.LinkTokenCreate(ctx).LinkTokenCreateRequest(*request).Execute()
// Send the data to the client
c.JSON(http.StatusOK, gin.H{
"link_token": resp.GetLinkToken(),
})
}
```
##### Install Link dependency
index.html
```html
Connect a bank
```
##### Configure the client-side Link handler
app.js
```javascript
const linkHandler = Plaid.create({
token: (await $.post('/create_link_token')).link_token,
onSuccess: (public_token, metadata) => {
// Send the public_token to your app server.
$.post('/exchange_public_token', {
public_token: public_token,
});
},
onExit: (err, metadata) => {
// Optionally capture when your user exited the Link flow.
// Storing this information can be helpful for support.
},
onEvent: (eventName, metadata) => {
// Optionally capture Link flow events, streamed through
// this callback as your users connect an Item to Plaid.
},
});
linkHandler.open();
```
#### Get a persistent access token
Next, on the server side, we need to exchange our `public_token` for an `access_token` and `item_id`. The `access_token` will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the [/item/public\_token/exchange](https://plaid.com/docs/api/items/index.html.md#itempublic_tokenexchange) endpoint from our server-side handler. We'll use the client library we configured earlier to make the API call.
Save the `access_token` and `item_id` in a secure datastore, as they're used to access Item data and identify webhooks, respectively. The `access_token` will remain valid unless you actively choose to expire it via rotation or remove the corresponding Item via [/item/remove](https://plaid.com/docs/api/items/index.html.md#itemremove) . The `access_token` should be stored securely, and never in client-side code. A `public_token` is a one-time use token with a lifetime of 30 minutes, so there is no need to store it.
```node
app.post('/api/exchange_public_token', async function (
request,
response,
next,
) {
const publicToken = request.body.public_token;
try {
const tokenResponse = await client.itemPublicTokenExchange({
public_token: publicToken,
});
// These values should be saved to a persistent database and
// associated with the currently signed-in user
const accessToken = tokenResponse.data.access_token;
const itemID = tokenResponse.data.item_id;
response.json({ public_token_exchange: 'complete' });
} catch (error) {
// handle error
}
});
```
```bash
curl -X POST https://sandbox.plaid.com/item/public_token/exchange \
-H 'Content-Type: application/json' \
-d '{
"client_id": "${PLAID_CLIENT_ID}",
"secret": "${PLAID_SECRET}",
"public_token": "public-sandbox-12345678-abcd-1234-abcd-1234567890ab"
}'
```
```ruby
access_token = nil
post '/api/exchange_public_token' do
request = Plaid::ItemPublicTokenExchangeRequest.new(
{
public_token: params["public_token"]
}
)
response = client.item_public_token_exchange(request)
# These values should be saved to a persistent database and
# associated with the currently signed-in user
access_token = response.access_token
item_id = response.item_id
content_type :json
{public_token_exchange: "complete"}.to_json
end
```
```java
import com.plaid.client.model.ItemPublicTokenExchangeRequest;
import com.plaid.client.model.ItemPublicTokenExchangeResponse;
public class PlaidExample {
...
static class GetAccessToken implements HttpHandler {
private static PlaidClient plaidClient;
private String publicToken;
private String accessToken;
private String itemId;
public void handle(HttpExchange t) throws IOException {
// Simplified pseudo-code for obtaining public_token
InputStream is = t.getRequestBody();
publicToken = is.publicToken();
// Create your Plaid client
HashMap apiKeys = new HashMap();
apiKeys.put("clientId", CLIENT_ID);
apiKeys.put("secret", SECRET);
apiKeys.put("plaidVersion", "2020-09-14");
apiClient = new ApiClient(apiKeys);
apiClient.setPlaidAdapter(ApiClient.Sandbox);
plaidClient = apiClient.createService(PlaidApi.class);
// Exchange public_token for an access_token
ItemPublicTokenExchangeRequest request = new ItemPublicTokenExchangeRequest()
.publicToken(publicToken);
Response response = plaidClient
.itemPublicTokenExchange(request)
.execute();
// These values should be saved to a persistent database and
// associated with the currently signed-in user
accessToken = response.body().getAccessToken();
itemId = response.body().getItemId();
String message = "{\"public_token_exchange\": \"complete\"}";
return Response
.status(Response.Status.OK)
.entity(message)
.type(MediaType.APPLICATION_JSON)
}
}
}
```
```python
access_token = None
item_id = None
@app.route('/exchange_public_token', methods=['POST'])
def exchange_public_token():
global access_token
public_token = request.form['public_token']
request = ItemPublicTokenExchangeRequest(
public_token=public_token
)
response = client.item_public_token_exchange(request)
# These values should be saved to a persistent database and
# associated with the currently signed-in user
access_token = response['access_token']
item_id = response['item_id']
return jsonify({'public_token_exchange': 'complete'})
```
```go
func getAccessToken(c *gin.Context) {
ctx := context.Background()
publicToken := c.PostForm("public_token")
// exchange the public_token for an access_token
exchangePublicTokenReq := plaid.NewItemPublicTokenExchangeRequest(publicToken)
exchangePublicTokenResp, _, err := client.PlaidApi.ItemPublicTokenExchange(ctx).ItemPublicTokenExchangeRequest(
*exchangePublicTokenReq,
).Execute()
// These values should be saved to a persistent database and
// associated with the currently signed-in user
accessToken := exchangePublicTokenResp.GetAccessToken()
itemID := exchangePublicTokenResp.GetItemId()
c.JSON(http.StatusOK, gin.H{"public_token_exchange": "complete"})
}
```
#### Fetching transaction data
Now that the authentication step is out of the way, we can begin using authenticated endpoints from the Plaid API and fetch transaction data using the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint.
The [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) endpoint is used to both initialize your view of transactions data, and keep you current with any changes that have occurred. When you first call it on an Item with no `cursor` parameter, transactions data available at that time is returned. If more updates are available than requested with the `count` parameter (maximum of 500), `has_more` will be set to `true`, indicating the endpoint should be called again, using the `next_cursor` from the previous response in the `cursor` field of the next request, to receive another page of data. After successfully pulling all currently available pages, you can store the cursor for later requests, allowing Plaid to send you new updates from when you last queried the endpoint.
Note that if you encounter an error during pagination, it's important to restart the pagination loop from the beginning. For more details, see the documentation for [TRANSACTIONS\_SYNC\_MUTATION\_DURING\_PAGINATION](https://plaid.com/docs/errors/transactions/index.html.md#transactions_sync_mutation_during_pagination) . For sample code for handling the error, see the [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) API reference.
Typically, the first 30 days of transaction history is available to be fetched almost immediately, but full transaction history may take a minute or more to become available. If you get an empty response when calling [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) shortly after linking an Item, it's likely that the first 30 days of transaction history has not yet been pulled. You will need to call the endpoint when the data is pulled. Similarly, if you only get the first 30 days of transaction history, you will need to wait until it is complete, and call the endpoint again.
To be notified whenever additional data becomes available, see [Transaction webhooks](https://plaid.com/docs/transactions/webhooks/index.html.md) .
```node
// Provide a cursor from your database if you've previously
// received one for the Item. Leave null if this is your
// first sync call for this Item. The first request will
// return a cursor.
let cursor = database.getLatestCursorOrNull(itemId);
// New transaction updates since "cursor"
let added: Array = [];
let modified: Array = [];
// Removed transaction ids
let removed: Array = [];
let hasMore = true;
// Iterate through each page of new transaction updates for item
while (hasMore) {
const request: TransactionsSyncRequest = {
access_token: accessToken,
cursor: cursor,
};
const response = await client.transactionsSync(request);
const data = response.data;
// Add this page of results
added = added.concat(data.added);
modified = modified.concat(data.modified);
removed = removed.concat(data.removed);
hasMore = data.has_more;
// Update cursor to the next cursor
cursor = data.next_cursor;
}
// Persist cursor and updated data
database.applyUpdates(itemId, added, modified, removed, cursor);
```
```bash
curl -X POST https://sandbox.plaid.com/transactions/sync \
-H 'Content-Type: application/json' \
-d '{
"client_id": "${PLAID_CLIENT_ID}",
"secret": "${PLAID_SECRET}",
"access_token": String,
"cursor": String,
"count": 250
}'
```
```ruby
# Provide a cursor from your database if you've previously
# received one for the Item. Leave null if this is your
# first sync call for this item. The first request will
# return a cursor.
cursor = database.get_latest_cursor_or_none(item_id)
# New transaction updates since "cursor"
added = []
modified = []
removed = [] # Removed transaction ids
has_more = true
# Iterate through each page of new transaction updates for item
while has_more
request = Plaid::TransactionsSyncRequest.new(
{
access_token: access_token,
cursor: cursor
}
)
response = client.transactions_sync(request)
# Add this page of results
added += response.added
modified += response.modified
removed += response.removed
has_more = response.has_more
# Update cursor to the next cursor
cursor = response.next_cursor
end
# Persist cursor and updated data
database.apply_updates(item_id, added, modified, removed, cursor)
```
```java
// Provide a cursor from your database if you've previously
// received one for the item leave null if this is your
// first sync call for this item. The first request will
// return a cursor.
String cursor = database.getLatestCursorOrNull(itemId);
// New transaction updates since "cursor"
List added = new ArrayList();
List modified = new ArrayList();
List removed = new ArrayList();
boolean hasMore = true;
// Iterate through each page of new transaction updates for item
while (hasMore) {
TransactionsSyncRequest request = new TransactionsSyncRequest()
.accessToken(accessToken)
.cursor(cursor);
response = plaidClient.transactionsSync(request).execute();
// Add this page of results
added.addAll(response.getAdded());
modified.addAll(response.getModified());
removed.addAll(response.getRemoved());
hasMore = response.getHasMore();
// Update cursor to the next cursor
cursor = response.getNextCursor();
}
// Persist cursor and updated data
database.applyUpdates(itemId, added, modified, removed, cursor);
```
```python
# Provide a cursor from your database if you've previously
# received one for the Item. Leave null if this is your
# first sync call for this Item. The first request will
# return a cursor.
cursor = database.get_latest_cursor_or_none(item_id)
# New transaction updates since "cursor"
added = []
modified = []
removed = [] # Removed transaction ids
has_more = True
# Iterate through each page of new transaction updates for item
while has_more:
request = TransactionsSyncRequest(
access_token=access_token,
cursor=cursor,
)
response = plaid_client.transactions_sync(request)
# Add this page of results
added.extend(response['added'])
modified.extend(response['modified'])
removed.extend(response['removed'])
has_more = response['has_more']
# Update cursor to the next cursor
cursor = response['next_cursor']
# Persist cursor and updated data
database.apply_updates(item_id, added, modified, removed, cursor)
```
```go
// Provide a cursor from your database if you've previously
// received one for the Item. Leave null if this is your
// first sync call for this Item. The first request will
// return a cursor.
cursor := database.getLatestCursorOrNil(itemId)
// New transaction updates since "cursor"
var added []Transaction
var modified []Transaction
var removed []RemovedTransaction // Removed transaction ids
hasMore := true
// Iterate through each page of new transaction updates for item
for hasMore {
request := plaid.NewTransactionsSyncRequest(accessToken)
if cursor != nil {
request.SetCursor(*cursor)
}
resp, _, err := client.PlaidApi.TransactionsSync(
ctx,
).TransactionsSyncRequest(*request).Execute()
// Add this page of results
added = append(added, resp.GetAdded()...)
modified = append(modified, resp.GetModified()...)
removed = append(removed, resp.GetRemoved()...)
hasMore = resp.GetHasMore()
// Update cursor to the next cursor
cursor = &resp.GetNextCursor()
}
// Persist cursor and updated data
database.applyUpdates(itemId, added, modified, removed, cursor)
```
#### Updating transaction data
After your initial [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) request, you may want your application to be notified when any transactions are added, removed, or modified in order to immediately fetch them from [/transactions/sync](https://plaid.com/docs/api/products/transactions/index.html.md#transactionssync) . To learn how, see [Transaction Webhooks](https://plaid.com/docs/transactions/webhooks/index.html.md) .
#### Example code in Plaid Pattern
For a real-life example of an app that incorporates transactions, see the Node-based [Plaid Pattern](https://github.com/plaid/pattern) sample app. Pattern is a sample financial management app that fetches transactions data upon receipt of transactions webhooks. Transactions code in Plaid Pattern can be found in [handleTransactionsWebhook.js](https://github.com/plaid/pattern/blob/master/server/webhookHandlers/handleTransactionsWebhook.js) .
#### Fetching by date
If you want to fetch transactions data by date range, you can use the [/transactions/get](https://plaid.com/docs/api/products/transactions/index.html.md#transactionsget) endpoint.