Onboarding

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 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. A bank account is created within banking service with a status of ‘pending’.
9. The bank identifier is sent back to the consuming product to be stored.
10. Banking Service sends a ‘resource created’ notification to the provider.

API flow diagram

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 Sage Network Platform 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.

4. Initiate an indirect account link

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.

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

{
  "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 customer’s credentials.
• branchIdentifier: (string) The real-world branch identifier for the bank account. If you do not wish to use, populate with the string ‘n/a’.
• accountIdentifier: (string) The real-world account number for the bank account. Usually this is not 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 in the GET /auth call previously made by the Banking Service UI to the provider. The redirect should be appended with a state query parameter which equals which equals the Authorisation ID. For example, ‘{redirectUrl}?state=${authorisationId}’.

5. Poll the indirect link account

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

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

Test onboarding

Recap

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

What’s next?

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