
Plaid enables applications to connect with users' bank, credit card, loan, and investment accounts to pull in account details such as balances and transactions. The same connection can also be used to verify ownership of an account (IAV).
Setup
To get started, you'll first need to sign up for Plaid, if you aren't yet a user. Once on the Plaid developer portal, follow the instructions below:
We currently support Plaid Development
and Production
environments, not Sandbox
(dummy accounts)
- Copy the
client_id
and paste it into the Hydrogen Admin Credentials screen as the "Username/Client Id" for Plaid.
- Copy the
secret
and paste it into the Hydrogen Admin Credentials screen as the "Password/Client Secret" for Plaid
- Choose Plaid as the vendor for financial account aggregation under the "Aggregation" tab of the Hydrogen Admin Settings.
Plaid Link
Once you have Plaid credentials set up on the Integrations Admin, you can embed Plaid Link into your app or web page. The Plaid Link will manage user credential validation, multi-factor authentication, and error handling for each institution that Plaid supports to ensure that your end-user is able to pull data from the account that they've linked.
In the code below replace the values for the following fields:
env
- enter 'development' for the Plaid development environment or 'production' if you are in a production contract with Plaid
token
- enter the widget_token
created in the Widget Link section below.
onSuccess
- follow the instructions in the Token Exchange section below
<button id="link-button">Link Account</button>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script>
<script type="text/javascript">
(function($) {
var handler = Plaid.create({
env: 'development',
token: '<widget_token>',
onLoad: function() {
// Optional, called when Link loads
},
onSuccess: function(public_token, metadata) {
// call integration/v1/token_exchange with client data, see example below
}
});
$('#link-button').on('click', function(e) {
handler.open();
});
})(jQuery);
</script>
Implementation
First you must create a widget link to retrieve a token for the Plaid link embed code.
mode
- set to iav
for bank links or aggregation
for account aggregation
clientName
- enter the application name that you want to display to your users
products
- for the bank auth product enter ['auth'], for account aggregation enter ['transactions'], and to enable both (default) enter ['auth', 'transactions']
webhook
- add if you would like transactions to automatically be pulled into Nucleus when they occur. Plaid does not support webhooks for balances or investment holdings.
POST /integration/v1/widget_link
{
"nucleus_client_id": "<nucleus_client_id>",
"vendor_name": "plaid",
"mode": "iav",
"vendor_request": { "client_name": "<name_to_display_on_widget>", "products": [ "auth", "transactions" ],
"country_codes": [ "US" ],
"language": "en",
"webhook": "https://[sandbox][api].hydrogenplatform.com/callback/aggregation/plaid" }
}
Sample Response
{
"widget_token": "link-sandbox-808d1a33-07ee-4bd9-90ae-9b460a2b14f8",
"vendor_name": "plaid"
}
Token Exchange
In the onSuccess
event of the Plaid widget, you will call our Integration API and exchange the Plaid public_token
and metadata
for the account details of the Nucleus client. Replace the nucleus_client_id
below with the ID of the client that is performing the link. Our server will do the exchange and store the mapping of the Plaid ID to Hydrogen for that client.
Please note that all requests in Hydrogen must be authenticated with proper OAuth 2.0 credentials and you must submit each request with a bearer token.
POST /integration/v1/token_exchange
{
nucleus_client_id: '<nucleus_client_id>',
product: 'atom',
integration_type: 'aggregation',
vendor_name: 'plaid',
vendor_request: {
metadata: metadata,
public_token: public_token
}
}
Sample Response
{
"nucleus_client_id": "0f51f4e6-c94c-4813-a0dc-c21eddfd4e5f",
"integration_type": "iav",
"product": "atom",
"vendor_name": "plaid",
"vendor_response": {
"institution_name": "Chase",
"institution_id": "ins_3",
"account": {
"id": "Z1r7gaxNa7uojogP7dDDfJNKQzbbxLFgjwryX",
"name": "Plaid Checking",
"type": "depository",
"subtype": "checking",
"mask": "0000"
},
"access_token": "access-sandbox-a760b923-3542-4df4-91db-59e015177caf",
"item_id": "NxmKwJeGJKu4A436jD11SwKya3aGw4hWJqkzG"
}
}
Account Aggregation
If you wish to use Plaid for account aggregation, you now can attach an
aggregation_account_id
in Nucleus to the Plaid account created, using the
item_id
from the Token Exchange response above in the following call:
POST /integration/v1/aggregation/account
{
"nucleus_client_id": "<nucleus_client_id>",
"product": "atom",
"vendor_request": {
"item_id": "<item_id from Plaid token exchange response>"
}
}
The result above will create an aggregation_account_id
in Nucleus. If you select "Automatically retrieve the latest balance, transactions and holdings after initial Aggregation Account creation" in the Integration Admin Settings, this data will pull in once the account is stored. Otherwise, you can perform the following calls to pull various account data:
GET /integration/v1/aggregation/balance/{nucleus_aggregation_account_id}
Plaid only supports the latest balance
GET /integration/v1/aggregation/transaction/{nucleus_aggregation_account_id}
Plaid only supports the last 90 days of data
GET /integration/v1/aggregation/holding/{nucleus_aggregation_account_id}
Only used for investment accounts
Webhooks
If you have kept the webook
URL in the Plaid Link, Hydrogen will automatically pull in transactions for the aggregation account as they occur. Plaid does not support events for account balances and investment holdings, so you will need to retrieve this data when the user logs into your app, or run a nightly job.
Instant Account Verification (IAV)
If you wish to use Plaid for verifying bank accounts, you now can attach a verified bank_link_id
in Nucleus to the Plaid account created, using the item_id
from the Token Exchange response above in the following call:
POST /integration/v1/iav
{
"nucleus_client_id": "<nucleus_client_id>",
"product": "atom",
"vendor_request": {
"item_id": "<item_id from Plaid token exchange response>"
}
}