Skip to content
Developerhome
Product homepage
Banking Service

Notification

  Less than to read

Connector APIBanking Service -> Provider

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.

POST/notification

Request

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. You will need to store this identifier as it will be used when posting statements.
  • 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. You will need to store this identifier as it will be used when posting statements.
  • 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",
    "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"
  }
}

Response

Your solution should respond with a 200.

Retry policy

We do a retry on the delivery of notifications using a liner back off. This occurs for a period of around 15 minutes.

Should there be downtime longer than this, the following can be used:

  • Bank account IDs for missed BankAccountCreated notifications could be found via the AccountQueries endpoint.
  • Deleted bank accounts could be discovered also via the AccountQueries endpoint returning a status of cancelled.
  • Missed authorisation created notification - This would effectively be a failed onboard and the user would have to try again when the service is available.

Securing this endpoint

With the /notification endpoint we can add a custom headerName and headerValue to the request specifiied by you.

Within this request you will also be passed a Sage ID token under the authorisation header which can be verified using the following endpoint:

  • Sandbox https://id-shadow.sage.com/.well-known/jwks.json
  • Production https://id.sage.com/.well-known/jwks.json

The following is an example of the request headers which would be sent along with this request:

  headers: {
    accept: 'application/json',
    Authorization: 'Bearer **Sage ID Token**',
    'content-type': 'application/json; charset=utf-8',
    YourKeyHeader: 'YourKeyValue'
  }

Was this helpful?