| Table of Contents | ||||
|---|---|---|---|---|
|
1. Version Control
Version | Date | Description of Changes |
Bahrain OBF v1.0.0 | 25th Aug 2020 | Initial Release |
...
2. Overview
The Event Notification subscription API Profile describes the flows and common functionality to allow an AISP/ PISP to:
Register an event subscription with an ASPSP to subscribe to event notifications.
A subscription can enable real time event notifications via an HTTP callback from the ASPSP, and aggregated polling by the AISP/PISP.
Specify a list of event types to be notified on.
Optionally read, update or delete a registered event subscription.
AISPs / PISPs can receive all or specific event types via the Real Time Event Notification API and/or the Aggregated Polling API.
...
The following APIs have been elaborated below:
Real-Time Notification: ASPSP shares the notifications with the AISP/ PISP real time, as soon as the event occurs
...
Aggregated Polling (Pull Notifications): ASPSP shares the notifications to AISPs/ PISPs in an aggregated set, upon request
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.
...
3. 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 |
23.1 | event-subscription | POST | POST /event-subscriptions | Optional | accounts | Client Credentials | Signed Request | No | OBEventSubscription | OBEventSubscriptionResponse |
23.2 | event-subscription | GET | GET /event-subscriptions | Mandatory (if resource POST implemented) | accounts | Client Credentials | Signed Response | No | n/a | OBEventSubscriptionsResponse |
23.3 | event-subscription | PUT | PUT /event-subscriptions/{EventSubscriptionId} | Conditional | accounts | Client Credentials | Signed Request Signed Response | No | OBEventSubscriptionResponse | OBEventSubscriptionResponse |
23.4 | event-subscription | DELETE | DELETE /event-subscriptions/{EventSubscriptionId} | Conditional | accounts | Client Credentials | n/a | No | n/a | n/a |
...
3.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.
...
3.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.
...
3.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
...
3.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.
...
4. Data Model
...
4.1 Event Subscription - Request
The OBEventSubscription object will be used for the call to:
POST /event-subscriptions
...
4.1.1 UML Diagram
...
...
4.1.2 Notes
For the OBEventSubscription object:
...
o AISPs/ PISPs may provide a list of event types to subscribe to specific events.
o AISPs/ PISPs may omit this field to subscribe to all supported events
...
4.1.3 Data Dictionary
Name | Occurrence | XPath | Enhanced 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 | Enum:
|
|
...
4.2 Event Subscription - Response
The OBEventSubscriptionResponse object will be used for a response to a call to:
...
The OBEventSubscriptionResponse object will also be used for the call to:
PUT /event-subscriptions
...
4.2.1 UML Diagram
...
...
4.2.2 Data Dictionary
Name | Occurrence | XPath | Enhanced 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 | Enum:
|
|
...
4.3 Event Subscriptions - Response
The OBEventSubscriptionsResponse object will be used for a response to a call to:
GET /event-subscriptions
...
4.3.1 UML Diagram
...
...
4.3.2 Data Dictionary
Name | Occurrence | XPath | Enhanced 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 | Enum:
|
|
...
5. Usage Example
...
5.1 Create Event Subscription
...
5.1.1 POST Event Subscription Request
|
|
...
5.1.2 POST Event Subscription Response
|
|
...
5.2 GET Event Subscriptions
...
5.2.1 GET Event Subscription Request
|
...
5.2.2 GET Event Subscription Response
|
...