Skip to content
Developerhome
Product homepage
Banking Service

3. Integrate

  Less than to read

Your Postman environment and collections

To see the Provider API in action you can use Postman. Postman is a multi-platform REST client with an intuitive GUI for:

  • Configuring HTTP requests
  • Designing JSON payloads
  • Viewing HTTP responses

A Postman collection is available to illustrate the Banking Service Provider API methods and workflow.

Step 1: Get Postman

Visit the Postman website to Download and install Postman.

Step 2: Get the Postman collections

Run in Postman

Postman supports collections which are a pre-packaged bundles of API requests. To assist in the development and testing of your integration, we have provided the following Postman collection which covers Banking Service’s intergration flows.

This collection contains the following collections:

  • Onboarding
  • Re-authorisation
  • Multi-account linking
  • Retrieve Sage ID token
  • Posting transactions

You can see explanations of the collections, including use cases and flows, in API flows.

Our Using Postman guide will walk you through importing and using our public Postman collection.

Provider flows

To enable a successful integration with Banking Service, it is important to understand the data flows.

There are 5 flows for providers connecting to Banking Service:

  • Authorisation
  • Re-authorisation
  • Multi-account linking
  • Pushing of transactions
  • Disconnect

The flows also include 4 participants:

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

Authorisation

When Banking Service calls the /auth endpoint, the customer should get a UI to enable them to authorise:

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

Flow diagram displaying the authorisation flow

Re-authorisation

When Banking Service calls the /authrefresh endpoint, the customer should get a UI to enable them to re-authorise. This may be in the event of a customer needing consent with the provider:

  1. Product initiates re-authorisation, calling into Banking Service.
  2. Banking Service sends ‘resource created’ notification to Provider.
  3. Banking Service calls the GET /authrefresh endpoint.
  4. The provider generates UI for authentication.
  5. The provider calls PATCH /authorisations on ProviderAPI, passing an empty array.
  6. The UI redirects to Banking Service.
  7. Banking Service changes state of account to active.

Flow diagram displaying the re-authorisation flow

Multi-account linking

When Banking Service calls the /availableAccounts endpoint, a list of all of the available accounts the customer has authorised to connect to Banking Service should be rerturned:

  1. Product initiates linking, calling into Banking Service.
  2. Banking Service calls the GET /availableaccounts endpoint.
  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.

Flow diagram displaying the multi-account linking flow

Pushing of transactions

The statements flow is the standard mechanism for uploading transaction data to the Provider API.

  1. Statements are uploaded individually for each bank account.
  2. While multiple bank accounts can be processed simultaneously, only one statement from each account can be processed at the same time. Providers should loop through all transactions they want to send for a given account. Sending a single batch and then polling for its completion before sending the next.

Flow diagram displaying the transactions flow)

Disconnect

When a customer disconnects in product:

  1. A call is made to Banking Service to initiate deletion of their account in the service.
  2. Banking Service will call the /notification endpoint to let the provider know this account has been disconnected in Banking Service.
  3. The provider can perform any action required for clean up.

Flow diagram displaying the disconnection flow

User flows

These flow diagrams explain what’s happening for the user as they complete these flows.

Authorisation

  1. The first thing the user needs to do is to onboard their accounts.
  2. User selects in product account and starts the onboarding flow.
  3. They search for the bank and selects connect.
  4. Banking Service sends ‘resource created’ notification to provider.
  5. Banking Service calls the provider’s GET /auth endpoint.
  6. The provider generates UI for authentication.
  7. User authorises and gets a list of available accounts. They then select the account they want to link.
  8. The provider calls PATCH /authorisations on Provider API, and passes an array of authorised accounts.
  9. The account information is displayed in the UI.
  10. User selects the date they wish to start receiving transactions from and confirms.
  11. A bank account is created in Banking Service.
  12. The details of the bank account are passed to the user’s product to be stored.
  13. Banking Service sends a ‘resource created’ notification to the provider.

Flow diagram displaying the authorisation user flow

Multi-account linking

  1. 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.
  2. User launches the Multi-account linking flow to get a list of accounts under same authorisation as account created during Authorisation flow.
  3. A request is made to Banking service to get all available accounts under the same authorisation.
  4. Banking service calls the providers GET /availableaccounts endpoint.
  5. The provider returns an array of available accounts under the same authorisation.
  6. This is returned to the user’s product.
  7. User maps in product bank accounts to available accounts.
  8. For each mapped account:
    • A bank account is created in Banking Service.
    • The details of the bank account are passed to the user’s product to be stored.
    • Banking Service sends a ‘resource created’ notification to the provider.

Flow diagram displaying the multi-account linking user flow

Pushing of transactions

  1. Now the user has onboarded a bank account we are ready to start receiving data.
  2. For the initial push of transactions a call would be made to POST /statements with bankaccount UUID for all transactions from start date the user selected.
  3. For subsequent pushes of transactions a call would be made to POST /statements with bankaccount UUID for all transactions since the last push.
  4. The user’s product can then call into Banking Service and get transactions. These are available for the user to post to their Accounting ledgers.

Flow diagram displaying pushing of transactions user flow

Re-authorisation

  1. There may be times when the user authorisation has expired and this needs to be updated.
  2. When authorisation has expired, the provider can invoke the Re-authorisation flow by calling the POST Statements setting account details status to “authRequired”.
  3. Banking Service will then set the bank account to “authRequired”.
  4. When the user’s product next calls in for transactions they will get the current transactions from Banking Service and will be told the account needs to be reauthorised.
  5. An in-product notification is shown to the user to inform which account needs to be updated. The user can then update credentials.
  6. Banking Service sends ‘resource created’ notification to provider.
  7. Banking Service calls the provider’s GET / authrefreshendpoint.
  8. The provider generates UI for authentication.
  9. User authorises.
  10. The provider calls PATCH /authorisations on Provider API, and passes an array of authorised accounts.
  11. The user is advised that the reauthorisation has been successful.

Flow diagram displaying the re-authorisation user flow

Disconnecting

  1. There may be times when a user wishes to disconnect their account. They might not want to use the feed any more, or may have linked their account to the wrong in-product account.
  2. The user can select to disconnect their account in their Sage software.
  3. This send a call to Banking service to delete the account and remove transaction history
  4. Any references to the bank account in-product will be removed. Any transactions which have been downloaded will remain.
  5. Banking Service sends ‘resource deleted’ notification to provider and the provide can carry out any required cleanup.

Flow diagram displaying the disconnect user flow

Implement a connector API

To process the required webhooks provider flows, you need to implement a connector API.

Endpoints

This API is exposed through the endpoints provided in Stage 2: Get set up with the following endpoints:

  • /auth – for generating UI to authenticate a customer account
  • /authrefresh – for generating UI to reauthenticate a customer
  • /notification – for receiving calls when events occur on Banking Service (or Provider API) that require the provider’s attention
  • /availableaccounts – multi-account linking is an optional feature that uses this endpoint. It’s adopted by some Sage products to let users onboard multiple accounts at one time.

Connector API specification

The full specification, including response codes and payloads, is in the Swagger file. Go to the API Reference section for connector API to find out more.

Building this API against the provided endpoints allows you to test the flows in the sandbox environment using the Postman collections. Download the Postman collections here.

Notifications

Notifications are sent to providers when events occur on Banking Service (or Provider API) that require the provider’s attention. For example, when the authorisation flow completes, a notification is sent to the provider to state that a bank account has been created.

Notifications will always contain “type”. This defines what the purpose of the notification is; and a resource with nested information about the resource involved in the event.

AuthorisationCreated

This is triggered when a customer starts the authorisation flow to create a bank account in Banking Service. This notification prepares the provider for a UI redirect to its GET /auth endpoint.

This notification is also sent in the re-authorisation flow, but just to notify the provider of the incoming POST /authrefresh call.

  • resource.id: The identifier of the authorisation. When GET /auth is called, this same authorisationId will be passed; this allows the provider to ensure that the request is valid.
{
    "type": "resourceCreated",
    "resource": {
        "id": "a7d66d27-e9ab-40b4-850a-447a541ca263",
        "type": "authorisation",
        "url": "NA"
    },
    "additionalData": {
      "bankId": "10aaeee6-4691-4443-8198-df39aaa8007c"
    }
}

BankAccountCreated

This is triggered in the authorisation flow, in response to the POST /bankaccounts endpoint being called into Banking Service.

  • 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 PATCH /authorisations call.
{
  "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"
  }
}

BankAccountFromCandidate

This is triggered in the multi-account linking flow, in response to the POST /bankaccounts endpoint being called into Banking Service.

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

BankAccountDeleted

This is triggered in the disconnect flow, in response to the DELETE /bankaccount/{bankAccountId} endpoint being called in Banking Service, or when a bank account is removed for other reasons.

resource.id: The identifier of the bankAccount resource being deleted additionalData.externalId: The externalId that was provided to Banking Service by the provider in the PATCH /authorisations call

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

Using Provider API

Provider API is API used for pushing transactions to Banking Service.

Provider API statements - reference data

The transactionNarrative field provides the consuming application with a single field to hold all the reference data that can be shown on the in-product transactions.

These fields are always linked in the same order. Empty fields are removed and the data in each remaining field is separated by a single space.

  • narrative1
  • narrative2
  • description
  • referenceNumber
  • payee.payeeDescription
  • checkNumber

If you map multiple fields with the same value, the in-product transaction may have duplicate information.

Provider API specification

The full specification, including response codes and payloads, is in the Swagger file. Go to the API reference section for Provider API.

Engineering support

Your team will be able to communicate with our engineers for support. The channels for contacting our engineers was agreed in Stage 2: Setup.

It is important that you get in touch with us if you have any issues during development such as:

  • Issues accessing sandbox
  • Documentation issues
  • Updates to endpoints or provider names
  • Delays to agreed go-live dates
  • Knowledge support for provider flows and API specifications

Next steps

Find out what you need to do for your integration to go live after you’ve completed your internal testing.

Was this helpful?