forked from fintechsandbox/project-sandcastle
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Plaid Overview and Tips- Cache
66 lines (40 loc) · 5.02 KB
/
Plaid Overview and Tips- Cache
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
# Plaid
## Overview
[Plaid](https://www.plaid.com) offers 3 consumer banking data services:
- Auth: validate a user's bank username & password
- Balance: guaranteed up to date account balances for a user
- Connect: transaction history for a user's bank accounts, as well as balances for those accounts (but Plaid does not guarantee these balances are up to date)
The team at Cache uses Connect, which is what we'll detail here.
## Setup
### Create an account
All API calls to Plaid require a `client_id` & `secret`, which are generated for your business when you sign up with Plaid.
### Routes, access_tokens
Plaid has excellent [documentation](https:/www.plaid.com/docs). Here is a brief overview of the 5 things one can do with Connect:
- Add a user (connectAdd)
- Step a user through multi-factor authentication (connectStep, follows after conectAdd)
- Get a user's account & transaction data (connectGet)
- Patch a user (connectPatch, required if a user's credentials or MFA have changed with the institution, and the user must be reintegrated)
- Delete a user (connectDelete)
Add/Step are for signup: integration a user's bank account. ConnectGet is for ongoing use, whenever new transaction data is available for the user. Patch/Delete are maintenance.
#### Access_tokens
Plaid's definition of a _user_ is an `access_token`: what you get back when a user successfully connects their bank. In other words, a user will connect their bank, and Plaid will generate a single `access_token` for this user's bank account. This means: 1 `access_token` represents the banking data associated with a user's bank username and password. In a typical Bank of America case, this means 1 `access_token` is associated with: a checking, savings, & credit card accounts for the user. Whatever they would see by logging into their instution's website using those credentials.
**IMPORTANT TIP**: Nothing prevents a user from signing up with their same bank credentials twice. **Plaid will generate a new** `access_token` **for each instance**, and as far as a startup's interface with Plaid is concerned, it is as if the 2 `access_tokens` are completely unrelated.
However, this comes with a caveat: it appears as if Plaid stores transaction history data on their own servers, so that if one `access_token` instance of a user's bank has been integrated many years before (for instance, if that user signed up with Mint.com, and 5 years of data have been stored), and a new `access_token` is generated for a new instance with a different service (e.g. the user now signs up with cache.ai), it appears as if the new `access_token` is fed the same 5 years of data from Plaid, rather than the 1 month - 2 years typical transaction history for a newly integrated bank.
In other words: Plaid keeps track of a bank account's data, and moving forward, Plaid serves that same, Plaid-stored data to all new `access_token` instances of a user's bank account. But as far as the Plaid API appears, these `access_tokens` are completely unrelated, and there is no trivial way to identify them as representing the same user bank account & data set.
### Server integration
Cache uses Nodejs for the back end. Plaid has an easy to integrate Node library [plaid-node](https://github.com/plaid/plaid-node), which can be installed using [npm](http://www.npmjs.com): `npm install plaid`. Connecting to the routes above is simple, with the 5 commands, as listed in the github README:
- plaidClient.addConnectUser(...)
- ...stepConnectUser(...)
- ...getConnectUser(...)
- ...patchConnectUser(...)
- ...deleteConnectUser(...)
Be mindful of the arguments listed in the README. If callbacks appear to be failing, it may be because Plaid's stated arguments in the README don't match what is currently implemented in their API.
#### Webhooks
When integrating a new user & receiving an `access_token` for that user, it's essential to provide Plaid with a webhook address: some route on your servers that Plaid can call to let you know about new data for a user, or any other issues (a user may need patching, etc.)
#### Suggested integration setup: `login_only : true`, and then listen for transaction webhooks
By default, during user authentication (connectAdd, connectStep), Plaid sends some transaction history back along with the _authentication successful_ message. WE suggest against this, as we frequently experience server timeouts while Plaid is pulling & cleaning data from the user's institution. One can turn this off by using the connectAdd option `{ login_only: true }`.
In the `login_only : true` case, Plaid will not send back any transaction history in the `success` callback, but instead will send pings to the webhook url you provided. Their initial pings will be for:
- Initial transaction history pulled (called within a minute, uses `code 0`)
- Historical transaction history pulled (called within 5 minutes, uses `code 1`)
## Sample data
Plaid's API is clean & consistent, & so is their data, all provided as JSON. Their [docs](https://www.plaid.com/docs) give excellent examples of the data structures returned from their routes.