Link Money Quickstart

Link Money Quickstart

This quickstart guide is designed to help you build a quick integration with Link Money from scratch. While following this guide, you will:

  1. Authenticate with the Link Money API
  2. Open our portal and link a financial account.
  3. Retrieve transaction and account data from the API.

Before starting the Link Money Quickstart guide, request a FinGoal developer account. You can expect FinGoal dev support to send you your credentials within 24 hours. You will use these credentials in the following steps.

Generate a User-Specific Access Token

The very first step to integrate with Link Money is to generate an access token. Link Money uses Client Credentials Oauth2 to create a JWT (JSON web tokens). The JWT tells Link Money who you are, and whose data you want to access.

ℹ️
For a deeper dive on authentication and authorization in Link Money, see Authentication.

While Link Money has several different kinds of tokens (corresponding to different levels of access), we must first focus on creating a user-level access token. This token lets us access Link Money on the behalf of a single end-user.

The following code snippet demonstrates how to retrieve a Link Money access token with Node.js. By requesting a token that’s specific to a user (one which has a user ID field in its request data), you can authorize the Link Money Gateway on behalf of a user.

The important fields to keep in mind for the generate token call are:

  1. Your client_id, which is issued in the Link Money developer portal.
  2. Your client_secret, which is issued in the Link Money developer portal.
  3. Your organization, which depends on your environment. If you are developing on behalf of a larger organization, ask the broad organization for the organization ID they have registered with Link Money.
  4. Your userId, which can be any string you want. In this flow, you do not necessarily need to create the user before creating their authentication token - use this token with the portal, and Link Money will do the rest. 
const axios = require("axios");

const createLinkMoneyToken = async (options) => {
  try {
    const { userId, itemId } = options;
    const data = {
      client_id: '{YOUR_CLIENT_ID}',
      client_secret: '{YOUR_CLIENT_SECRET}',
      audience: 'https://link-money-api/',
      grant_type: 'client_credentials',
      organization: '{YOUR_ORGANIZATION_ID}',
    };

		// use a userId string if you require a user token.
    if (userId) {
      data.userId = userId;
    
		// use an item_id string if you require an item token. 
    } else if (itemId) {
      data.item_id = itemId; 
    }
    
    const config = {
      method: 'post',
      url: 'https://dev-jhhgu9vc.auth0.com/oauth/token',
      headers: {
        'Content-Type': 'application/json',
      },
      data: data,
    }

    const createTokenResponse = await axios(config);
    const { data: tokenData } = createTokenResponse;
		const { access_token } = tokenData;
  } catch (error) {
    // any http errors will be surfaced here. 
  }
}

Open the Link Money Gateway

With a successfully generated user-specific access token, you have what you need to authorize a call to the Link Money Gateway, where your users can link their third party financial accounts for aggregation and verification. You must specify a flow_name query parameter to determine the Gateway’s user experience. Permitted flow names are:

  • ver_agg: Account verification is mandatory, while aggregation is optional.
  • agg_ver: Account aggregation is mandatory, while verification is optional.
  • agg: Account aggregation alone is offered.
  • ver: Account verification alone is offered.

Several additional query parameters determine how the gateway will behave when the user is ready to exit the account linking process.

  1. Redirect Flow: The gateway/widget is opened, the user interacts with the account linking tools, the gateway is closed, and the user is redirected to your application based on a redirectUri query parameter that you provide. Good for web applications.
  2. Deeplink Flow: The gateway is opened, the user interacts with the account linking tools, the gateway is closed, and the user is redirected to your application based on a deeplink query parameter that you provide. Good for native applications.
  3. Auto-close Flow: The gateway is opened, the user interacts with the account linking tools, the user finishes, and the gateway automatically closes. Good for environments that do not support redirects, or iframes. Providing neither a redirectUri nor a deeplink parameter will cause the portal to default to the auto-close flow.
const flowName = 'ver_agg';
const linkMoneyGatewayUri = `https://linkmoney-gateway-dev.fingoal.com/api/authenticate?token={YOUR_TOKEN}&flow_name=${flowName}`;
const redirectUri = '{YOUR_REDIRECT_URI}';

// option A: 
window.open(`${linkMoneyGatewayUri}&redirectUri=${redirectUri}`); 

// option B (in the markup): 
<iframe src=linkMoneyGatewayUri></iframe>

From there your user can follow the Fastlink flow to link their accounts for either aggregation or verification, depending on which flow you specified.

Link Money’s instance of the Yodlee Fastlink v4 securely authenticates with that institution.
Link Money’s instance of the Yodlee Fastlink v4 securely authenticates with that institution.
The user is prompted with a login form after selecting an institution. The user may also see a popup open, prompting them to authenticate with their provider directly.
The user is prompted with a login form after selecting an institution. The user may also see a popup open, prompting them to authenticate with their provider directly.
The user is prompted to select which accounts they want to link, and may link further accounts or exit the process.
The user is prompted to select which accounts they want to link, and may link further accounts or exit the process.

Retrieve User Data From Gateway

Once a user has linked an account, you have several options for beginning their aggregation flow:

  1. If you specified a redirectUri in step 2, the gateway will redirect to your application with a query parameter called events. This contains data about the linked accounts, along with the item_ids of anything the user linked, for use in further authentication. See Plaid Endpoints for using the item_id to retrieve data.
  2. If you set up webhooks with Link Money API, new user data will automatically arrive at your endpoint, in whatever aggregator style you specified (eg, Plaid).

For more information, see:

📞
Link Money Gateway Calls

Make API Calls to Retrieve User Data

To retrieve account and transaction data from the Link Money API, we need to follow two steps:

  1. Generate an access token.
  2. Make an API request to the desired endpoint.
  3. Grab the correct Link Money API environment (production/development)

To generate an access token, you can reuse the code from the first step of this guide. If you are a Plaid user, you will need to use the correct item ID, which can be collected either from the events data or from webhooks.

With the correct access token for a specific item, we can now make API requests to retrieve Plaid Accounts and transactions. 

// Accounts Call

const axios = require("axios");

const getAccounts = async (itemToken) => {
  try { 
    const url = `{YOUR_LINK_MONEY_API_URL}/v1/plaid/accounts`;
    const response = await axios.post(url, { headers: {
      Authorization: "Bearer " + itemToken
    }}); 

    const { data } = response; 
    const { accounts } = data; 
    return accounts;
  } catch(error) {
    console.log(error);
  }
}
// Accounts Call

const axios = require("axios");

const getAccounts = async (itemToken) => {
  try { 
    const url = `{YOUR_LINK_MONEY_API_URL}/v1/plaid/accounts`;
    const response = await axios.post(url, { headers: {
      Authorization: "Bearer " + itemToken
    }}); 

    const { data } = response; 
    const { accounts } = data; 
    return accounts;
  } catch(error) {
    console.log(error);
  }
}
// Transactions Call

const axios = require("axios"); 
const moment = require("moment");

export const getTransactions = async (itemToken) => {

	// note that you can use the same parameters here that you can for the Plaid request.
  const startDate = moment().subtract(30, 'days').format('YYYY-MM-DD');
  const endDate = moment().format('YYYY-MM-DD');

  const data = {
    start_date: startDate,
    end_date: endDate,
    options: {
      count: 250,
      offset: 0,
    },
  }

  const callConfig = { 
    method: "POST",
    url: `{YOUR_LINK_MONEY_API_URL}/v1/plaid/transactions/get`,
    headers: {
      'Content-Type': "application/json",
      Authorization: "Bearer " + itemToken
    },
    data
  }

  try {
    const transactionsResponse = await axios(callConfig);
    const { data: transactionData } = transactionsResponse;
		const { transactions } = transactionData;
		return transactions;
  } catch(error) {
    console.log(error);
  }
}

And that’s all! You have now successfully implemented Link Money in your application. For deeper information about how to integrate with Link Money further, consult the following links.