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.
Incremental aggregation request
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.
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.
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.
205 Reset Contentand provides an AuthorizationResponse as the body, 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
New transactions ready
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.
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.
Instant account updates
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
Periodic account updates
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.