API Overview

Introduction

The MoneyKit API gives developers access to your end-users’ financial data. By using the API in combination with MoneyKit Connect, a user can grant your application permission to view their financial account data.

MoneyKit provides a unified product API across all providers of financial data. This means you will get the same response formats no matter which institution your end-users have accounts with.

Links

A Link is a MoneyKit object that represents a connection from your app to an individual, end-user login at an institution. One Link can have multiple accounts.

To access your end-user’s account data via MoneyKit API you must create a Link using MoneyKit Connect and MoneyKit API.

The end-user will then grant permissions to accounts, limited by data scope. Once this process is completed, you will have obtained a Link ID that can be used to refresh and fetch data via any of our Product endpoints while in the connected state.

Link IDs should not be exposed outside of your backend API.

Example of a Link

An end-user logs into their personal Chase accounts via OAuth, granting your application access to read balances and transactions on only their checking and savings accounts.

The Link ID you receive will have those 2 accounts and your application will be able to use our Accounts and Transactions products to see their transaction history across them.

Your application would not be able to request unpermissioned data such as Account Numbers or Identity for these 2 accounts.

Reauth

Links can expire (error code auth_expired) for several reasons such as

• End-user changes credentials
• Certain products may need reauthorization if too much time has passed since a previous authorization.
• End-user revokes access.

You can use MoneyKit API and MoneyKit Connect to reauth an existing Link. If you have webhooks configured, you will receive an event when a Link’s state changes. You can also check a Link’s state using get_link.

Modes

MoneyKit has two modes:

• Live
• Sandbox

Live Mode

Live mode allows end-users to connect to their financial accounts with institutions.

Once the end-user has granted your app permission, you can fetch data using our product endpoints.

Developers must allow end-users to disconnect their accounts from within an application. MoneyKit has an endpoint to disconnect a Link which will stop your application from receiving new data or webhook events.

Sandbox Mode

Sandbox mode is a restricted version of Live with test-only institutions. All sandbox activity is free and you can use this mode for development and testing.

There are several test institutions and accounts you can use to simulate different scenarios and products. All test institutions simulate MoneyKit products such as account balances and routing, identity, transactions, and investments. Learn more about the Sandbox test banks.

Links created in sandbox mode are just like regular links, but they will automatically expire and disappear 30 days after creation. You will receive webhook notifications when sandbox links expire.

Test Product Data

Each test bank will have at least 3 selectable accounts (Checking, Savings and Credit Card) with balances, account numbers and identity data randomly generated. Account balances can be refreshed via the product refresh endpoint where new random balances will be generated.

A selection of fake transactions can also be generated with at least one pending transaction present in each refresh. After a subsequent refresh previously pending transactions will be resolved. This allows you to fully test get_transaction_diff.

Note: The number of refreshes allowed for transactions is limited in Sandbox.

As an example:

1. Call get_transactions_diff for your sandbox link and store the 2 transactions returned:

   txn_id	description	pending
   1	Coffee	false
   2	Food	true

2. Refresh the transactions on your sandbox link using refresh_products

3. Call get_transactions_diff for the sandbox link and there should be new transactions along with 1 update for transaction 2 where pending is now false. Apply these changes to your table.

   id	description	pending
   1	Coffee	false
   2	Food	false
   3	Drinks	true
   4	Taxi	false

Test Webhooks

Webhooks for product refreshes and state changes will be triggered in Sandbox.

You can also manually trigger webhooks for sandbox links using trigger_test_link_webhook_event.

API Access

The MoneyKit API is accessed from the perspective of your "App", which MoneyKit will create and provision for you. You will have two versions of the app, one Live and one Sandbox.

Your App will have one or more API keys, represented by a client_id and client_secret pair). They can be generated and accessed on your app's Dashboard. These keys can access all links for the appropriate version of your App (keys for the sandbox version can access only sandbox links; keys for the live version can access only live links).

You can rotate your keys at any time on the Dashboard. When keys are rotated, the previous keyset will continue to function for a few days, giving you time to change to the new keys without downtime. We can also create additional keys for you if necessary.

Once you have generated a set of keys you can use the generate_access_token method to create a bearer token for full access to MoneyKit API. This short-lived token should be cached and used with subsequent requests to the MoneyKit API as an HTTP header Authorization: Bearer {token}.

You can check the expiry (expires_in) to refresh the token just ahead of time, or check for api_error.auth.expired_access_token API errors and then regenerate the access token and retry the initial request.

Versioning

Whenever we make backward-incompatible changes to the MoneyKit API, we will create a new API version, and continue to support the old API version. We will terminate support for old versions only after providing explicit advance notice to all users and giving them time to upgrade to a newer version.

All API requests can include a MoneyKit-Version HTTP header to control the API version used for the request. All responses include a MoneyKit-Version HTTP header so you know which version was used.

We recommend you set the MoneyKit-Version HTTP header to a known version to avoid unexpected API changes in your application. Our client libraries have dedicated ways of setting the default version header which you can find in their documentation. Each client library will have a default version hardcoded.

Breaking Changes

The following are examples of breaking API changes that will result in a new API version:

• Removing or renaming a request parameter or response field or enum cases
• Removed functionality
• Changes to the intended functionality
• Adding new required parameters or making an existing optional parameter required
• Changing the meaning of error codes

The following are examples of non-breaking API changes that will not result in a new API version:

• New endpoints or products
• New fields in responses
• New enum cases
• Changes to error responses such as error message or documentation url (excluding error code).

Client Libraries

MoneyKit maintains two official client libraries generated from our OpenAPI spec.

Official Client Libraries

Python

moneykit/moneykit-python

Ruby

moneykit/moneykit-ruby

Reporting Issues

All MoneyKit requests contain a X-Request-Id HTTP header in the response. You can log this out in your service.

Please supply the following values when creating a support request:

• App Client ID
• Request ID
• Link ID and/or Link Session token