Instantly verify bank accounts and aggregate held away account data
Integrations > Plaid
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).
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)
client_id
and paste it into the Hydrogen Admin Credentials screen as the "Username/Client Id" for Plaid.secret
and paste it into the Hydrogen Admin Credentials screen as the "Password/Client Secret" for PlaidOnce 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 Plaidtoken
- 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>
mode
- set to iav
for bank links or aggregation
for account aggregationclientName
- enter the application name that you want to display to your usersproducts
- 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"
}
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"
}
}
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}
GET /integration/v1/aggregation/transaction/{nucleus_aggregation_account_id}
GET /integration/v1/aggregation/holding/{nucleus_aggregation_account_id}
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.
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>"
}
}
*Plaid is a technology integration on the Hydrogen platform. There is no implied partnership or company affiliation unless otherwise stated.