Connection lifecycle

Moneyhub store the user's 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 user's 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 up to 36 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 on the type of connection:

• api: Every 4 hours between 6am and 11pm
• legacy: Once overnight and when receiving webhooks from our screen scraping partner.
• zoopla: Monthly
• autotrader: 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.

We recommend using the enableAsync option when triggering a manual sync so that it runs in the background. This is particularly useful for syncs that take longer than usual to complete. The syncCompleted webhook can be used to be notified when the sync has completed.

Reauth/Refresh/Reconsent

📘

Connection IDs

When refreshing or reconsenting a connection, the connection ID value will not change for the connection the action is being carried out on.

For reauthorising a connection, the connection ID will change. If you select a subset of accounts to reauth in comparison to what was connected before (for example, old connection had accounts A, B, C, on reauth you only select accounts B, C) the accounts not selected will still exist and have the old connection ID and will still sync until expiry, while the selected accounts will have a new connection ID and have the new consent period (so in the example, Account A will have the old connection ID and keep syncing until old expiry - or if expiry has already elapsed, will no longer sync. Accounts B & C will have a new connection ID and new consent period).

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
• reconsent

Reauth/reconsent/refresh a connection

One of the scopes above can be used to create an authorisation URL that will take a user through the reauthentication/reconsent journey. Please see here for more information on creating an authorisation URL.

These scopes require a claims parameter to be sent that contains a sub value and a mh:con_id value. Please see here for what these claims should look like.

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, reconsent or refresh is openid. If any other scope is provided the result will be an invalid_scope error.

If using the reauthentication flow, it is important to introspect the id token that gets returned after exchanging the auth code as the connection id can change 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 the user’s consent has expired and tppConsent on the connection is false.
• Update the login credentials on a legacy connection.
• If the provider, account details, and credentials stay the same, the connection ID usually remains unchanged. However, if there are changes to any of these details, we'll issue a new connection ID to keep your connection secure and up-to-date

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.

Reconsent

This flow should be used to:

• Renew consent on an open banking connection where tppConsent is true on the connection.
• Consent can be renewed on a connection before or after the expiry of the connection. If a connection has been expired for more than 90 days, tppConsent will be set to false meaning a full re-auth will be required.
• Please see the guide on 90 day consent changes for more information.

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 with that connection from our database.

The endpoint can be found in our API.

Post Connection Enrichment

Once a connection has been completed, enrichment activities take place. At the moment they are:

• Regular transaction detection

You can be notified of when these actions have been completed in the following places:

• Sync end points
  • Sync accounts array now has a postConnectionEnrichmentStatus and postConnectionEnrichedAt fields
• Post connection enrichment webhook