Connections Management

Once connections have been created, these will need to be managed by the API Client (assuming the connections are on-going access AIS connections). There are several use cases related to the management of connections after the initial creation. These are:

• Re-authentication
• Re-consent
• Refreshing
• Manual sync
• Connection error handling

Re-authentication

• Similar process to adding a connection.
• Navigates user to bank / data provider for authorisation.
• It is recommended that the option to re-authenticate be provided to the user. This enables the following:
  • A user to add a new account to a connection.
  • A user to resolve a connection issue without needing assistance.
• See here for more about the re-auth flow.

Re-consent

• Applies only to API / Open Banking connections.
• Only eligible for connections that have tppConsent field set as true.
• See here for more about the 90 day re-consent flow.

Refresh

• Applies only to Legacy connections.
• Typically this is where user input is required to fetch data from the provider e.g. where MFA is required.
• This flow can be useful for a user to see the latest data for a connection so it is recommended to be made available for the user to initiate this flow.
• See here for more about the refresh flow.

Manual sync

• Manually attempts to fetch data from the bank/data provider.
• When as a result of direct user action, an IP address of the user should be provided.
• It is recommended that the option to manually sync be provided to the user.
• The manual sync endpoint should ideally only be triggered by user action and only in certain cases.
• The POST /syncendpoint will be rate limited once every 30 minutes per connection.
• See here for more about the syncing of connections.

Connection error handling

Please see here for a summary about the different error statuses possible on a connection.

The below diagrams show the connection error handling flow for each connection error. The decision points refer to fields on the user connection returned from GET /users/{userId}/connections.

The following fields on the can be used to determine the appropriate action:

• lastUpdated - the date of when data was successfully last updated on the connection. This dictates when the resync error status is set on a connection. When the resync error is set depends on the type of account in the connection.
  For most account types, if lastUpdated is more than 2 days old the resync error will be set. For the below account types, lastUpdated will be more than 40 days in the past before the resync error is set:
  • properties:*
  • asset
  • mortgage:*
  • loans
• lastSyncedAt - the last sync attempt on the connection. This date is updated on both sync success and error. Differs from the lastUpdated field which is only updated on a successful sync.
• tppConsent - a field that can be used to determine if the reconsent journey can be used for that connection.
• status - the status of the connection. Will be either ok or error.
• extendedStatus - more information about the error status of a connection. Possible values are
  • expired - consent has expired on the connection.
  • stoppedSyncing - there was an error syncing the connection and we have now stopped retrying the connection syncs (this happens after 3 days of failed sync retries).
• error - an error code describing the type of error on the connection.

Fields returned from https://identity.moneyhub.co.uk/oidc/.well-known/api-connections

• singleSyncOnly - this indicates that a connection will sync only once and will not sync again automatically without input from the user. In these cases the refresh flow should be used. Currently only applies to legacy connections.

📘

The below diagrams are intended to serve as a guide to which of the above use cases to apply for a given connection status. However it is recommended to provide options to users for reauth, reconsent (for API connections), refresh (for legacy connections) and manually syncing a connection.

API / Open Banking / Zoopla / Autotrader connections

Legacy connections

📘

If the connection is still showing an error state after following above actions and/or reauthenticating, please raise a ticket through the Moneyhub API Service Desk