Real Time Notification
1. Version Control
Version | Date | Description of Changes |
Bahrain OBF v1.0.0 | 28th Oct 2020 | Initial Release |
2. Overview
The Real Time Event Notification API Profile describes the flows common functionality for the Real Time Event Notification API, which allows ASPSPs to notify an AISP/ PISP that an event has occurred.
Step: Send Event Notification
When an event occurs on a resource that requires a notification, the ASPSP identifies the callback-url associated with the AISP/ PISP owning the affected resource
The ASPSP sends a signed event notification to the callback URL, detailing the nature of the event and identifying the affected resource
The AISP/ PISP may optionally initiate a client credential grant to retrieve the resource using the details contained in the event notification.
This functionality enables an ASPSP to notify the AISP/ PISP in real time after an event occurs. Upon receipt of this notification, AISPs/ PISPs can notify the user/customer, if required, regarding completion of the event.
The Event Notification resource is used by an ASPSP to notify an AISP/ PISP of an event.
This resource description should be read in conjunction with a compatible Real Time Event Notification Profile.
3. Endpoints
An ASPSP will send event notifications to a AISP/ PISP using the event-notification resource.
S. No. | Resource | HTTP Operation | Endpoint | Mandatory | Scope | Grant Type | Message Signing | Idempotency Key | Request Object | Response Object |
3.1 | event- notification | POST | POST / event- notifications | Mandatory | accounts payments | n/a | No | No | OBEventNotification |
|
Notes:
AISP/ PISP must make available an event notification endpoint to receive event notifications
AISP/ PISP must acknowledge an event notification with a 202 HTTP response and include the provided x-fapi-interaction-id
3.1 POST/event-notifications
The API endpoint allows the ASPSP to send an event-notification resource to an AISP/ PISP.
3.2 Transport Level Security
AISP/ PISP hosted endpoints must be protected using TLS 1.2, as per the FAPI Read/Write specification.
AISP/ PISP hosted endpoints must be protected using a network certificate issued by a Trust Anchor supported by the ASPSP.
MA-TLS is not applicable to AISP/ PISP hosted endpoints.
4. Data Model
4.1 Event Notification - Request
The OBEventNotification object will be used for a call to:
POST /event-notifications
Note, the OBEventNotification object is aligned with the Security Event Token (https://tools.ietf.org/html/rfc8417). It acts as a wrapper for events contained within the events claim.
4.1.1 UML Diagram
4.1.2 Notes
The rid, rty and rlk claims are prefixed with the OB namespace http://openbanking.org.bh in the data model. The namespace has been removed from the diagram for clarity.
4.1.3 Data Dictionary
Name | Occurrence | XPath | Enhanced Definition | Class/ Datatype | Codes | Pattern |
OBEventNotification | OBEventNotification |
|
| OBEventNotification |
|
|
Iss | 1.1 | OBEventNotification/iss | Issuer | String |
|
|
Iat | 1.1 | OBEventNotification/iat | Issued At | Number |
|
|
Jti | 1.1 | OBEventNotification/jti | JWT ID | String |
|
|
Aud | 1.1 | OBEventNotification/aud | Audience | String |
|
|
Sub | 1.1 | OBEventNotification/sub | Subject | String : URI |
|
|
Txn | 1.1 | OBEventNotification/txn | Transaction Identifier | String |
|
|
Toe | 1.1 | OBEventNotification/toe | Time of Event | Number |
|
|
Events | 1.1 | OBEventNotification/events | Events | OBEvent |
|
|
urn:bh:org:openbanking:events:resource-update | 0..1 | OBEventNotification/events/ urn:bh:org:cbb_openbanking:events:resource-update | Resource-Update Event | OBEventResourceUpdate |
|
|
urn:bh:org:openbanking:events:account-access-consent-linked-account-update | 0..1 | OBEventNotification/events/ urn:bh:org:cbb_openbanking:events:account-access-consent-linked-account-update | An event that indicates an account linked to a consent has move in/out of scope of the consent | OBEventAccountAccessConsentLinkedAccountUpdate |
|
|
urn:bh:org:openbanking:events:consent-authorization-revoked | 0..1 | OBEventNotification/events/ urn:bh:org:cbb_openbanking:events:consent-authorization-revoked | An event that indicates a consent resource has had its authorisation revoked | OBEventConsentAuthorizationRevoked |
|
|
4.2 OBEventSubject
This section describes the OBEventSubject class which is used in the OBEventResourceUpdate, OBEventConsentAuthorizationRevoked and OBEventAccountAccessConsentLinkedAccountUpdateclasses.
4.2.1 UML Diagram
4.2.2 Notes
The rid, rty and rlk claims are prefixed with the OB namespace http://openbanking.org.bh in the data model. The namespace has been removed from the diagram for clarity
The array of resource links (http://openbanking.org.bh/rlk) must contain links to all supported versions of the resource
4.2.3 Data Dictionary
Name | Occurrence | XPath | Enhanced Definition | Class/ Datatype | Codes | Pattern |
OBEventSubject |
|
|
| OBEventSubject |
|
|
subject_type | 1..1 | OBEventSubject/subject_type | Subject type for the updated resource | String | http://openbanking.org.bh/rid_http://openbanking.org.bh/rty |
|
http://openbanking.org.bh/rid | 1..1 | OBEventSubject/http://openbanking.org.bh/rid | Resource Id for the updated resource | String |
|
|
http://openbanking.org.bh/rty | 1..1 | OBEventSubject/http://openbanking.org.bh/rty | Resource Type for the updated resource | String |
|
|
http://openbanking.org.bh/rlk | 1..n | OBEventSubject/http://openbanking.org.bh/rlk | Resource links to other available versions of the resource | OBEventSubject/http://openbanking.org.bh/rlk |
|
|
version | 1..1 | OBEventSubject/http://openbanking.org.bh/rlk/version | Resource version | String |
|
|
link | 1..1 | OBEventSubject/http://openbanking.org.bh/rlk/link | Resource link | String |
|
|
4.3 OBEventResourceUpdate
This section describes the OBEventResourceUpdate class which is used in the OBEventNotification resource.
4.3.1 UML Diagram
4.3.2 Notes
The rid, rty and rlk claims are prefixed with the OB namespace http://openbanking.org.bh in the data model. The namespace has been removed from the diagram for clarity
The array of resource links (http://openbanking.org.bh/rlk) must contain links to all supported versions of the resource
4.3.3 Data Dictionary
Name | Occurrence | XPath | Enhanced Definition | Class/ Datatype | Codes | Pattern |
urn:bh:org:openbanking:events:resource-update |
|
| An event that indicates a resource has been updated | OBEventResourceUpdate |
|
|
subject | 1..1 | urn:bh:org:cbb_openbanking:events:resource-update /subject | The subject of the event | OBEventSubject |
|
|
4.4 OBEventConsentAuthorizationRevoked
This section describes the OBEventConsentAuthorizationRevoked class which is used in the OBEventNotification resource.
4.4.1 UML Diagram
4.4.2 Notes
For the OBEventConsentAuthorizationRevoked object:
The subject claim must be populated if the Event Notification does not include a urn:bh:org:cbb_openbanking:events:resource-update event
4.4.3 Data Dictionary
Name | Occurrence | XPath | Enhanced Definition | Class/ Datatype | Codes | Pattern |
urn:bh:org:openbanking:events:consent-authorization-revoked |
|
| An event that indicates a consent resource has had its authorisation revoked | OBEventConsentAuthorizationRevoked |
|
|
reason | 0..1 | urn:bh:org:cbb_openbanking:events:consent-authorization-revoked/reason | Reason for the Consent Authorization Revoked event | String |
|
|
subject | 0..1 | urn:bh:org: cbb_openbanking:events:consent-authorization-revoked/subject | The subject of the event | OBEventSubject |
|
|
4.5 OBEventAccountAccessConsentLinkedAccountUpdate
This section describes the OBEventAccountAccessConsentLinkedAccountUpdate class which is used in the OBEventNotification resource.
4.5.1 UML Diagram
4.5.2 Notes
For the OBEventAccountAccessConsentLinkedAccountUpdate object:
The http://openbanking.org.bh/rty claim must be populated with "account-access-consent"
4.5.3 Data Dictionary
Name | Occurrence | XPath | Enhanced Definition | Class/ Datatype | Codes | Pattern |
urn:bh:org:openbanking:events:account-access-consent-linked-account-update |
|
| An event that indicates an account linked to a consent has move in/out of scope of the consent | OBEventAccountAccessConsentLinkedAccountUpdate |
|
|
reason | 0..1 | urn:bh:org:cbb_openbanking:events:account-access-consent-linked-account-update/reason | Reason for the Account Access Consent Linked Account Update event | String |
|
|
subject | 1..1 | urn:bh:org:cbb_openbanking:events:account-access-consent-linked-account-update/subject | The subject of the event | OBEventSubject |
|
|
4.6 Event Notification Retry Policy
4.6.1 ASPSP
An ASPSP’s Event Notification Retry Policy defines behaviour when an event notification is unacknowledged or the ASPSP receives a 5xx error.
An Event Notification Retry Policy must define an Exponential Backoff Policy to calculate the Retry Time Interval
An Event Notification Retry Policy must define the Maximum Number of Retries an ASPSP will make before declaring the AISP/ PISP Event Notification endpoint unresponsive and ceasing further attempts
An Event Notification Retry Policy must define the Maximum Time Interval for Retries, after which an ASPSP will declare the AISP/ PISP Event Notification endpoint unresponsive and cease further attempts
4.6.2 AISP/ PISP
An AISP/ PISP may make GET requests for its resources if its /event-notifications endpoint was unavailable for the Maximum Time Interval for Retries, as defined in an ASPSP’s Event Notification Retry Policy.
5. Usage Examples
5.1 Send Event Notification - Resource Update
5.1.1 POST Event Notification Request
|
Decoded JWT Body - Event Notification Payload
|
5.1.2 POST Event Notification Response
|
5.2 Send Event Notification - AIS Consent Authorisation Revoked
In case of Account Information Access/Authorization revocation, the state of the Consent resource is not updated. This triggers only one event for the underlying consent resource:
consent-authorization-revoked
5.2.1 POST Event Notification Request
|
Decoded JWT Body - Event Notification Payload
|
5.2.2 POST Event Notification Response
|
5.3 Send Event Notification - AIS Consent Authorisation Revoked
In case of Account Information Access/Authorization revocation, the state of the Consent resource is not updated. This triggers only one event for the underlying consent resource:
consent-authorization-revoked
5.3.1 POST Event Notification Request
|
Decoded JWT Body - Event Notification Payload
|
5.3.2 POST Event Notification Response
|
CENTRAL BANK OF BAHRAIN © 2020