Migration

ℹ️

This guide is relevant for customers of our enduring account connectivity APIs.

Connection modes

Official open banking APIs can be enabled for your app in one of three modes. The connection mode used for each bank is configured independently, allowing for a staggered migration as each bank brings functionality online to support your use case.

Strict mode

In strict mode, only the bank's official open banking connection will be available. This is best suited to a brand new app. Strict mode cannot be enabled for a bank if you already have users using classic connections with that bank.

Migration mode

In migration mode, existing classic connections will continue to function, but users will be unable to set up a new classic connection with that bank. New connections can only be established using the official open banking integration.

By default, this will lead to a passive migration over time, although there is little incentive for users with an existing connection to switch. Depending on the desired pace of migration, Akahu can also:

• Highlight classic connections in our OAuth flow and display a message prompting the user to upgrade them.
• Mention a deadline date in our prompt to the user (optional).
• After the migration deadline has passed and with explicit confirmation from you, deactivate any remaining classic connections (requiring that the user migrates to reactivate), or revoke them entirely.

We expect that you will handle direct communications with your users informing them about the actions required of them and relevant deadlines.

ℹ️

You can determine which connections each of your users are currently using by inspecting the connection parameter of each account item returned from our API.

Developer mode

Developer mode can only be enabled for non-production app configurations and is designed specifically to allow developers to test the migration workflow.

When creating a new connection, developer mode provides a choice between the classic or official version. For existing connections, developer mode will display the same options as migration mode.

This allows you to complete test the migration pathway multiple times by:

1. Creating a new classic connection.
2. Confirming the classic connection and returning to your app.
3. Visiting the Akahu authorisation flow a second time.
4. Following the official connection migration prompts.
5. Completing migration to the official connection and returning to your app.

How migrations work

When your users visit the Akahu OAuth flow and have existing classic connections at a bank that is configured in migration mode, they will be given the option to upgrade that classic connection to use the official open banking connection.

This upgrade requires that the user to completes a new authorisation using the official open banking connection for their bank. During this process they will need to re-select which of their accounts they wish to share with your application.

Once the user has completed the new authorisation, Akahu will:

• Create a new record for each account that the user shares via the new official open banking connection. These account records will each receive a new _id.
• Match each new account with its predecessor and assign a special _migrated parameter to the new account record containing the _id of the account’s predecessor.
• Remove your app’s access to the user’s original account records.

Because the user needs to re-select which bank accounts to share with your app, it is possible that they will (intentionally or inadvertently) select a different subset of accounts to what they had shared previously. This means that it is also possible for new accounts to be added, or existing accounts to be removed during the migration.

An example of this is illustrated in the diagram below, in which the user has originally shared accounts A, B, and C, but during the migration, selected Accounts A, B, and D.

Supporting a seamless migration

Account data

The account migration process is triggered only once the user completes the Akahu OAuth flow and returns to your app.

We recommend that one of the first actions taken by your app after receiving the OAuth redirect (and completing the OAuth code exchange) is to query an up-to-date list of the user’s accounts using our GET /accounts API endpoint. You can then compare the results from this API call with your own records to determine what changes have taken place.

When you observe a new account available at our API, check for the presence of the _migrated attribute. Use the _migrated attribute to identify the account’s predecessor in your records, and update your records (accounts and transactions) with the new account details including its updated _id (account id) and _connection (connection id).

Account webhooks

When a user migrates an account to a new connection, your application will not receive the DELETE and CREATE webhook events that would usually be emitted due to the change in access.

Instead, a single MIGRATE event will be emitted, containing the previous_item_id and new_item_id for the migrated account. If multiple accounts were migrated from a single authorisation, multiple webhook events will be emitted - one for each account.

Transaction data

For each account that is migrated, Akahu will copy a maximum of 1 year's transaction history. Each copied transaction is assigned a new _id and a _migrated field that references the _id of the original transaction it was copied from (i.e. the same process used for account migration).

From this point onwards, Akahu will fetch new transactions for the account using the new, official connection.

This means that if your app requests transactions from our API that occurred prior to the migration event, Akahu will return data that was sourced using the original connection but with new IDs. Transactions that occurred after the migration event are sourced from the new connection. This approach allows Akahu to maintain a reference to the original transaction ID in each transaction's _migrated field¹.

There may be a small overlap period of 1-2 days containing transactions from both the original and new connection. Akahu will attempt to blend these together to ensure a seamless transition. If, during this blended period, we are unable to reconcile a transaction between the original and new connection, churn may occur. Churn results in an existing transaction being deleted and a new one being created to take its place.

While we have made best efforts to ensure consistency of data between classic and official connections, it is possible that there will be some changes in transaction data sourced using official connections. You may notice differences in the date, type, and format of description.

¹If you would prefer to disable the migration of transaction history and instead retrieve an entirely fresh set of transactions for migrated accounts, let us know and we can configure this for your app. All transactions for migrated accounts will be assigned new IDs and will not include the _migrated field. In this case, you will be responsible for reconciling these transactions against any existing data you have stored.

Transaction webhooks

The migration of existing transaction history to the new account will not generate webhook events.

Any transactions fetched using the new connection will result in INITIAL_UPDATE/DEFAULT_UPDATE webhook events as per usual. These events will reference the new account _id in the item_id field of the webhook body. Akahu may begin sending webhook events for new transactions very soon after the account migration event, so it is important that your application responds to the account migration by updating the account IDs in your own system as quickly as possible.

If a deletion occurs for a transaction that has been migrated from the original connection (this will only happen for the 1-2 day merge window mentioned in the previous section), a DELETE webhook event will be sent. This webhook event will include both the transaction's _id and _migrated in the removed_transactions array of the webhook payload. This ensures that your application can correctly identify the correct transaction for deletion regardless of whether your records reference the original transaction ID or the new one.

Hosting your own connection selector

If your app implements its own connection selection UI by passing the connection parameter to the Akahu OAuth flow, there are some changes that you will need to account for when displaying the list of available connections for users to choose from.

When your app has a particular bank enabled in either migration or developer mode, the GET /connections endpoint will return two entries for this bank: one for the classic connection type and the other for the official connection type.

There are some new connection attributes to differentiate between the connection type (link to docs on new connection attributes). It is recommended to use the connection_type attribute to add indicators to your UI that differentiate the classic and dedicated open banking connections (their name and logo will otherwise be identical for a given bank). The new_connections_enabledflag will be set false for classic connections with migration mode enabled. You can use this attribute to hide/disable the connection option in your app.

Example of official connection in strict mode

{
  "_id": "conn_cm4hlog270000914n33hj6tqq",
  "name": "ASB",
  "logo": "https://cdn.akahu.nz/logos/...",
  "connection_type": "official",
  "new_connections_enabled": true,
  "mode": "strict",
}

Example of official connection in migration mode

[
  {
    "_id": "conn_cjgaaozdo000001mrnqmkl1m0",
    "name": "Westpac",
    "logo": "https://cdn.akahu.nz/logos/...",
    "connection_type": "classic",
    "new_connections_enabled": false
  },
  {
    "_id": "conn_cmb01ceg1000008l53yw4a6ez",
    "_classic": "conn_cjgaaozdo000001mrnqmkl1m0"
    "name": "Westpac",
    "logo": "https://cdn.akahu.nz/logos/...",
    "connection_type": "official",
    "new_connections_enabled": true,
    "mode": "migration",
  }
]

Behaviour when connection parameter is provided