[AmEx] Breaking Change - 2023-05-31

For Data API and Verification in the UK only.

AmEx is deprecating their Oauth API on 2023-05-31. In order to continue accessing Amex accounts, we are migrating to their new APIs. The provider id will then be ob-amex.

This is a breaking change as account and transaction IDs are not consistent between the 2 integrations.

List of changes

• [BREAKING CHANGE] transaction_id field is different for the same transaction between ob-amex and oauth-amex due to a different account_id being returned by Amex and the way transaction_id is generated.
• provider_transaction_idis a newly added field to ob-amex describing the ID Amex assigns to the transaction.
• normalised_provider_transaction_idis a newly added field representing a transaction ID in a TrueLayer consistent format (it is not subject to change).
• address / provider_id: newly added fields to the card-transactions meta object. The address is the merchant address returned as a string. These are optional fields.

• [BREAKING CHANGE] account_idwill be different for the same user account between ob-amex and oauth-amex due to different encryption used between the two APIs on Amex side.
• display_name may be slightly different due to a new character limit imposed by Amex.
• partial_card_number will display 4 characters instead of the previous 5.
• name_on_card will display the full account holder name instead of the previously abbreviated name, and will no longer include the title.

• credit_limit is a newly added field in ob-amex, which describes the remaining available limit for the account holder.
• payment_due is no longer supported by Amex API
• payment_due_date is no longer supported by Amex API

Supplementary Cards

• Supplementary cards will no longer be supported with the ob-amex connector.

Client impact

• For clients who store a history of a user’s transactions, we do not recommend trying to reconcile transactions accessed via the new Amex integration with those you’ve stored from the old one. The best approach is to start afresh: ask users to connect their amex account(S) via the ob-amex provider_id and re-fetch the historical transaction data you need. You should make these transactions data requests immediately after the user connects their accounts to maximise the amount of data available to you.
• If you would like to attempt to reconcile transactions from oauth-amex to transaction accessed from ob-amex, the best possible available fields present in both transaction payloads are: amount, description, timestamp
• Any part of your integration that used the provider_id oauth-amex will need to be updated it to ob-amex as per the instructions below. Failure to do so will mean users will be unable to connect their Amex accounts starting date TBC
  

How we will make the change available

• We will be running ob-amex in parallel with oauth-amex to migrate connections to the new implementation when connections are sent to us for re-authentication.
• We will enable ob-amex in private beta release channel for you to test the changes ahead of us turning off new connection creation to oauth-amex. If you would like to test ob-amex please contact us and we will whitelist you for ob-amex private beta.

Client actions

How you do provider authentication		If you use Reauth	Action required alongside reconciling List of Changes outlined above
Clients using TrueLayer auth dialog provider selection screen	All providers enabled when creating new connections		No additional action beyond reconciling the list of changes outlined above.
			You will need to ensure that all reauths are being directed to ob-amex You will receive 500 errors for oauth-amex connections. At this point, you should direct users to create a new ob-amex connection
	Selection of UK providers enabled when creating new connections		You will need to re-configure your auth link to include ob-amex and remove oauth-amex if previously included
			You will need to re-configure your auth link to include ob-amex and remove oauth-amex if previously included You will need to ensure that all reauths are being directed to ob-amex You will receive 500 errors for oauth-amex connections. At this point, you should direct users to create a new ob-amex connection
Clients using their own provider selection screenor direct bank auth	Use TrueLayer providers endpoint		You will need to ensure you do not make requests for oauth-amex after 2023-05-31, 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-amex, you will need to reconfigure it to have ob-amex
			You will need to ensure you do not make requests for oauth-amex after 2023-05-31, 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-amex, you will need to reconfigure it to have ob-amex You will need to ensure that all reauths are being directed to ob-amex You will receive 500 errors for oauth-amex connections. At this point, you should direct users to create a new ob-amex connection
	Do not use TrueLayer providers endpoint i.e. if you have hardcoded the provider-ID oauth-amex		You will need to ensure you do not make requests for oauth-amex after the change, otherwise you will begin receiving 500 errors From 2023-05-31, when we switch on ob-amex, requests for new auth URIs need to be made on ob-amex and therefore subsequent refresh requests and resource requests for those new connections will need to be made on ob-amex You will receive endpoint not supported errors when attempting to create new connections using oauth-amex
			You will need to ensure you do not make requests for oauth-amex after the change, otherwise you will begin receiving 500 errors From 2023-05-31, when we switch on ob-amex, requests for new auth URIs need to be made on ob-amex and therefore subsequent refresh requests and resource requests for those new connections will need to be made on ob-amex. You will receiveendpoint not supported errors when attempting to create new connections using oauth-amex You will need to ensure that all reauths are being directed to ob-amex You will receive 500 errors for oauth-amex connections. At this point, you should direct users to create a new ob-amex connection