Skip to content
Developer home


  Less than to read

Before you can retrieve transactions through a provider, you need to complete the onboarding process. This process is carried out from the consuming product, where you can create an organisation and company, and link bank accounts which are available through the providing service.

This walkthrough covers the API calls made to and from Banking Service from your application and consuming product to demonstrate the various flows detailed in our Postman collection.

Read our API flow overview before following this walkthrough. This covers any prerequisites and how to use our Postman collections.

API flow diagram

Flow diagram displaying the authorisation flow

1. Create an organisation

An organisation represents a customer’s portfolio of resources. As the route resource, other resources (Company, BankAccount) are linked to the organisation and cannot be linked to any other organisation.

To be able to access a Service Fabric service such as Banking Service, you need an organisation and company. When a user chooses to access one of these services the consuming product will make sure they are created.

2. Get an access token

At this point a JSON Web Token (JWT) will be obtained to securely access this new organisation and complete additional steps. This is done through GET AccessToken request.

JWT is an open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. A JWT must be used for all flows.

Learn more about JWT >

3. Get a bank account

The consuming product can get detailed information regarding a provider’s bank through the GET /bank endpoint by passing the bank identifier parameter.

The user searches for the bank they would like to connect with. If the user selects a bank that is indirect (dataProvider value on the bank will be ‘indirect’) the product will initiate the authorisation by calling GET /indirectlinkaccount.

POST /notification

Connector API

This notifies the provider that an authorisation has started by sending a POST request to the providers /notification endpoint with the following payload:

    "type": "resourceCreated",
    "resource": {
        "id": "a7d66d27-e9ab-40b4-850a-447a541ca263",
        "type": "authorisation",
        "url": "NA"
    "additionalData": {
      "bankId": "10aaeee6-4691-4443-8198-df39aaa8007c"

GET /auth

Connector API

The Banking Service calls into the provider’s GET /Auth endpoint. The provider should then perform any neccessary tasks to authenticate the user. They may ask the user to enter their internet banking credentials and perform multi-factor authentication.

The following query paramters are sent within the auth request:

Query Parameter Description
bankaccount The sage id of the bank that the user of the Sage Banking service has chosen to on-board with.
authorisation_id UUID of the authorisation session within the Sage Banking Service. Following an authorisation this ID is used in conjunction with Patch Auth to inform the Banking Service of authorised accounts. It can be used to optionally validate against the authorisation id received on the web hook notification.
redirect_uri Url to redirect to upon success or failure. The value of the State query parameter should be appended to this when redirecting.
state uuid to be appended to redirect_uri when redirecting.
externalId The providers unique identifier for the bank account.

POST /oauth/token

Sage ID

Using the provider API to complete requests such as PATCH authorisations, requires a Sage ID bearer token and an API key to authenitcate the call.

An API key will be provided to you by the Sage team through the setup proccess. To Generate a Sage ID bearer token you can make a POST request to the token endpoint as detailed below. This token generally lasts 480 minutes but should be refreshed when receiving a 401 Unauthenticated responses from the API.

This request should be sent with the following body:

Body Params Description
grant_type This should be set as client_credentails.
client_id This value identifies your client, and is tied to your provider; only tokens generated with your clientId can access resources associated with your provider.
client_Secret This value is required in order to generate SageId tokens. It should be handled as a secret and not shared.
audience This value identifies the Provider API and ensures that generated SageId tokens are targeted at the correct API.

These resources (keys) will be supplied by the Sage team.

PATCH /authorisations

Provider API

The provider will inform Banking Service of the results of the onboarding session of this bank account. In the case of onboarding the collection of all accounts which access is granted are to be provided. Banking Service then takes responsibility for determining which account the onboarding session is for.

This is an example of the payload which should be provided:

  "data": {
    "status": "success",
            "bankAccountExternalId": "string1234",
            "accountName": "string",
            "bankIdentifier": "1234",
            "branchIdentifier": "string",
            "accountIdentifier": "13425"
            "bankAccountExternalId": "string4321",
            "accountName": "string",
            "bankIdentifier": "4321",
            "branchIdentifier": "string",
            "accountIdentifier": "14253"

Description of the fields:

  • bankAccountExternalId: (string) The provider’s own unique identifier for the bank account.
  • 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.
  • bankIdentifier: (string) The real-world bank identifier for the specific bank. Banking service recommends this to be an identifier that represents the customers credentials.
  • 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’.
  • 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.

When this Patch has been called, the provider should then redirect back to the banking service UI. The redirect URI to be used is available as a query paramater within the GET /auth call previously made by the banking service UI to the provider.

The consuming product can then poll the Banking Service for confirmation that the account has been authorised by the provider. This is done through the /indirectlinkaccountprogress endpoint. This also provides the consuming application with information about the account that was selected by the customer.

6. Create a company bank account

A bank account is created agaisnt the user’s company through a POST request to /bankaccounts.

This bank account is a representation of a customer’s account held with their bank. It can hold account information such as:

  • Account number
  • Sort code
  • Balance information
  • Authorisation tokens (depending on the Bank and region)

A BankAccount can only be used in 1 organisation, but can be linked to multiple companies within it.

POST /notification

Connector API

After the consuming product has created this bank account, the provider will be notified by the Banking Service sending a POST request to the provider’s /notification endpoint with the following payload:

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

Note: Make sure you store this resource ID which is the bank account ID to be used when pushing transactions into Banking Service.


This walkthrough has covered the Banking Service flow for onboarding. Showing how the consuming Sage product triggers calls to the provider, to authorise the user through the Banking Service.

Next steps

Allow users to re-authorise with your application, through the re-authorisation flow.