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)

1. Copy the client_id and paste it into the Hydrogen Admin Credentials screen as the "Username/Client Id" for Plaid.
2. Copy the secret and paste it into the Hydrogen Admin Credentials screen as the "Password/Client Secret" for Plaid
3. 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

Widget Link

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