Link Money API

Link Money API

Link Money is a suite of software that helps developers connect their applications to third-party sources of financial data, such as banks and credit unions. With LinkMoney, developers receive a dedicated front-end account linking solution managed through FinGoal. Access to user data is exposed to the developer through an API. Developers may also register to receive near-instantaneous data updates through LinkMoney webhooks.

LinkMoney is targeted at developers who can use the Link Money Web Gateway and integrate with the LinkMoney API. Some developers have standalone applications and find the LinkMoney solution more cost-effective and easier to integrate than other solutions.

Endpoints

Endpoints are broadly divided into sections described by the index. Each collection of endpoints offers access to a different set of functions. Most developers will only require a small portion of these endpoints to fully integrate with Link Money.

URL construction

Depending on which endpoint collection, you may only need to access certain endpoint collections and not others. Endpoint construction is essentially:

  1. The Base URL - for example, https://linkmoney-dev.fingoal.com
  2. The endpoint collection's name - plaid, yodlee, mx, cdp, etc. See each endpoint collection for the collection's name.
  3. The version - each endpoint collection has separate versioning rather than a holistic version control for the entire api - for example, v1.
  4. The endpoint, as specified in each endpoint's documentation.

Some examples include:

https://linkmoney-dev.fingoal.com/v1/plaid/transactions/get
https://linkmoney-dev.fingoal.com/v2/yodlee/transactions
https://linkmoney-dev.fingoal.com/v1/developer/configuration

🖥️
Developer Configuration

Pagination

All endpoints which return lists are paginated. These endpoints also support two query parameters which specify the number of records per page and the page to be returned.

Each response will include a pagination object specifying information on the total number of entries and the current page.

MX Endpoints

Plaid Endpoints

Yodlee Endpoints

Authentication

Link Money uses JSON Web Tokens (JWTs) to authenticate all protected API endpoints. Developers can create JWTs with their oauth2 credentials, issued by the Developer Dashboard. For the most part, JWTs should also be limited to a single user or a single account in scope.

Generic Tokens

In some cases, a Link Money API endpoint might require a generic token, which can access developer-specific resources but not user specific resources. These cases might include:

  • Creating, updating, or retrieving a developer configuration
  • Accessing anonymized bulk data
  • Accessing utility data

In cases where a generic token is warranted, the endpoint documentation will state that the route requires a generic token.

Generate a Token

  1. Retrieve your client_id and client_secret from the Developer Dashboard.
  2. With the client_id and client_secret, you can make a POST call to the Authorization Server with your credentials to exchange them for a JWT:
  3. curl --request POST \
      --url https://dev-jhhgu9vc.auth0.com/oauth/token \
      --header 'content-type: application/json' \
      --data '{"client_id":"{YOUR_CLIENT_ID}","client_secret":"{YOUR_CLIENT_SECRET}","audience":"https://link-money-api/","grant_type":"client_credentials"}'

    If the Authorization Server recognizes your client_id and client_secret, it will respond with a JSON payload containing the JWT:

    {
    	"token": "{YOUR_BEARER_TOKEN}",
    	"type": "Bearer"
    } 
  4. Use the token value to make your calls to resources requiring a generic token by including it as a Bearer token in your Authorization header.
  5. curl --request GET \
      --url https://link-money-api-development.herokuapp.com/plaid/v1/transactions/get/v1/generic_resource \
      --header 'Authorization: Bearer {YOUR_BEARER_TOKEN}'

Considerations

  • Generic tokens target only developer resources, not user resources.
  • Generic tokens should not be user-facing and should be for internal use only.
  • Generic bearer tokens in Link Money remain valid for one hour before they expire.

User Tokens

User JWTs let developers access API resources that are user-level. The token ensures that the endpoint will return data for the user specified in the JWT payload, and no other user data can be accessed with this token.

Generate a User-Specific JWT.

  1. Retrieve your client_id and client_secret from the Developer Dashboard.
  2. Retrieve the ID of the user for the token. Depending on your developer configuration, this value could be user.uid, user.id, or user.guid.
  3. Make a call to the Authorization server with your Oauth2 credentials and the valid user ID in the payload. For this example, we will use guid as the ID field, though any of the three are considered valid:
  4. curl --request POST \
      --url https://dev-jhhgu9vc.auth0.com/oauth/token \
      --header 'content-type: application/json' \
      --data '{"client_id":"{YOUR_CLIENT_ID}","client_secret":"{YOUR_CLIENT_SECRET}","guid":{USER_ID}", "audience":"https://link-money-api/","grant_type":"client_credentials"}'
  5. If the Authorization server recognizes your Oauth2 credentials, it will respond with a JSON payload containing the user-specific bearer token:
  6. {
    	"token": "{YOUR_BEARER_TOKEN}",
    	"type": "Bearer"
    } 
  7. Call to a user-specific resource in FindMoney with this bearer token to retrieve data for the specified user:
  8. curl --request GET \
      --url https://linkmoney.fingoal.com/v1/{user-specific-resource} \
      --header 'Authorization: Bearer {YOUR_BEARER_TOKEN}'

Considerations

  • User tokens access only resources that are user-specific.
  • User tokens expire after 3 hours, after which point they must be regenerated.
  • User tokens will be generated regardless of whether the user with the specified ID exists in the LinkMoney API. Calls to user-specific endpoints with tokens that are for a non-existent user will return {} empty JSON.

Item Tokens

For developers migrating from Plaid, Link Money offers authentication JWTs on the item-based level. Item JWTs allow you to access data for a single item in Link Money.

ℹ️
Though item tokens are a valid approach to authenticating with Find Money API's Plaid endpoints, developers can also leverage User Tokens with a user_id field for a different approach to Authentication.

Create an Item-Specific JWT

  1. Retrieve your client_id and client_secret from the Developer Dashboard.
  2. Retrieve the item_id for the item you want to authenticate (See Link Money Gateway Calls)
  3. Retrieve the organization for the organization you want to authenticate with.
  4. Make a call to the authorization server with your Oauth2 client credentials and the item_id in the payload:
  5. curl --request POST \
      --url https://dev-jhhgu9vc.auth0.com/oauth/token \
      --header 'content-type: application/json' \
      --data '{"client_id":"{YOUR_CLIENT_ID}","client_secret":"{YOUR_CLIENT_SECRET}","item_id":{YOUR_ITEM_ID},"audience":"https://link-money-api/","grant_type":"client_credentials", "organization": {YOUR_ORG_ID}}'
  6. If the Authorization server recognizes your Oauth2 credentials, it will respond with a JSON payload containing the item-specific bearer token:
  7. {
    	"token": "{YOUR_BEARER_TOKEN}",
    	"type": "Bearer"
    } 
  8. Call to an item-specific resource in Link Money with this bearer token to retrieve data for the specified user:
  9. curl --request GET \
      --url https://linkmoney.fingoal.com/v1/plaid/item-specific-resource \
      --header 'Authorization: Bearer {YOUR_BEARER_TOKEN}'

Considerations

  • Item tokens access only resources that are item-specific.
  • Item tokens expire after 24 hours, after which point they must be regenerated.
  • Item tokens will be generated regardless of whether the item with the specified ID exists in the Link Money API. Calls to item-specific endpoints with tokens that are for a non-existent item will return {} empty JSON.

Basic Tokens
⚠️
Although Link Money offers this capability for transitional ease from the MX platform, we strongly encourage using User Token instead, as they are more secure. If you still choose to use Basic Tokens, bear in mind that the encoded values in the header can be decoded by any party and should not be traded publicly.

Some platforms, like MX, use Basic Tokens. A basic token is a base64 encoding of your Oauth2.0 credentials which can be decoded server-side. These Basic Tokens can be both developer-level (generic) and user-level (specific).

MX Endpoints will specify whether they require generic or specific authentication.

Create a Generic Token

  1. Retrieve your client_id and client_secret from the Developer Dashboard.
  2. Concatenate these values into a single string separated by a colon: my_client_id:my_client_secret.
  3. Base64 encode the value. In this example, the encoded value is bXlfY2xpZW50X2lkOm15X2NsaWVudF9zZWNyZXQ=.
  4. Prepend Basic to the value to create the header:
  5. Basic bXlfY2xpZW50X2lkOm15X2NsaWVudF9zZWNyZXQ=

  6. In your HTTP call, use this as the Authorization header:
  7. curl -H "Authorization: Basic bXlfY2xpZW50X2lkOm15X2NsaWVudF9zZWNyZXQ=" https://linkmoney.fingoal.com/v1/mx

Create a Specific (User) Token

  1. Retrieve your client_id and client_secret from the Developer Dashboard.
  2. Retrieve the guid of the user.
  3. Concatenate these values into a single string seperated by colons:
  4. my_client_id:my_client_secret:user_guid

  5. Base64 encode the value. In this example, the encoded value is
  6. bXlfY2xpZW50X2lkOm15X2NsaWVudF9zZWNyZXQ6dXNlcl9ndWlk

  7. Prepend Basic to the value to create the header:
  8. Basic bXlfY2xpZW50X2lkOm15X2NsaWVudF9zZWNyZXQ6dXNlcl9ndWlk

  9. In your HTTP call, use this as the Authorization header:
  10.  curl -H "Authorization: Basic bXlfY2xpZW50X2lkOm15X2NsaWVudF9zZWNyZXQ6dXNlcl9ndWlk" https://linkmoney.fingoal.com/v1/mx/user-specific-resource

In some situations, Link Money endpoints are accessible with generic tokens, which are limited by developer scope, but not user or account scope.

Webhooks

Link Money API uses Webhooks to send updates to developers that lets developer applications know about data changes for new transactions, account balance updates, new account connections, and anything else worth sending a real-time update. This functionality also lets developers who use it skip having to pull data from the Link Money API on regular intervals to keep their applications abreast of the freshest user data.

Different aggregators have different webhook methodologies, schemas, and approaches. Link Money API offers webhooks in a variety of formats to make it easy to migrate from another aggregator's webhook system.

🧪
Test a Webhook in the Sandbox
Retries

Sometimes, for a variety of reasons, a webhook may fail. Webhook send failure in LinkMoney API is determined by the developer's callback URL's response. A webhook is considered successful if the callback URL responds to the webhook with any of these HTTP statuses:

  • 200 OK
  • 201 Created
  • 202 Accepted
  • 203 Non-Authoritative Information
  • 204 No Content

When an endpoint sends on of the following 2xx status messages, LinkMoney will assume the webhook was correctly received, and no retries or dropped data protocols will be activated. However, if a developer's endpoint responds with a non-2xx response, or if an endpoint fails to respond at all (Request Timeout), LinkMoney will assume that the webhook was not received.

LinkMoney webhooks try 3 additional times in 5-minute intervals to send data in the event that the initial webhook request failed. If, after the 15-minute retry window, the webhook still has not been received.

MX Webhooks

Plaid Webhooks

Yodlee Webhooks

Webhook URI

After setting up a webhook URI through this flow, data will automatically begin to arrive from any of the organizations to which the developer has access. These hooks will continue to flow regardless of whether or not the webhook URI returns a successful (2xx) response.

If your developer ID has not yet been registered with any organizations, please contact FinGoal Support (support@fingoal.com) with the organization you are attempting to access. If you have access to no organizations, you will not receive webhooks.

Request

PATCH /v1/webhooks/configuration

Request Headers

Field
Description
Authorization
A valid Authorization header with a Bearer ${token} using an authentication token generated from a Generic Token to authorize the call.

Request Body

Field
Description
webhookUri
A valid webhook URI where you would like to receive data updates.

Response

Code
Response Body
Description
201
The response body consists of a configuration object containing your developer name, callbackUri, and aggregator.
The webhook URL has been successfully updated.
400
An error object containing a link to pertinent documentation.
The webhook URI was improperly formatted; Link Money API could not interpret it as a URI.

Schema

Schema describe what kinds of data Link Money uses, how they are structured, and what data types they should be. Each schema is described by a table which includes the parameters' names, their data types, an example of each, and a description of what they are.

Data can be returned in several different structures. Check below to find your preferred format.

MX Schema

Plaid Schema

Yodlee Schema

CDP (CUFX)

Link Money Gateway

Quick URL Guide

API
Environment
Base URL
Link Money
Development
Link Money
Production

Product Features