MoneyKit API

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.

Test Institutions

Credentials Bank

This institution simulates a real bank login flow using a username and password. You can control the login experience by using different combinations of username and password. You can use any other values than documented to cause the login to fail.

OAuth Bank

This institution simulates a real bank login flow using OAuth. The user will be redirected to a webpage to log in. Upon completion, the webpage will redirect back to your application. This is perfect for testing your redirect setup for MoneyKit Connect.

Instant Bank

The perfect bank for rapid developer testing downstream of the login process. This bank will not ask any questions and automatically grant all requested permission scopes for all available fake accounts.

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

To access MoneyKit API you must create and configure an App. An App is tied to one MoneyKit mode (Live or Sandbox). An app’s mode cannot be changed after creation.

An App can have multiple API keys (client_id and client_secret). API keys can access all Links for an App. This allows for both key rotation and giving multiple services in larger systems different sets of keys. Each set of keys can have different scopes if desired to limit the blast radius. Keys must never be exposed on the front end.

We recommend you create one app in Sandbox mode for development and testing and one in Live mode.

Once you have generated a set of client credentials you can use generate_access_token method to create a bearer token for full access to MoneyKit API.

This short-lived bearer token should be cached and used with subsequent requests to 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 then regenerate the access token and retry the initial request.

Versioning

Whenever MoneyKit API makes backward incompatible changes, we will create a new API version and continue to support the old API version subject to notice.

All requests can include MoneyKit-Version HTTP header to control the API version used for the request. All responses include 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).

Change Log

Coming soon.

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