Skip to content
Developer home

2. Develop and test

  Less than to read

Develop and test checklist

Technical kick-off call

The technical kick-off call is an an opportunity to ask questions you have at the start of development. The call will include:

  • An introduction to your assigned Enablement engineer.
  • Confirmation of setup requirements.
  • Overview of the data flows need to connect to Banking Service.
  • Overview of API specifications.

This is intended to be a technical session, but we will address any questions you have.

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

Postman supports collections which are a pre-packaged bundle of API requests. To assist in the development and testing of your integration, we have provided three separate Postman collections.

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

Step 3: Import the Postman collection

  1. Unzip the JSON format files from the downloaded ZIP archive.
  2. Open Postman.
  3. From the main menu, select File > Import.
  4. Drag and drop the JSON files into Postman.

Step 4: Import the environment JSON received during registration

The environment JSON we provided in registration contains the details of the sandbox test environment. This includes your client ID and secret. The environment JSON must be imported into Postman to enable the collections to function.

  1. Unzip the JSON format file from the downloaded ZIP archive.
  2. Open Postman.
  3. Select the manage environments option at the top right of the Postman UI.
  4. From the manage environments view, select Import.
  5. Select the choose files option and locate the environment JSON file.
  6. Ensure the new environment is selected once imported.

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

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


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 1: Apply and 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": {}
}

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

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": "bankAccountFromCandidate",
    "url": "https://somethingorother.com"
  },
  "additionalData": {
    "externalId": "13b437a2-e0bb-4d06-8dc1-618ea2b6a723:0b035aef-9e1e-406e-9815-06409757f05e"
  }
}

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

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 1: Apply and set up.

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.