Skip to content
Developerhome

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.

Overview

  1. Product initiates linking, calling into Banking Service.
  2. Banking Service sends ‘resource created’ notification to provider.
  3. Banking Service calls the GET /auth endpoint. When Banking Service calls the /auth endpoint, the customer should get a UI to enable them to authorise.
  4. The provider generates UI for authentication.
  5. The provider calls PATCH /authorisations on ProviderAPI, and passes an array of authorised accounts.
  6. The UI redirects to Banking Service.
  7. The customer in product calls the POST /bankaccount endpoint in Banking Service.
  8. Banking Service sends a ‘resource created’ 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. 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

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 APIBanking Service -> Provider

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 APIBanking Service -> Provider

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 parameters 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 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.

POST /oauth/token

Sage IDProvider -> 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/{authorisationId}

Provider APIProvider -> Banking Service

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": "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 APIBanking Service -> Provider

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.


Was this helpful?