Skip to content
Developerhome

Multi-account linking

  Less than to read

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

Flow diagram displaying the authorisation flow

Participant description
  • Product The Sage product which is currently integrated with Banking Service UI using Consumer API.
  • UI The user interface which allows the Sage user to search for a bank and allows them to authenticate.
  • Banking Service Banking Service handles the calls from the consuming API which Sage products use to interact with Banking Service. Also handling the provider API which handles the connection from any 3rd party provider.
  • Sage ID Sage ID is used to secure all requests into the provider API. You will use Sage ID to obtain your access token.
  • Provider This refers to the 3rd party who is integrating with Banking Service. This 3rd party connector will need to contain the connector API endpoints to be able to handle the Banking Service flows and recieve data.

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.

:

Note: Before a user can benefit from the multi-account flow, they must onboard at least 1 account for the same financial institution using the single account flow. This is required as they still need to authenticate with the institution and grant any necessary consents.

GET /availableaccounts

Connector APIBanking Service -> Provider

When Banking Service calls this endpoint they will pass a single externalId in the query parameters:

GET /availableaccounts?externalId=X

The externalId is a unique value you specify for each of the user’s accounts. You provide Banking Service this identifer in the PATCH /authorisations call when a user goes through onboarding. You should use this externalId to return an array of available accounts under the same authorisation. These are then returned to the consuming product for the user to onboard.

Example of response:

[
    {
        "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’.

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.

POST /notification

Connector APIBanking Service -> Provider

For each linked bank account, Banking Service sends a resource created notification to the provider. This is done through a POST request to the provider’s /notification endpoint with the following payload:

{
  "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

Test description Expected outcome
A customer needs to be able to onboard a single account and then call to see other available accounts. After onboarding a single account, the consuming product should be able to call the GET /availablebankaccounts endpoint to retrieve their other available accounts.

FAQs

When will a customer use the muti-account link flow?
A customer may choose to use the multi account link funtionality that is offered within a Sage product at any point after their first account has been onboarded. Multi account link does not have to occur straight after an onboard.

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.


Was this helpful?