1. Version Control

Version	Date	Description of Changes
Bahrain OBF v1.0.0	28th Oct 2020	Initial Release

2. Overview

Aggregated Polling is about the provision of notification of revocations from ASPSPs to AISPs/ PISPs, upon AISP/ PISP request, enabling AISPs/ PISPs to update their records and contact the users/customers, if required, at the point in time of the request. However, the key difference is that rather than focusing on a specific consent resource’s status (via a GET request on that specific resource), aggregated polling allows an AISP/ PISP to request an aggregated set of events from multiple users/customers during a specific period.

This functionality makes much more efficient usage of the ASPSPs and AISPs/ PISPs network bandwidth as multiple single polls, especially with no change of access status, are avoided.

Moreover, it allows AISPs/ PISPs to receive all the required notifications without the need to implement systems with high availability (e.g. systems running 24x7) or systems based on real time push notifications, providing full flexibility to AISPs/ PISPs about the timing they want to receive the notifications based on their business models. AISPs/ PISPs are able to notify users/customers immediately after they poll ASPSPs, if required.

Step 1: Initial Polling

This is the first time an AISP/ PISP calls the ASPSP to poll for events:

An AISP/ PISP calls an ASPSP to poll for events
The ASPSP responds with an array of awaiting events encoded as signed event notifications

Awaiting events are the events that have not been acknowledgement by the AISP/ PISP, or have been reported as errors by the AISP/ PISP.

Step 2a: Acknowledge Only

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

An AISP/ PISP calls an ASPSP to acknowledge the event notifications that have been successfully processed
If required, the AISP/ PISP also sends indicators of event notifications which they could not process due to an error
The ASPSP responds positively but sends no further events

Step 2b: Poll and Acknowledge

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

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

Acknowledgment by the AISP/ PISP

Recipients of event notifications must acknowledge them. This is manifested in one of two ways:

Through positive acknowledgement in that the event notification has been received and successfully processed
Through negative acknowledgement where the event notification has been received but the AISP/ PISP encountered an error in processing

ASPSPs can evict positively acknowledged event notifications from their stores. It is implicit that AISPs/ PISPs are responsible for retaining a record of event notifications appropriate to their needs once positively acknowledged.

The Events resource is used by an AISP/ PISP to retrieve multiple signed event notifications from an ASPSP.

This resource description should be read in conjunction with a compatible Aggregated Polling Profile.

3. Endpoints

S. No.	Resource	HTTP Operation	Endpoint	Mandatory	Scope	Grant Type	Message Signing	Idempotency Key	Request Object	Response Object
3.1	events	POST	POST /events	Mandatory	accounts payments	Client Credentials	N/A	No	OBEventPolling	OBEventPollingResponse

3.1 POST /events

The endpoint allows an AISP/ PISP to poll for and acknowledge and receive event notifications.

The POST method allows the AISP/ PISP to transmit their polling parameters and event notification acknowledgments
The ASPSP responds accordingly, sending event notifications as indicated by the AISPs/ PISPs polling parameter

4. Data Model

4.1 Aggregated Polling - Request

The OBEventPolling will be used as the request payload for:

POST /events

4.1.1 UML Diagram

4.1.2 Data Dictionary

Name	Occurrence	XPath	Enhanced Definition	Class/ Datatype	Codes	Pattern
OBEventPolling		OBEventPolling		OBEventPolling
maxEvents	0..1	OBEventPolling/maxEvents	Maximum number of events to be returned. A value of zero indicates the ASPSP should not return events even if available	Integer
returnImmediately	0..1	OBEventPolling/returnImmediately	Indicates whether an ASPSP should return a response immediately or provide a long poll	Boolean
ack	0..n	OBEventPolling/ack	An array of `jti` values indicating event notifications positively acknowledged by the AISP/ PISP	Array:String
setErrs	0..1	OBEventPolling/setErrs	An object that encapsulates all negative acknowledgements transmitted by the AISP/ PISP	OBEventPolling/setErrs
<jti>	0..n	OBEventPolling/setErrs/<jti>	A event notification error object entitled using the jti of the event notification	OBEventPolling/setErrs/<jti>
err	1..1	OBEventPolling/setErrs/<jti>/err	A value from the IANA "Security Event Token Delivery Error Codes" registry that identifies the error as defined here	String
description	1..1	OBEventPolling/setErrs/<jti>/description	A human-readable string that provides additional diagnostic information	String

4.2 Aggregated Polling - Response

The OBEventPollingResponse will be used as the response payload for:

POST /events

4.2.1 UML Diagram

4.2.2 Data Dictionary

Name	Occurrence	XPath	Enhanced Definition	Class/ Datatype	Codes	Pattern
OBEventPollingResponse	1..1	OBEventPollingResponse		OBEventPollingResponse
moreAvailable	1..1	OBEventPollingResponse/moreAvailable	A JSON boolean value that indicates if more unacknowledged event notifications are available to be returned	Boolean
sets	1..1	OBEventPollingResponse/sets	A JSON object that contains zero or more nested JSON attributes. If there are no outstanding event notifications to be transmitted, the JSON object SHALL be empty	OBEventPollingResponse/sets
<jti>	0..n	OBEventPollingResponse/sets/<jti>	An object named with the jti of the event notification to be delivered. The value is the event notification, expressed as a string. The payload of the event should be defined in the OBEventNotification format	OBEventPollingResponse/sets/<jti>

5. Usage Example

Note for the sake of readability the SETs shown in examples are shorted.

5.1 Poll Only

5.1.1 POST Events Request

POST /events HTTP/1.1

Authorization: Bearer 7b99f6c331e841dab811176e25d57ca7

Content-Type: application/json

x-fapi-interaction-id: 1af4c0e6b5da49f6b1aebf439e87c199

{ "returnImmediately": true }

5.1.2 POST Event Response

POST /events HTTP/1.1 Content-Type: application/json x-fapi-interaction-id: 1af4c0e6b5da49f6b1aebf439e87c199

{ "sets": { "b6a68c1db7fc4c178fd7d8a41b9ef85c": "eyJhbG...NEysZ4", "2644f8cbc8294325ad103ddfc4a5b15d": "eyJhbG...Qssw5c", "1fd954d5fb964afb97deee232bb88d1f": "eyJhbG...9kogfI" }, "moreAvailable": false }

5.2 Acknowledge Only

5.2.1 POST Events Request

POST /events HTTP/1.1 Authorization: Bearer 7b99f6c331e841dab811176e25d57ca7 Content-Type: application/json x-fapi-interaction-id: 295f6c6c7b2045b2a3e91e4f1c31d681 { "maxEvents": 0,

"ack": [ "b6a68c1db7fc4c178fd7d8a41b9ef85c" ]

}

5.2.2 POST Event Response

POST /events HTTP/1.1 Content-Type: application/json x-fapi-interaction-id: 295f6c6c7b2045b2a3e91e4f1c31d681

{ "sets": { } }

5.3 POST and Acknowledge with Errors

5.3.1 POST Events Request

POST /events HTTP/1.1 Authorization: Bearer 7b99f6c331e841dab811176e25d57ca7 Content-Type: application/json x-fapi-interaction-id: 3fc0df586e45404abd5bbf1b23ce343d

{ "returnImmediately": true, "maxEvents": 1, "ack": [ "2644f8cbc8294325ad103ddfc4a5b15d" ], "setErrs": { "1fd954d5fb964afb97deee232bb88d1f": { "err": "jwtIss", "description": "Issuer is invalid or could not be verified" } } }

5.3.2 POST Events Response

POST /events HTTP/1.1 Content-Type: application/json x-fapi-interaction-id: 3fc0df586e45404abd5bbf1b23ce343d

{ "sets": { "25fd4432da4e4e609033a733aea68a54": "eyJhbG...8o8PLY" }, "moreAvailable": true }