Table of Contents

Overview.. 2

Endpoints. 2

2.1. POST /events. 2

Data Model 2

3.1. Aggregated Polling - Request 2

3.1.1 UML Diagram.. 2

3.1.2 Data Dictionary. 2

3.2. Aggregated Polling - Response. 3

3.2.1 UML Diagram.. 3

3.2.2 Data Dictionary. 3

Usage Example. 4

4.1. Poll Only. 4

4.1.1 POST Events Request 4

4.1.2 POST Event Response. 4

4.2. Acknowledge Only. 4

4.2.1 POST Events Request 4

4.2.2 POST Event Response. 4

4.3. POST and Acknowledge with Errors. 5

4.3.1 POST Events Request 5

4.3.2 POST Events Response. 5

These API Specifications should be read in conjunction with Event Notifications API Profile

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 HTTP/1.1 Authorization: Bearer 7b99f6c331e841dab811176e25d57ca7 Content-Type: application/json x-fapi-interaction-id: 1af4c0e6b5da49f6b1aebf439e87c199 POST Events Request

{
  "returnImmediately": true
}

4.1.2 POST Event `POST /events HTTP/1.1Content-Type: application/jsonx-fapi-interaction-id: 1af4c0e6b5da49f6b1aebf439e87c199` Response

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

4.2. Acknowledge Only

4.2.1 `POST /events HTTP/1.1 Authorization: Bearer 7b99f6c331e841dab811176e25d57ca7Content-Type: application/jsonx-fapi-interaction-id: 295f6c6c7b2045b2a3e91e4f1c31d681 { "maxEvents": 0, "ack": [ "b6a68c1db7fc4c178fd7d8a41b9ef85c" ]}` POST Events Request

4.2.2 POST Event `POST /events HTTP/1.1Content-Type: application/jsonx-fapi-interaction-id: 295f6c6c7b2045b2a3e91e4f1c31d681` Response

{
  "sets": { }
}

4.3. POST and Acknowledge with Errors

4.3.1 `POST /events HTTP/1.1Authorization: Bearer 7b99f6c331e841dab811176e25d57ca7Content-Type: application/jsonx-fapi-interaction-id: 3fc0df586e45404abd5bbf1b23ce343d` POST Events Request

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

4.3.2 `POST /events HTTP/1.1Content-Type: application/jsonx-fapi-interaction-id: 3fc0df586e45404abd5bbf1b23ce343d` POST Events Response

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

Events