Multi-account linking

Many users of Banking Service will only have a handful of bank accounts they want to integrate with their software. However, we know there are users with upwards of 100 accounts per financial institution and the existing (single account) flow means onboarding each of these 1 by 1 is time-consuming.

This walkthrough covers how we can use the multi-account linking flow to link additional accounts to an existing BankConnection. This means you don’t need to repeat the single account flow multiple times. A user may choose to use multi account link to authorise further accounts any time after their inital onboarding. This guide walks through the API calls made to and from the Banking Service from your application and the consuming product. It demonstrates the multi-account linking flow detailed in our Postman collection.

Overview

1. Product initiates linking, calling into Banking Service.
2. Banking Service calls the GET /availableaccounts endpoint. When Banking Service calls the providers /availableAccounts endpoint, a list of all of the available accounts the customer has authorised to connect to Banking Service should be rerturned.
3. Banking Service returns the array of authorised, but unlinked, accounts to the product UI.
4. The customer in product calls the POST /bankaccount endpoint in Banking Service.
5. Banking Service sends a ‘resource created’ (bankaccounts from candidate) notification to the provider.

API flow diagram

1. Initiate multi-account linking

Depending on the user’s product, they may support the ability to link all accounts under a single authorisation, this is called multi-account linking.

The user can initate this multi-account link flow from the consuming Sage product. This informs the Banking Service to get all available accounts under the same authorisation as the account created during the single account flow. Banking Service then sends a request the provider’s GET /availableaccounts endpoint through the connector API.

[
    {
        "accountType": "string",
        "accountName": "string",
        "externalId": "string",
        "bankIdentifier": "e9316993-a44f-49a7-b891-2374c77ce5a4",
        "accountIdentifier": "4de7d7a7-b222-4024-96b5-95b20d350b77",
        "branchIdentifier": "string"
    },
    {
        "accountType": "string",
        "accountName": "string",
        "externalId": "string",
        "bankIdentifier": "a4676993-a44f-49a7-b891-2374c77ce5a4",
        "accountIdentifier": "7vh6d3a2-b222-4024-96b5-95b20d350b77",
        "branchIdentifier": "string"
    }
]

Description of the fields:

• accountType: (string) is the type of account; ‘business’, ‘savings’, ‘loan’, ‘creditCard’, ‘corporate’ or ‘personal’.
• accountName: (string) The bank account name that is to be displayed to the customer. Can use account name + masked account number to help customers identify.
• externalId: (string) The provider’s own unique identifier for the bank account.
• bankIdentifier: (string) The real-world bank identifier for the specific bank. Banking Service recommends this to be an identifier that represents the customers credentials.
• accountIdentifier: (string) The real-world account number for the bank account. Usually this isn’t the account number but a unique identifier held by the provider.
• branchIdentifier: (string) The real-world branch identifier for the bank account. If you do not wish to use please populate with the string ‘n/a’.

2. User links the required accounts

The user can use in-product functionality to map their bank accounts to the available accounts returned by the provider. For each mapped account:

• A bank account is created in Banking Service.
• The details of this bank account are passed to the user’s product to be stored.
• Banking Service sends a ‘resource created’ notification to the provider.

{
  "type": "resourceCreated",
  "resource": {
    "id": "36aed119-675f-4507-9da3-06a5914d95ee",
    "type": "bankAccountFromCandidate",
    "url": "https://somethingorother.com"
  },
  "additionalData": {
    "externalId": "13b437a2-e0bb-4d06-8dc1-618ea2b6a723:0b035aef-9e1e-406e-9815-06409757f05e",
    "requestedStartDate": "2021-06-29T11:05:29Z",
    "bankId": "10aaeee6-4691-4443-8198-df39aaa8007c"
  }
}

Description of the fields:

• resource.type – For linking an account with the multi-account linking flow, the type will be bankAccountFromCandidate.
• resource.id – The identifier of the newly created bankAccount resource.
• additionalData.externalId – The externalId that was provided to Banking Service by the provider in the /authorisations PATCH call.
• requestedStartDate – The start date which the user has requested to start recieving transactions from.

Test multi-account linking

FAQs

Guides

Recap

This walkthrough has covered the Banking Service flow for linking multiple accounts to a single authorisation.

We have shown how you initiate this flow from the consuming product, which trigger Banking Service to call the provider’s GET /availableaccounts endpoint to retrieve a list of accounts.

We have also covered how the provider is notified through the POST /notifications endpoint when a new account has been linked.

What’s next?

Discover how to push transactions into Banking Service.