Connection lifecycle

Moneyhub store the users account data for as long as the connection is maintained. Should the connection expire the data is left in that last updated state until the user re authenticates.
Only by removing the connection will the users account data be deleted.

Adding connection

A financial connection can be added to a new user or to an existing user as explained in our Use Cases.
It is only after exchanging the authorisation code and getting a successful response that you can start requesting the data from our API.

The id token that gets returned contains the connection id under the mh:con_id property.
An example response can be found here

When exchanging the authorisation code and creating the connection with the bank we fetch between 1 to 3 months of transactions that will be available immediately.

After the initial process we fetch the remaining transactions in the background, which will be available in the next couple of minutes. By default we get 12 months of transactions at this stage, but this varies per bank, and some may only provide 3 months total.

The best way to get notified about the transactions that are fetched in the background is by subscribing to our Transactions webhook.

Syncing

Our API automatically syncs connections to update their financial data (accounts/balances/transactions).
The schedule varies depending of the type of connection:

  • api: Every 4 hours between 6am and 11pm
  • legacy: Once overnight and when receiving webhooks from our screen scrapping partner.
  • zoopla: Monthly

A manual sync can be triggered on our API using the sync endpoint for a specific connection at any point. For api connections, this will fetch data from the financial provider (e.g. bank). Most providers don't set limits on how often you can do this, but some do - for example, Triodos is limited to 4 times a day per user connection. The automatic updates already take account of these limits, so we recommend against regularly calling the manual sync endpoint, to avoid issues with providers like Triodos.

Reauth/Refresh

Some of the OpenBanking APIs that we connect to require the user to re-authenticate every 90 days. In addition we have screen-scraping connections that the user will need to update if their credentials change. In order to support these flows we support the following scopes:

  • reauth
  • refresh

These scopes require a claims parameter to be sent that contains a sub value and a mh:con_id value. Moneyhub will then take the user through a re-authentication journey or “refresh” journey.

We advise that the above 2 scopes are used with the response_type of code id_token.

The only scope that can (and must) be supplied along with either reauth or refresh is openid. If any other scope is provided the result will be an invalid_scope error.

It is important to introspect the id token that gets returned after exchanging the auth code as the connection id can be changed after a re authorisation.
An example response can be found here
This behaviour can be caused for several reasons:

  • The AISP does not return consistent account ids when re authorising.
  • The user has selected a different set of accounts compared to the initial consent.
  • The user has multiple connections with the same bank but has selected different accounts on each consent.

The connections of a user can always be fetched from our API

Reauth

This flow should be used to:

  • Re authenticate an open banking connection once that the user’s consent has expired.
  • Update the login credentials on a legacy connection.

Reconsent

This flow should be used to:

  • Renew consenton an open banking connection once that the user’s consent has expired where tppConsent is true on the connection.

Refresh

This flow is available only for legacy connections when the input of the user might be required to fetch the latest data. This is usually the case when MFA or security questions are enabled on the bank site.

This flow is not available for open banking connections as user input is never required to fetch the latest data, unless the consent has expired. If this is the case the reauth flow will need to be used to get a new consent.

Removing connection

A connection can be removed which subsequently will revoke the consent that the user granted.
This in turn will delete all of the data associated to that connection from our database.

The endpoint can be found in our API.