[Starling] Breaking Change on 3rd October 2022

The current integration is highly incident prone and has caused multiple outages in our service to Starling in the last 12 months. This breaking change will impact all clients of data and verification in the UK. This document does not apply to the Payments API.

List of changes

• Requests to /accounts/${account_id}/transactions for the same /account_id will return transactions with different transaction_ids in the new integration from the old integration
  • Clients may instead wish to use the provider_transaction_id for reconciliation, as this field’s value will be unchanged

• At present oauth-starling returns the account holder’s name in the display_name field of the /accounts response. ob-starling will return the account name instead eg: “personal”, “joint” etc. (The Account holder name is still available in /info which is where it was before but it was also in /accounts)

• Changes to the meta fields for the/transactionsendpoint:
  • The field nameprovider_sourcein meta object is now referred to asprovider_category
  • provider_transaction_idis now returned in the response as per TrueLayer documentation

• Forob-starlingthe Description field will no longer be pre-fixed by the counterparty name.
  • If you requirecounter_party_perferred_name, the field you should look at isprovider_merchant_namewhich is in the meta object. This is populated by a field in the OB spec,merchantdetails.merchantname, however, it is an optional field and therefore we cannot guarantee it is always populated.
  • As a general point across all open banking spec providers, we populatemeta.counter_party_preferred_namewith creditor or debtor account name.  Where neither of these 2 fields is supplied,meta.counter_party_preferred_nameis not present.

Client impact

• If you have hard-coded provider-IDs into your product and do not change the provider ID to ob-starling, the change will mean end users are unable to grant new consents
• If your auth link is configured to have oauth-starling, you will need to reconfigure it to have ob-starling
• For all clients: Since Starling also offer the ability for end users to reauthenticate AIS consent within the Starling banking app, some consents will be broken when we turn off oauth-starling. We do not have visibility of the magnitude of consents that are re-authenticated in this way

Client actions

How you do provider authentication		If you use Reauth	Action required
Clients using TrueLayer auth dialog provider selection screen	All providers enabled when creating new connections		No action is needed and no disruption will be experienced
			You will need to ensure that all reauths are being directed to ob-starling  You will receive 500 errors for oauth-starling connections. At this point, you should direct users to create a new ob-starling connection
	Selection of UK providers enabled when creating new connections		You will need to re-configure your auth link to include ob-starling and remove oauth-starling if previously included
			You will need to re-configure your auth link to include ob-starling and remove oauth-starling if previously included You will need to ensure that all reauths are being directed to ob-starling  You will receive 500 errors for oauth-starling connections. At this point, you should direct users to create a new ob-starling connection
Clients using their own provider selection screen or direct bank auth	Use TrueLayer providers endpoint		You will need to ensure you do not make requests for oauth-starling after 2022-10-03, otherwise you will begin receiving 500 errors You need to clear your cache of the providers endpoint, should you cache the providers list If your auth link is configured to have oauth-starling, you will need to reconfigure it to have ob-starling
			You will need to ensure you do not make requests for oauth-starling after 2022-10-03, otherwise you will begin receiving 500 errors You will need to clear your cache of the providers endpoint, should you cache the providers list If your auth link is configured to have oauth-starling, you will need to reconfigure it to have ob-starling You will need to ensure that all reauths are being directed to ob-starling  You will receive 500 errors for oauth-starling connections. At this point, you should direct users to create a new ob-starling connection
	Do not use TrueLayer providers endpoint i.e. if you have hardcoded the provider-ID oauth-starling		You will need to ensure you do not make requests for oauth-starling after the change, otherwise you will begin receiving 500 errors From 2022-10-03, when we switch on ob-starling, requests for new auth URIs need to be made on ob-starling and therefore subsequent refresh requests and resource requests for those new connections will need to be made on ob-starling You will receive endpoint not supported errors when attempting to create new connections using oauth-starling
			You will need to ensure you do not make requests for oauth-starling after the change, otherwise you will begin receiving 500 errors From 2022-10-03, when we switch on ob-starling, requests for new auth URIs need to be made on ob-starling and therefore subsequent refresh requests and resource requests for those new connections will need to be made on ob-starling You will receive endpoint not supported errors when attempting to create new connections using oauth-starling  You will need to ensure that all reauths are being directed to ob-starling  You will receive 500 errors for oauth-starling connections. At this point, you should direct users to create a new ob-starling connection

Key dates

• From 03-10-2022 at 11am BST:
• A new provider-ID ob-starling will exist in the providers endpoint in public beta
• Requests for new auth URIs for oauth-starling will no longer be possible;
• Token refresh and resource requests for oauth-starling will continue to work for 90 days.
• From 09-01-2023:
• oauth-starling refreshes & resource requests will no longer be possible
• All requests to Starling will need to be made to ob-starling as it will be the only provider ID that you can use
• ob-starlingwill be available in GA