Event Notification API

Event Notification API V3.1.8

Introduction

This API specification describes the flows and common functionality to allow a TPP to receive event notifications.

As per OB, usage of the Event Notification Subscription API is recommended over the Callback URL API for notification registration. For polling implementation of real-time push Notifications is optional.

Therefore BOI API Platform’s implementation of the Event Notification API profile v3.1.8 will support below APIs:

• The Event Notification Subscription API which allow TPPs to register to receive the events.
• Aggregated Polling API which allow TPPs to poll for subscribed events.

Functional Overview

Event Notification flow with examples:

Step 1: Set up Client Credentials Token

To request for Event Notification Subscription and Aggregated Polling, the Access Token must be obtained by the TPP using a Client Credentials grant type within a secure, server side context between the TPP and the ASPSP.

The access tokens required for accessing these APIs must have one of the following scope: accounts, fundsconfirmations, payments.

When an Access Token expires, the TPP should request another Access Token using the request payload.

For the API endpoints we are using Open Banking Directory Sandbox certificates. You need to trust Open Banking Directory Sandbox certificates while calling our APIs.

Example:

POST Request: client credentials grant type token endpoint

curl -k -X POST \
--key ./{network.key} \
--cert ./{network.pem} \
 https://api-sandbox.bankofireland.com/oauth/as/token.oauth2 \
-H 'accept: application/json' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=payments&client_id=1OEwYAKIgMtefvOKfSEdAS'

Request parameters:

Parameter	Example value	Description
grant_type	client_credentials	The grant type being requested.
scope	Accounts, Fundsconfirmations,Payments	Generic scope

POST response: client credentials grant type token endpoint

{
    "access_token": "VS6VAWqqfI2sKOh4iuwgEgPPgduw",
    "token_type": "Bearer",
    "expires_in": 299
}

Step 2: Setup Event Notification Subscription

This flow begins with a TPP creating an event-subscription resource with an ASPSP using below endpoint:

POST /event-subscriptions:

The API endpoint allows the TPP to ask an ASPSP to create a new event-subscription resource. On invocation of this API, the API Platform creates the event-subscription resource and responds with a unique EventSubscriptionId.

Step 3: Event is produced

An event corresponding to one of an ASPSP's event types occurs on a resource when the customer revokes the TPP access for the given consents from the ASPSP access dashboards.

Step 4: TPP Requests Event Notifications

A TPP requests event notifications using Aggregated Polling, which allows a ASPSPs to deliver multiple signed event notifications to TPPs though the use of polling using below endpoint:

POST /events:

This API endpoint allows the TPP to poll for events to which TPP have a subscription. The aggregated set of events are delivered as part of the API response. Each event in the set is represented as a JWS with its JTI as its identifier.

The message signing process used for creating JWS uses the same signing key as used for signing API response of existing APIs.

• Step I: Initial Polling

This is the first time a TPP calls the ASPSP to poll for events:

1. A TPP calls an ASPSP to poll for events.
2. The ASPSP responds with an array of awaiting events encoded as signed event notifications.

Awaiting events are the events that have not been delivered to the TPP.

• Step II-A: Acknowledge Only

Following the initial poll the TPP has the option to only acknowledge receipt if they do not wish to receive further events at a given time:

1. A TPP calls an ASPSP to acknowledge the event notifications that have been successfully processed.
2. If required, the TPP also sends indicators of event notifications which they could not process due to an error.
3. The ASPSP responds positively but sends no further events.

• Step II-B: Poll and Acknowledge

Following the initial poll the TPP can then repeatedly poll the ASPSP, acknowledging successfully processed event notifications and requesting more:

1. A TPP calls an ASPSP to acknowledge the event notifications that have been successfully processed with appropriate parameters to receive more.
2. If required, the TPP also sends event notifications which they could not process due to an error.
3. The ASPSP responds positively and responds with an array of awaiting event notifications encoded as signed event notifications.

Step 5: Retrieve/Delete Event Notification Subscription

A TPP may Retrieve/Delete the event notification subscription resource using below endpoints:

GET /event-subscriptions:

The API endpoint allows the TPP to ask an ASPSP to retrieve its event-subscription resource. The API Platform retrieves the event-subscription resource and responds with the resource.

DELETE /event-subscriptions:

The API allows the TPP to delete the event subscription resource that they have created earlier.

Examples of the above API endpoints can be viewed [here].

For more details on Open Banking's initiative and API specifications:

https://openbankinguk.github.io/read-write-api-site3/v3.1.8/profiles/]

Versioning

This API Specification conforms to Open Banking UK Event Notification API Specification – v3.1.8

Additional information and limitations has been provided in the ‘Important Information’ page