1. Overview

The Events resource is used by a TPP to retrieve multiple signed event notifications from an ASPSP.

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

2. Endpoints

_{S. No.}	_Resource	_{HTTP Operation}	_Endpoint	_Mandatory	_Scope	_{Grant Type}	_{Message Signing}	_{Idempotency Key}	_{Request Object}	_{Response Object}
_2.1	_events	_POST	_{POST /events}	_Optional	_{accounts fundsconfirmations}	_{Client Credentials}	_N/A	_No	_{OBEventPolling}	_{OBEventPollingResponse}

2.1 POST /events

The endpoint allows a TPP to poll for and acknowledge and receive event notifications.

The POST method allows the TPP to transmit their polling parameters and event notification acknowledgements.
The ASPSP responds accordingly, sending event notifications as indicated by the TPPs polling parameters

3. Data Model

3.1 Aggregated Polling - Request

The OBEventPolling will be used as the request payload for:

POST /events.

3.1.1 UML Diagram

3.1.2 Data Dictionary

_Name	_Occurrence	_XPath	_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 TPP}	_Array:String
_setErrs	_0..1	_{OBEventPolling/setErrs}	_{An object that encapsulates all negative acknowledgements transmitted by the TPP}	_{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

3.2 Aggregated Polling - Response

The OBEventPollingResponse will be used as the response payload for:

POST /events.

3.2.1 UML Diagram

3.2.2 Data Dictionary

_Name	_Occurrence	_XPath	_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>}

4. Usage Example

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

4.1 Poll Only

4.1.1 POST Events Request

POST /events HTTP/1.1

Authorization: Bearer 7b99f6c331e841dab811176e25d57ca7

Content-Type: application/json

x-fapi-interaction-id: 1af4c0e6b5da49f6b1aebf439e87c199

{ "returnImmediately": true }

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

4.2 Acknowledge Only

4.2.1 POST Events Request

POST /events HTTP/1.1

Authorization: Bearer 7b99f6c331e841dab811176e25d57ca7

Content-Type: application/json

x-fapi-interaction-id: 1af4c0e6b5da49f6b1aebf439e87c199

4.2.2 POST Event Response

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

{ "sets": { } }

4.3 POST and Acknowledge with Errors

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

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