Skip to content
Developer home

Onboarding

  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
bank The Sage ID of the bank that the user of the Sage Banking Service has chosen to onboard 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 webhook 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

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",
    "bankAccounts": {
      "bankAccountExternalId": "string",
      "accountName": "string",
      "bankIdentifier": "string",
      "branchIdentifier": "string",
      "accountIdentifier": "string"
    }
  }
}

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": "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"
  }
}
:

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


Recap

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.