Version | Date | Author | Comments |
---|---|---|---|
3.0 | OB R/W API Team | Swagger URLs updated to point to latest stable version. | |
3.1-draft1 | OB R/W API Team | This is the initial draft version for 3.1 Errata: Typos and grammar fixes. Removed duplicate ASPSP Swagger specification section. | |
3.1-draft2 | OB R/W API Team | Draft2 Changes:
| |
3.1-draft3 | OB R/W API Team | Draft3 Changes
| |
3.1-draft4 | OB R/W API Team | Draft4 Changes
| |
3.1-RC1 | OB R/W API Team | RC1 Changes
| |
3.1 | OB R/W API Team | Version 3.1 final release. No changes from Version 3.1 RC1. Updated swagger links to latest release candidate. |
The Event Notification API Specification describes the flows and payloads to allow ASPSPs to deliver event notifications to TPPs.
The ASPSP API endpoints described here allow a TPP to:
The TPP API endpoint described here allow an ASPSP to:
This specification should be read in conjunction with the Payments, Accounts, and Confirmation of Funds API specifications. These specifications detail the circumstances under which an event notification may be delivered.
Implementation of the Event Notification API Specification is optional for both ASPSPs and TPPs.
Event notifications are aligned with the Security Event Token standard, a proposed IETF standard for exchanging information about security events. See https://tools.ietf.org/html/rfc8417. An event notification is structured as a JWT, indicating an event has occurred through a set of claims.
A resource-update event (rurn:uk:org:openbanking:events:resource-update) is used to communicate that a specific resource has been updated. It contains identifiers for the resource and links to retrieve it.
Event Notifications are singed for non-repudiation using the approach defined in the R/W API specification, with the following difference:
The steps and sequence diagram below provide a general outline of a notification flow for all resources in the R/W APIs.
Step 1: Setup Event Notification Configuration
Step 2: Event Notification Required
Step 3: Retrieve/Update/Delete Event Notification Configuration
participant TPP participant ASPSP Authorisation Server participant ASPSP Resource Server participant ASPSP Notification Service note over TPP, ASPSP Notification Service Step 1: Setup Event Notification Configuration end note TPP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA TPP -> ASPSP Authorisation Server: Initiate Client Credentials Grant ASPSP Authorisation Server -> TPP: access-token TPP <-> ASPSP Resource Server: Establish TLS 1.2 MA TPP -> ASPSP Resource Server: POST /callback-urls ASPSP Resource Server -> TPP: HTTP 201 (Created), CallbackUrlId note over TPP, ASPSP Notification Service Step 2: Event Notification Required end note note left of ASPSP Notification Service - Create EventNotification - Sign EventNotification end note loop Retry Until Successful (as per retry policy) ASPSP Notification Service -> TPP: POST /event-notifications, EventNotification, signature alt success TPP -> ASPSP Notification Service: HTTP 202 Accepted else failure TPP -> ASPSP Notification Service: HTTP 500/400 end alt end loop note right of TPP TPP verifies signature URL for resource contained in the EventNotification rlk (resource links) claim end note TPP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA TPP -> ASPSP Authorisation Server: Initiate Client Credentials Grant ASPSP Authorisation Server -> TPP: access-token TPP <-> ASPSP Resource Server: Establish TLS 1.2 MA TPP -> ASPSP Resource Server: GET Resource ASPSP Resource Server -> TPP: HTTP 200 (OK), Resource note over TPP, ASPSP Notification Service Step 3: Retrieve/Update/Delete Event Notification Configuration end note TPP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA TPP -> ASPSP Authorisation Server: Initiate Client Credentials Grant ASPSP Authorisation Server -> TPP: access-token TPP <-> ASPSP Resource Server: Establish TLS 1.2 MA alt Retrive TPP -> ASPSP Resource Server: GET /callback-urls ASPSP Resource Server -> TPP: HTTP 200 (OK) else Update TPP -> ASPSP Resource Server: PUT /callback-urls/{CallbackUrlId} ASPSP Resource Server -> TPP: HTTP 200 (OK) else Delete TPP -> ASPSP Resource Server: DELETE /callback-urls/{CallbackUrlId} ASPSP Resource Server -> TPP: HTTP 204 (OK) end alt option footer=bar |
TPPs must register a callback URL for TPP hosted services to receive event notifications from an ASPSP. The callback URL must end with the Event Notification API specification version number, followed by ‘/event-notifications'.
For example:
This section overviews the release management and versioning strategy for the Event Notification API.
TPPs must register for event-notification callbacks with the version of Event Notification API they have implemented. The version element of the Callback-URL resource is used for this purpose.
An ASPSP will maintain at most, a single Callback-URL resource per TPP.
TPP hosted endpoints must be protected using TLS 1.2, as per the FAPI R/W specification (details here http://openid.net/specs/openid-financial-api-part-2-ID1.html#tls-considerations).
TPP hosted endpoints must be protected using an OB issued network certificate.
MA-TLS is not applicable to TPP hosted endpoints.
A TPP will set up and maintain its call back details (URL and version number) using the callback-url resource.
Resource | HTTP Operation | Endpoint | Mandatory ? | Scope | Grant Type | Message Signing | Idempotency Key | Request Object | Response Object |
---|---|---|---|---|---|---|---|---|---|
callback-url | POST | POST /callback-urls | Optional | accounts payments fundsconfirmations | Client Credentials | Signed Request Signed Response | No | OBCallbackUrl1 | OBCallbackUrlResponse1 |
callback-url | GET | GET /callback-urls | Mandatory (if resource POST implemented) | accounts payments fundsconfirmations | Client Credentials | Signed Response | No | n/a | OBCallbackUrlsResponse1 |
callback-url | PUT | PUT /callback-urls/{CallbackUrlId} | Mandatory (if resource POST implemented) | accounts payments fundsconfirmations | Client Credentials | Signed Request Signed Response | No | OBCallbackUrlResponse1 | OBCallbackUrlResponse1 |
callback-url | DELETE | DELETE /callback-urls/{CallbackUrlId} | Mandatory (if resource POST implemented) | accounts payments fundsconfirmations | Client Credentials | n/a | No | n/a | n/a |
POST /callback-urls |
The API endpoint allows the TPP to ask an ASPSP to create a new callback-url resource.
GET /callback-urls |
The API endpoint allows the TPP to ask an ASPSP to retrieve its callback-url resource.
PUT /callback-urls/{CallbackUrlId} |
The API endpoint allows the TPP to ask an ASPSP to update a callback-url resource.
DELETE /callback-urls/{CallbackUrlId} |
The API endpoint allows the TPP to ask an ASPSP to delete a callback-url resource.
The OBCallbackurl1 object will be used for the call to:
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBCallbackUrl1 | OBCallbackUrl1 | OBCallbackUrl1 | ||||
Data | 1..1 | OBCallbackUrl1/Data | OBCallbackUrlData1 | |||
Url | 1..1 | OBCallbackUrl1/Data/Url | Callback URL for a TPP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to. | xs:anyURI | ||
Version | 1..1 | OBCallbackUrl1/Data/Version | Version for the event notification. | Max10Text |
The OBCallbackUrlResponse1 object will be used for a response to a call to:
The OBCallbackUrlResponse1 object will also be used for the call to:
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBCallbackUrlResponse1 | OBCallbackUrlResponse1 | OBCallbackUrlResponse1 | ||||
Data | 1..1 | OBCallbackUrlResponse1/Data | OBCallbackUrlResponseData1 | |||
CallbackUrlId | 1..1 | OBCallbackUrlResponse1/Data/CallbackUrlId | Unique identification as assigned by the ASPSP to uniquely identify the callback URL resource. | Max40Text | ||
Url | 1..1 | OBCallbackUrlResponse1/Data/Url | Callback URL for a TPP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to. | xs:anyURI | ||
Version | 1..1 | OBCallbackUrlResponse1/Data/Version | Version for the event notification. | Max10Text |
The OBCallbackUrlsResponse1 object will be used for a response to a call to:
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBCallbackUrlsResponse1 | OBCallbackUrlsResponse1 | OBCallbackUrlsResponse1 | ||||
Data | 1..1 | OBCallbackUrlsResponse1/Data | OBCallbackUrlsResponseData1 | |||
CallbackUrl | 0..n | OBCallbackUrlsResponse1/Data/CallbackUrl | OBCallbackUrlResponseData1 | |||
CallbackUrlId | 1..1 | OBCallbackUrlsResponse1/Data/CallbackUrl/CallbackUrlId | Unique identification as assigned by the ASPSP to uniquely identify the callback url resource. | Max40Text | ||
Url | 1..1 | OBCallbackUrlsResponse1/Data/CallbackUrl/Url | Callback URL for a TPP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to. | xs:anyURI | ||
Version | 1..1 | OBCallbackUrlsResponse1/Data/CallbackUrl/Version | Version for the event notification. | Max10Text |
POST /callback-urls
POST /callback-urls HTTP/1.1 Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA x-jws-signature: TGlmZSdzIGEgam91cm5leSBub3QgYSBkZXN0aW5hdGlvbiA=..T2ggZ29vZCBldmVuaW5nIG1yIHR5bGVyIGdvaW5nIGRvd24gPw== x-fapi-financial-id: OB/2017/001 x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865 Content-Type: application/json Accept: application/json { "Data": { "Url": "https://tpp.com/open-banking/v3.1/event-notifications", "Version": "3.1" } } |
POST /callback-urls response
HTTP/1.1 201 Created x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865 Content-Type: application/json { "Data": { "CallbackUrlId": "CB-101", "Url": "https://tpp.com/open-banking/v3.1/event-notifications", "Version": "3.1" }, "Links": { "Self": "https://api.alphabank.com/open-banking/v3.1/callback-urls/CB-101" }, "Meta": {} } |
GET /callback-urls
GET /callback-urls HTTP/1.1 Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA x-fapi-financial-id: OB/2017/001 x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865 Accept: application/json |
GET /callback-urls response
GET/1.1 200 OK x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865 Content-Type: application/json { "Data": { "CallbackUrl": [{ "CallbackUrlId": "CB-101", "Url": "https://tpp.com/open-banking/v3.1/event-notifications", "Version": "3.1" }] }, "Links": { "Self": "https://api.alphabank.com/open-banking/v3.1/callback-urls/" }, "Meta": {} } |
The Swagger Specification for Event Notification ASPSP APIs can be downloaded from the following links:
An ASPSP will send event notifications to a TPP using the event-notification resource.
Resource | HTTP Operation | Endpoint | Mandatory ? | Scope | Grant Type | Message Signing | Idempotency Key | Request Object | Response Object |
---|---|---|---|---|---|---|---|---|---|
event-notification | POST | POST /event-notifications | Optional | n/a | n/a | Signed Request | No | OBEventNotification1 |
Notes:
x-fapi-interaction-id
.POST /event-notifications |
The API endpoint allows the ASPSP to send an event-notification resource to a TPP.
The OBEventNotification1 object will be used for a call to:
The OBEventNotification1 object is aligned with the Security Event Token (https://tools.ietf.org/html/rfc8417). It contains a single OBEventResourceUpdate1 event object within the events claim.
The rid
, rty
and rlk
claims are prefixed with the OB namespace http://openbanking.org.uk in the data model. The namespace has been removed from the diagram for clarity.
For the OBEventNotification1 object:
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBEventNotification1 | OBEventNotification1 | The resource-update event. | OBEventNotification1 | |||
iss | 1..1 | OBEventNotification1/iss | Issuer. | xs:anyURI | ||
iat | 1..1 | OBEventNotification1/iat | Issued At (Unix timestamp). | xs:int | ||
jti | 1..1 | OBEventNotification1/jti | JWT ID. | Max128Text | ||
aud | 1..1 | OBEventNotification1/aud | Audience. | Max128Text | ||
sub | 1..1 | OBEventNotification1/sub | Subject. | xs:anyURI | ||
txn | 1..1 | OBEventNotification1/txn | Transaction Identifier. | Max128Text | ||
toe | 1..1 | OBEventNotification1/toe | Time of Event (Unix timestamp). | xs:int | ||
events | 1..1 | OBEventNotification1/events | Events. | OBEvent1 | ||
urn:uk:org:openbanking:events:resource-update | 1..1 | OBEventNotification1/events/urn:uk:org:openbanking:events:resource-update | Resource-Update Event. | OBEventResourceUpdate1 | ||
subject | 1..1 | OBEventNotification1/events/urn:uk:org:openbanking:events:resource-update/subject | The resource-update event. | OBEventSubject1 | ||
subject_type | 1..1 | OBEventNotification1/events/urn:uk:org:openbanking:events:resource-update/subject/subject_type | Subject type for the updated resource. | Max128Text | http://openbanking.org.uk/rid_http://openbanking.org.uk/rty | |
http://openbanking.org.uk/rid | 1..1 | OBEventNotification1/events/urn:uk:org:openbanking:events:resource-update/subject/http://openbanking.org.uk/rid | Resource Id for the updated resource. | Max128Text | ||
http://openbanking.org.uk/rty | 1..1 | OBEventNotification1/events/urn:uk:org:openbanking:events:resource-update/subject/http://openbanking.org.uk/rty | Resource Type for the updated resource. | Max128Text | ||
http://openbanking.org.uk/rlk | 1..n | OBEventNotification1/events/urn:uk:org:openbanking:events:resource-update/subject/http://openbanking.org.uk/rlk | Resource links to other available versions of the resource. | OBEventLink1 | ||
version | 1..1 | OBEventNotification1/events/urn:uk:org:openbanking:events:resource-update/subject/http://openbanking.org.uk/rlk/version | Resource version. | Max10Text | ||
link | 1..1 | OBEventNotification1/events/urn:uk:org:openbanking:events:resource-update/subject/http://openbanking.org.uk/rlk/link | Resource link. | xs:anyURI |
An ASPSP's Event Notification Retry Policy defines behaviour when an event notification is unacknowledged or the ASPSP receives a 5xx error.
A TPP 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.
POST /event-notifications
POST /event-notifications HTTP/1.1 x-fapi-financial-id: OB/2018/002 x-fapi-interaction-id: 14ba1762-a316-4a87-8d6e-5bfbefaf01d7 Content-Type: application/jwt eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGViYW5rLmNvbS8iLCJpYXQiOiIxNTE2MjM5MDIyIiwianRpIjoiYjQ2MGEwN2MtNDk2Mi00M2QxLTg1ZWUtOWRjMTBmYmI4ZjZjIiwic3ViIjoiaHR0cHM6Ly9leGFtcGxlYmFuay5jb20vYXBpL29wZW4tYmFua2luZy92My4wL3Bpc3AvZG9tZXN0aWMtcGF5bWVudHMvcG10LTcyOTAtMDAzIiwiYXVkIjoiN3VteDVuVFIzMzgxMVF5UWZpIiwiZXZlbnRzIjp7InVybjp1azpvcmc6b3BlbmJhbmtpbmc6ZXZlbnRzOnJlc291cmNlLXVwZGF0ZSI6eyJzdWJqZWN0Ijp7InN1YmplY3RfdHlwZSI6Imh0dHA6Ly9vcGVuYmFua2luZy5vcmcudWsvcmlkX2h0dHA6Ly9vcGVuYmFua2luZy5vcmcudWsvcnR5IiwiaHR0cDovL29wZW5iYW5raW5nLm9yZy51ay9yaWQiOiJwbXQtNzI5MC0wMDMiLCJodHRwOi8vb3BlbmJhbmtpbmcub3JnLnVrL3J0eSI6ImRvbWVzdGljLXBheW1lbnQiLCJodHRwOi8vb3BlbmJhbmtpbmcub3JnLnVrL3JsayI6W3sidmVyc2lvbiI6InYzLjAiLCJsaW5rIjoiaHR0cHM6Ly9leGFtcGxlYmFuay5jb20vYXBpL29wZW4tYmFua2luZy92My4wL3Bpc3AvZG9tZXN0aWMtcGF5bWVudHMvcG10LTcyOTAtMDAzIn0seyJ2ZXJzaW9uIjoidjEuMSIsImxpbmsiOiJodHRwczovL2V4YW1wbGViYW5rLmNvbS9hcGkvb3Blbi1iYW5raW5nL3YxLjEvcGF5bWVudHMvcG10LTcyOTAtMDAzIn1dfX19LCJ0eG4iOiJkZmM1MTYyOC0zNDc5LTRiODEtYWQ2MC0yMTBiNDNkMDIzMDYiLCJ0b2UiOiIxNTE2MjM5MDIyIn0.-coUJsJVycbZufiWHi71TIQsCjP4gj9uZ4FOsNEysZ4 |
{ "iss": "https://examplebank.com/", "iat": 1516239022, "jti": "b460a07c-4962-43d1-85ee-9dc10fbb8f6c", "sub": "https://examplebank.com/api/open-banking/v3.1/pisp/domestic-payments/pmt-7290-003", "aud": "7umx5nTR33811QyQfi", "events": { "urn:uk:org:openbanking:events:resource-update": { "subject": { "subject_type": "http://openbanking.org.uk/rid_http://openbanking.org.uk/rty", "http://openbanking.org.uk/rid": "pmt-7290-003", "http://openbanking.org.uk/rty": "domestic-payment", "http://openbanking.org.uk/rlk": [ { "version": "v3.1", "link": "https://examplebank.com/api/open-banking/v3.1/pisp/domestic-payments/pmt-7290-003" }, { "version": "v1.1", "link": "https://examplebank.com/api/open-banking/v1.1/payment-submissions/pmt-7290-003" } ] } } }, "txn": "dfc51628-3479-4b81-ad60-210b43d02306", "toe": 1516239022 } |
POST /event-notifications response
HTTP/1.1 202 Accepted x-fapi-interaction-id: 14ba1762-a316-4a87-8d6e-5bfbefaf01d7 |