OAuth Bank Migration


As part of the launch of the new OAuth connections customers will need to migrate from the old financial institution to the new financial institution. After they have moved they will need to authenticate with that new OAuth connection. Although this will cause some disruption for your customers at first due to the Authentication step, it will provide them a much more reliable and stable experience going forward. They will also have increased control of their data sharing. This guide outlines the process of migration and some of the best practices for using the migration service.

As each new direct financial institution connection becomes available there will be a launch date followed by a full migration date. The launch date is when the connection first becomes available to customers so they can add accounts. This is also when accounts can be migrated. The full migration date is when we will automatically move customers over to the new connection.

To migrate an existing set of accounts to a new set you would use the migration service API.

The Migration Service Does 3 Things

  • 1

    It changes the FI ID from the old to the new FI ID.

  • 2

    We then place the aggregation status code of the account to code 948. This code can be used to programmatically present the customer with specific messaging related to authenticating for the first time.

  • 3

    The financial institution transaction identifier is formatted to assure deduplication of transactions.

With the account now placed in a 948 aggregation status it is then possible to use that status as a programmed indicator to prompt the customer to authenticate their account using the new OAuth method.

Here is the step by step process you should follow:

  • 1

    Indicate to the customer that their connection has been updated for the financial institution and that this new connection requires their authentication.

  • 2

    Call for finicity connect type fix for the institutionLoginId account set.

  • 3

    Present Connect Fix flow to the customer.

  • 4

    Customer will be prompted to login to their FI via the Connect Fix flow. Once authenticated, the accounts will update.

There are a few best practices to follow in your application during the adoption of a new financial institution connection.

Technical Articles

Best Practice Recommendation 1

It is best to swap out the old connection for the new connection on the launch date. This is the day it becomes available for new customer adds. The old connection is still available for current customers to fix and maintain, so a good first step is simply directing new customers to the new process so that it can be monitored and validated. For connect full you pass a parameter on the call as indicated in the institution settings guide below. If your using connect lite flow then you would look for the OAuth enabled flag on the FI list to see what the new OAuth FI is and then compare that to the old FI value on the new FI to know which one to replace.

Best Practice Recommendation 2

Once a new connection is live you can give your customers an option to opt in to the new connection. You can build a message for your customers allowing them to opt in. If they choose to do so, you can use the migration service to move their accounts from the old connection to the new connection and prompt them to authenticate. After they authenticate they are good to go.

Best Practice Recommendation 3

If customers don’t do a positive opt in, it’s recommended that you programatically migrate parts of your population to the new connection on a schedule. This will allow you to manage any potential customer support inquiries regarding the change. As an example, you could migrate ¼ of your customer database every 2 weeks until the full migration date. That would give you a 2 month migration path.

If you decide to not migrate your customers before the full migration date be sure to at least be ready to migrate all your customers when we force migrate them over to the new connection at which point you will see all the customer accounts in a 948 aggregation status.