1. Overview

The Event Subscription resource is used by an AISP/PISP to subscribe to events with an ASPSP.

This resource description should be read in conjunction with a compatible Event Notification Subscription Profile.

2. Endpoints

An AISP/ PISP will set up and maintain its event subscription details (URL, event types and version number) using the event-subscription resource.

S. No.	Resource	HTTP Operation	Endpoint	Mandatory	Scope	Grant Type	Message Signing	Idempotency Key	Request Object	Response Object
2.1	event-subscription	POST	POST /event-subscriptions	Optional	accounts payments	Client Credentials	Signed Request Signed Response	No	OBEventSubscription	OBEventSubscriptionResponse
2.2	event-subscription	GET	GET /event-subscriptions	Mandatory (if resource POST implemented)	accounts payments	Client Credentials	Signed Response	No	n/a	OBEventSubscriptionsResponse
2.3	event-subscription	PUT	PUT /event-subscriptions/{EventSubscriptionId}	Conditional (See Note 1)	accounts payments	Client Credentials	Signed Request Signed Response	No	OBEventSubscriptionResponse	OBEventSubscriptionResponse
2.4	event-subscription	DELETE	DELETE /event-subscriptions/{EventSubscriptionId}	Conditional (See Note 1)	accounts payments	Client Credentials	n/a	No	n/a	n/a

Note 1

Implementation for an ASPSP is:

Mandatory, when the above is not true and ASPSP implemented POST /event-subscriptions

2.1 POST /event-subscriptions

The API endpoint allows the AISP/ PISP to ask an ASPSP to create a new event-subscription resource.

The POST action allows the AISP/ PISP to register an event subscription for an AISP/ PISP to access event notifications.
The ASPSP creates the event-subscription resource and responds with a unique EventSubscriptionId to refer to the resource.
An ASPSP must respond with a 409 error if an event-subscription exists for that AISP/ PISP.

2.2 GET /event-subscriptions

The API endpoint allows the AISP/ PISP to ask an ASPSP to retrieve its event-subscription resource.

The ASPSP retrieves the event-subscription resource and responds with the resource.

2.3 PUT /event-subscriptions/{EventSubscriptionId}

The API endpoint allows the AISP/ PISP to ask an ASPSP to update an event-subscription resource.

The PUT action allows the AISP/ PISP to update an event subscription for an AISP/ PISP to access event notifications.
The ASPSP updates the event-subscription resource and responds with the updated resource

2.4 DELETE /event-subscriptions/{EventSubscriptionId}

The API endpoint allows the AISP/ PISP to ask an ASPSP to delete an event-subscription resource.

The ASPSP deletes the event-subscription resource.

3. Data Model

3.1 Event Subscription - Request

The OBEventSubscription object will be used for the call to:

POST /event-subscriptions

3.1.1 UML Diagram

3.1.2 Notes

For the OBEventSubscription object:

AISP/ PISP must not provide CallbackUrl, when subscribing for Aggregated Polling only
AISP/ PISP must provide the Version of Resources, for which they want to subscribe the events for. E.g. if supplied with value "3.1", AISP/ PISP indicates the subscription for the change in state of resources created in v3.1 version
EventTypes usage:
- AISPs/ PISPs may provide a list of event types to subscribe to specific events.
- AISPs/ PISPs may omit this field to subscribe to all supported events

3.1.3 Data Dictionary

Name	Occurrence	XPath	Definition	Class/ Datatype	Codes	Pattern
OBEventSubscription		OBEventSubscription		OBEventSubscription
Data	1..1	OBEventSubscription/Data		OBEventSubscription/Data
CallbackUrl	0..1	OBEventSubscription/Data/CallbackUrl	Callback URL for an AISP/ PISP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to	String:URI
Version	1..1	OBEventSubscription/Data/Version	Version for the event notification.	String
EventTypes	0..n	OBEventSubscription/Data/EventTypes	Array of event types the subscription applies to	Array:String

3.2 Event Subscription - Response

The OBEventSubscriptionResponse object will be used for a response to a call to:

POST /event-subscriptions
PUT /event-subscriptions/{EventSubscriptionId}

The OBEventSubscriptionResponse object will also be used for the call to:

PUT /event-subscriptions

3.2.1 UML Diagram

3.2.2 Data Dictionary

Name	Occurrence	XPath	Definition	Class/ Datatype	Codes	Pattern
OBEventSubscriptionResponse		OBEventSubscriptionResponse		OBEventSubscriptionResponse
Data	1..1	OBEventSubscriptionResponse/Data		OBEventSubscriptionResponse/Data
EventSubscriptionId	1..1	OBEventSubscriptionResponse/Data/EventSubscriptionId	Unique identification as assigned by the ASPSP to uniquely identify the callback URL resource.	String
CallbackUrl	0..1	OBEventSubscriptionResponse/Data/CallbackUrl	Callback URL for an AISP/ PISP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to	String:URI
Version	1..1	OBEventSubscriptionResponse/Data/Version	Version for the event notification.	String
EventTypes	0..n	OBEventSubscriptionResponse/Data/EventTypes	Array of event types the subscription applies to	Array:String

3.3 Event Subscriptions - Response

The OBEventSubscriptionsResponse object will be used for a response to a call to:

GET /event-subscriptions

3.3.1 UML Diagram

3.3.2 Data Dictionary

Name	Occurrence	XPath	Definition	Class/ Datatype	Codes	Pattern
OBEventSubscriptionsResponse		OBEventSubscriptionsResponse		OBEventSubscriptionsResponse
Data	1..1	OBEventSubscriptionsResponse/Data		OBEventSubscriptionsResponse/Data
EventSubscription	0..n	OBEventSubscriptionsResponse/Data/EventSubscription		OBEventSubscriptionsResponse/Data/EventSubscription
EventSubscriptionId	1..1	OBEventSubscriptionsResponse/Data/EventSubscription/EventSubscriptionId	Unique identification as assigned by the ASPSP to uniquely identify the callback url resource.	String
Url	0..1	OBEventSubscriptionsResponse/Data/EventSubscription/Url	Callback URL for an AISP/ PISP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to.	String:URI
Version	1..1	OBEventSubscriptionsResponse/Data/EventSubscription/Version	Version for the event notification.	String
EventTypes	0..n	OBEventSubscriptionsResponse/Data/EventSubscription/EventTypes	Array of event types the subscription applies to.	Array:String

4. Swagger Code

The swagger code for the Event Subscription API can be found on this link.

5. Usage Example

5.1 Create Event Subscription

5.1.1 POST Event Subscription Request

POST /event-subscriptions

Authorization: Bearer 4ZopnFZFKjr5zDsicSQpLL

x-jws-signature: LMlmPSqzISEpar72ce5deMGue4RsZMDnZYG1bW6hdPlvriZ=..G1rrM18vVYBmdmRurS6nIR1yFHR8bGZyIJdvaB5nKGRvm35hTr==

x-fapi-interaction-id: 75bdc714-b2dg-7676-c759-780d6815689f

Content-Type: application/json

Accept: application/json

{ "Data": { "CallbackUrl": "https://AISP/ PISP.com/open-banking/event-notifications", "Version": "2.2" } }

5.1.2 POST Event Subscription Response

201 Created

x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K

x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865

Content-Type: application/json

{ "Data": { "EventSubscriptionId": "CB-101", "CallbackUrl": "https://AISP/ PISP.com/open-banking/event-notifications", "Version": "2.2" }, "Links": { "Self": "www.tbc.com" }, "Meta": {} }

5.2 GET Event Subscriptions

5.2.1 GET Event Subscription Request

GET /event-subscriptions

Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865

Accept: application/json

5.2.2 GET Event Subscription Response

200 OK

x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K

x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865

Content-Type: application/json

{ "Data": { "EventSubscription": [{ "EventSubscriptionId": "CB-101", "CallbackUrl": "https://AISP/ PISP.com/open-banking/event-notifications", "Version": "2.2" }] }, "Links": { "Self": "www.tbc.com" }, "Meta": {} }