Back to Integrations

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 and get your client_id, public_key, and secret (which differs per environment). If you already have a Plaid account, you can go ahead and sign in to retrieve these values. We currently support Plaid Development and Production environments, not Sandbox (dummy accounts).

Implementation

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:

<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({
    clientName: '<APP NAME>',
    env: 'development',
    key: '<PLAID PUBLIC KEY>',
    product: ['auth', 'transactions'],
    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>

1) 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

2) 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 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>"
    }
}

Instant Account Aggregation (IAV)

2) 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 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>"
    }
}

3) The result above will create an aggregation_account_id in Nucleus. Once the account is stored, you can pull balances, transactions, and holdings for the aggregation account.

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}