Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 7 Next »

1.  Overview

The Event Subscription resource is used by a TPP to subscribe to events with an ASPSP.

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

2.  Endpoints

A TPP 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
fundsconfirmations

Client Credentials

Signed Request

Signed Response

No

OBEventSubscription

OBEventSubscriptionResponse

2.2

event-subscription

GET

GET /event-subscriptions

Mandatory (if resource POST implemented)

accounts
payments
fundsconfirmations

Client Credentials

Signed Response

No

n/a

OBEventSubscriptionsResponse

2.3

event-subscription

PUT

PUT /event-subscriptions/{EventSubscriptionId}

Conditional (See Note 1)

accounts
payments
fundsconfirmations

Client Credentials

Signed Request

Signed Response

No

OBEventSubscriptionResponse

OBEventSubscriptionResponse

2.4

event-subscription

DELETE

DELETE /event-subscriptions/{EventSubscriptionId}

Conditional (See Note 1)

accounts
payments
fundsconfirmations

Client Credentials

n/a

No

n/a

n/a

 Note 1

Implementation for an ASPSP is:

  • Optional, where both the following are true:

    • The ASPSP supports aggregated polling only

    • The ASPSP only supports a single event type for aggregated polling

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

2.1 POST /event-subscriptions

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

  • The POST action allows the TPP to register an event subscription for a TPP 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 TPP.

2.2 GET /event-subscriptions

The API endpoint allows the TPP 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 TPP to ask an ASPSP to update an event-subscription resource.

  • The PUT action allows the TPP to update an event subscription for a TPP 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 TPP 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:

  • TPP must not provide CallbackUrl, when subscribing for Aggregated Polling only

  • TPP must provide the Version of Resources, for which they want to subscribe the events for. E.g. if supplied with value "3.1", TPP indicates the subscription for the change in state of resources created in v3.1 version

  • EventTypes usage:

    • TPPs may provide a list of event types to subscribe to specific events.

    • TPPs 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 a TPP 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 a TPP 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 a TPP 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.  Usage Example

4.1 Create Event Subscription

4.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://tpp.com/open-banking/event-notifications",            "Version": "2.2"   } }

4.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://tpp.com/open-banking/event-notifications",            "Version": "2.2"   },   "Links": {           "Self": "www.tbc.com"   },   "Meta": {} }

4.2 GET Event Subscriptions

4.2.1 GET Event Subscription Request

GET /event-subscriptions

Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

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

Accept: application/json

4.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://tpp.com/open-banking/event-notifications",                       "Version": "2.2"                       }]   },   "Links": {             "Self": "www.tbc.com"           },   "Meta": {} }

 

  • No labels