Aggregation Flow

The aggregation flow will form the overwhelming majority of Plaid’s requests to a partner. Plaid uses periodic, incremental requests to stay synchronized with the institution’s view of an account. The partner can also prompt Plaid to delete or cycle a token whenever it chooses.

• Aggregation API Reference

For a given user, Plaid achieves aggregation by requesting, periodically or in response to notifications:

• A current view of accounts under the control of the user.
• Identities related to those accounts.
• Recent transaction history.

1Plaid requests a current view of the user's account information. The request will be made from a small pool of static IP addresses controlled by Plaid, and will bear the access token.

2The partner validates the access token, then generates and returns a current summary of the user's resources.

3Plaid requests a current view of the user's transactions, with a time window of 7 days.

4The partner returns the full list of transactions, across all accounts, satifsying request parameters. If the full set of transactions exceeds these parameters, i.e. the total number of transactions exceeds limit, then Plaid will return to (3) and modify request parameters accordingly, until all transactions have been reviewed.

Partners are able to unilaterally revoke an access token without first notifying Plaid, although notification is still desirable in the interest of a positive user experience. If any request made by Plaid receives an HTTP status 401 Unauthorized, the token will be marked as revoked.

The partner should revoke access tokens when users change their passwords, and should log access attempts bearing revoked tokens.

1Plaid makes any request in the aggregation flow

2While validating the request the Partner discovers that the token should be revoked, and returns HTTP status 401 Unauthorized.

3Plaid marks the Item as invalid, deletes the token, and notifies all connected Plaid apps that the item cannot be served.

4After the token is revoked, the Partner should monitor future API requests to ensure that the token is never observed in subsequent requests. If the token is seen subsequently, that may indicate that a previously secure system has been breached.

Partners are able to expire tokens and communicate replacement tokens to Plaid. Token refresh enables partners to separate the duration of an authorization from the lifetime of a single access token, ensuring that it can expire access tokens without disrupting user experience by requiring them to reauthorize to Plaid.

1Plaid makes any request in the aggregation flow.

2While validating the request the Partner discovers that the token should be replaced, and returns HTTP status 205 Reset Content and provides an AuthorizationResponse in the X-PLAID-AUTH-TOKEN header, where auth_token is the replacement token. The expired token should be preserved, and requests bearing it should be logged, as these may indicate security breach

3Plaid deletes the previous token and reissues the request using the new token.

4The previous token is now revoked, and the Partner should monitor future API requests to ensure that it is never observed in subsequent requests. If the previous token is seen subsequently, it may indicate a security breach.

Partners can notify Plaid when multiple users have transactions ready to pick up. This allows partners and Plaid to collaboratively schedule aggregation and reduce unnecessary transactions fetches. Plaid will still periodically aggregate the accounts of every connected user, but these requests can be configured to be issued during periods of low demand.

1Multiple users generates spending activity.

2The partner sends a NewTransactionsNotification to Plaid, indicating that multiple users have new transactions which are read to retrieve. The partner only needs to send transactions which are new since the last time Plaid was notified. It is not necessary to track whether and when Plaid last requested transactions for a given user.

3Plaid receives and acknowledge the notifications.

4Plaid will update its aggregation schedule to prioritize users who have new transactions waiting.

5Plaid issues an incremental aggregation request.

Financial institution backends are varied, and implementation teams will find different strategies for serving transaction updates easier or more difficult to pursue, based on their own internal capabilities. We describe below a few styles of processing that may serve as starting points for a partner’s implementation.

When serving transactions updates, the partner backend processes new pending and posted transactions, checks if those transactions belong to Plaid-connected accounts (e.g. checking if account has an access token associated), and if so, POSTs a NewTransactionsNotification to /items/transactions/notify

1User creates transactions, which is passed on to FI backend.

2Financial institution backend processes transaction and checks if transactions belongs to a PX bank account before forwarding transaction to Plaid

3Plaid uses information found in RTT notification payload to retrieve new transactions

This implementation style makes use of workers processing a job queue. A business process observes new transaction activity on a Plaid-connected account, looks up the associated Plaid Item ID, and places the ID into a queue. The queue is then drained periodically, e.g. every 15 minutes, and NewTransactionsNotifications are sent for the accounts in the queue.

1User creates transactions which is passed on to financial institution backend

2Financial institution backend processes transaction and forward to financial institution RTT service

3RTT service checks transaction to see if it belongs to a Plaid Exchange account before adding to queue

4RTT service periodically checks queue for transactions older than 5min

5RTT service forwards transactions older than 5min to Plaid RTT endpoint

6Plaid uses information found in RTT notification payload to retrieve new transactions

• New Transactions Ready (POST /items/transactions/notify) API Method