Integration Quickstart Guide

Follow the guide below to learn the Hydrogen Integration Admin & APIs



Integration Overview


Introduction

Hydrogen Integrations is a suite of APIs and admins that allow developers to push and pull data seamlessly to or from 3rd party APIs including KYC, ACH, CRM, market data, account aggregation, KMS, IAV, BaaS, brokerage and more. Our integration framework is an easy low-code alternative to struggling with complex fintech APIs. Hydrogen will act as the only integration point and API you ever need to interact with!

The following modules are all part of the Integration suite:

Integration Vendors

The Integration Portal is the hub that lists all integration vendors that are currently supported. Vendors are tagged with categories for easy searching and filtering. Every vendor has its own page with instructions on set up and integration.

Integration Admin

After deciding which integrations are right for your application you can supply the API credentials and choose the applicable settings in our admin. This can be accessed securely after logging in to our developer portal.

Integration API

The Integration API is similar to other APIs that you may have already interacted with on Hydrogen. It's built on REST principles with resource oriented URLs and HTTP response codes. All API responses are returned in JSON format. Additional features of the API include filtering, pagination, and data caching. View the online documentation here.

Sandbox Base URL: https://sandbox.hydrogenplatform.com/integration/v1
Production Base URL: https://api.hydrogenplatform.com/integration/v1


Platform Interaction

The integration APIs will both push and pull data to/from entities throughout the Hydrogen platform. All data that needs to be pushed to a 3rd party service MUST first be stored in Nucleus or Molecule. This is done to both standardize the data collection and to allow developers to push data asynchronously. Let's walk through an example of how this interaction works with a KYC check.

Before submitting the KYC check, we will first create a client in Nucleus:

POST /nucleus/v1/client


{
  "username": "[email protected]",
  "email": "[email protected]",
  "first_name": "John",
  "last"_name: "Doe",
  "date_of_birth": "1980-01-15"
}

The result of this request will create a client_id in Nucleus. Now to perform an "iv" (identity verification) check in the integration service, we just need to supply the nucleus_client_id and the type of KYC we wish to perform. All data that is needed from the client object including the name and date of birth will be automatically pulled from the data store.

POST /integration/v1/kyc


{
  "nucleus_client_id": ""<client_id created above>",
  "product": "atom",
  "kyc_type": "iv"
}

Once the KYC response has been received back from the vendor, the integration service will read the output and decide if the identity supplied is a match, no_match, or inconclusive. If it's a match, the is_verified flag for the Nucleus client will automatically be set to "true" for you so it's easy to see which clients have passed KYC. That's all there is to it! We take care of all data cleaning and transformations so you only need to work with our API.


Data Storage

There are two types of data stored from an integration response: 1) unstructured data and 2) structured data.

Unstructured Data

Raw responses from every integration vendor request are stored in their original form in our database. These can be used later for auditing, analytics and regulatory reporting.

Structured Data

Raw data is useful for auditing but it's difficult to build apps with. That's why we take the raw data and standardize the data needed to store in our structured data model Nucleus. Below is an example of what a structured Aggregation Account looks like. You will see all data labels have been standardized across every vendor and all extraneous data has been excluded:


{
  "id": "f96fad3e-a8cf-4915-bc0c-da4d9693ab83",
  "create_date": "2017-01-03T00:00:00.000+0000",
  "update_date": "2017-01-05T00:00:00.000+0000",
  "client_id": "b1d2b9dc-fb9d-4ce2-b2df-eb8801127b23",
  "account_name": "Bank Gold Checking",
  "institution_name": "Citywide Bank",
  "category": "Bank Account",
  "subcategory": "Checking Account",
  "account_number": "566788991",
  "mask": "XXXXX8991",
  "currency_code": "USD",
  "bank_link_id": null,
  "is_asset": true,
  "is_business": false,
  "is_investment": false,
  "is_active": true,
  "financial_offer_id": "6n2725g4-c449-4ae2-9349-576cb7897l72",
  "metadata": {}
}



Integration Vendors

Now that we have a good introduction to the integration platform we will explore each module in more detail using account aggregation as an example. To start with the integration we will first check the Integration Homepage to see a current list of vendors that are supported. Each vendor is separated by category such as ACH or KYC and can be searched and sorted.


Vendor Pages

When you click on a vendor from the main integrations homepage, you will be taken to that vendor's page. This should be the first place you start with our integration service, as you will find all the information you need for each vendor including instructions to sign up, store credentials in our admin, and submit API requests. An example is shown below for MX.




Integration Admin

After going through the account aggregation vendors and speaking with MX representatives, we have decided to move forward with them as a vendor for our PFM app. Now we can add our MX keys and settings on the Hydrogen admin. To access the admin you must first Sign Up, complete the onboarding application, and be granted Sandbox credentials. You will then see a navigation like the one shown below when you log in to your developer account. Clicking the "Integrations" tab on the header will take you to the admin.


Credentials

The credentials section gives you the ability to add and edit vendor credentials using the interface in the screenshot below. Each feature is numbered and explained below the image:

Feature Description
1 Click the "Plus" icon to add a new vendor to the config.
2 Displays the Integration category such as "Aggregation" or "KYC".
3 Displays the logo of the vendor chosen for the credentials.
4 Displays the vendor environment. The two options are "Development" (Sandbox or Testing) or "Production" (Live). Please note, this is the vendor's environment and does not relate to the Hydrogen dev environment. For instance, you may use Production credentials for a vendor in the Hydrogen Sandbox and vice versa.
5 Turns the vendor config on or off. When the toggle button displays "Off" this integration will not be available for use.
6 Displays the Username or Client ID of the vendor credentials, sometimes referred to as the client_id in OAuth implementations.
7 Displays the Password or Key of the vendor credentials, sometimes referred to as the client_secret in OAuth implementations.
8 Displays the Public Key or Token for the vendor where applicable. This is normally used when there is an end user verification in addition to the application.
9 Press this button to test in realtime if the credentials supplied are valid. If valid a green check mark will display, otherwise a red X will display. Please contact the vendor if your credentials do not work properly.
10 Edit or Delete the credentials.

Settings

Now that we have stored the credentials for account aggregation we must update the settings to activate the integration. The screenshot below is an example of settings for Account Aggregation which are explained more here.

There are three types of settings in the admin that are illustrated in this account aggregation example:

Feature Description
1 Vendor Choice: Choose the vendor you wish to use for the data type within the category. In this example we have chosen MX for financial account aggregation and Zillow for real estate valuations. One vendor may be used for multiple integration types within a category, which is why it must still be chosen in the settings after enabling in the credentials.
2 Platform Orchestrations: Some integrations can automatically have other Hydrogen APIs in Atom or Molecule call their adaptors and perform actions. This makes it simpler to orchestrate workflows that may require multiple API calls. In this example we have chosen to "Automatically update all aggregation account data when the Aggregation Account Overview is retrieved." By choosing this option, each call to GET /nucleus/v1/client/{client_id}/aggregation_account_overview will automatically pull the latest balances, transactions, and holdings for all accounts aggregated. This means you do not have to call GET /integration/v1/aggregation/balance, GET /integration/v1/aggregation/transaction, or GET /integration/v1/aggregation/holding separately for each account and each page refresh.
3 Data Settings and Transformations: In this example we have chosen to "Restrict accounts pulled back from the vendor to the following currency: USD". By choosing this option, any account or transaction with a ISO 4217 currency code that isn't USD will not be stored in Hydrogen. This is useful for US based apps that do not wish to perform FX conversions or can't legally work with non USD based accounts.



Integration API

Each vendor page will list the calls needed to perform the integration. Additionally, many integration categories have orchestrated settings that will perform API requests automatically after storing data in Atom or Molecule. However, there are times when you may wish to view more details on an API request and response. Full API reference for the Integration API is available here.


Authentication

All Hydrogen APIs use OAuth 2.0 to facilitate authorization on the API, an industry standard framework for authorization. Please follow the Authentication Guide in the Hydrogen Atom Quickstart.


Adaptors

After API authentication we will be interacting with the integration APIs found in the API reference here. Each integration category such as account aggregation has a set of "adaptors" which are generic services that abstract away all reference to the 3rd party vendor APIs. Based on the aggregation vendor that we set above (MX), the adaptor will make the requisite calls to MX, pull back the data, and transform it for storage in Nucleus Aggregation Account. Below is an example of the creation of an account. You will see that the only input needed is the client_id from Nucleus and the Hydrogen product:

POST /integration/v1/aggregation/account


{
  "nucleus_client_id": "<nucleus_client_id>",
  "product": "atom"
}

Vendor APIs

All integrations to the vendors are handled by the adaptor for each integration category. Hydrogen has performed all the API calls to the vendor behind the adaptor. Once you select which vendor you wish to use for the category, the adaptor will take care of all the API requests, responses, and data transformation. This means that you will NOT have to interact with any other APIs or documentation EVER! Hydrogen is your ONE integration point and fintech API.