Event Notification

---

Getting started

Welcome to our Open Banking API Sandbox! It enables you to explore all aspects of our Open Banking solution from registering your app, to authorising consent and calling protected APIs.

The Event Notification API allows a TPP to receive event notifications about a change in a resource. The current implementation of Event Notification API can be viewed as two sub-sets of APIs:

• Event Notification Subscription API. It allows TPPs to register an event subscription with HSBC to subscribe to event notifications.
• Agregated Polling API. It allows HSBC to deliver multiple signed event notifications to TPP though the use of polling.

This section will take you through a step by step guide to help you start using Event Notification API as quickly as possible. In the following chapters you will learn how to:

• Register on the portal
• Create a new project
• Create & Authorise Accout Information consent
• Create an Event Subscription
• Trigger an Event
• Poll & Acknowledge Events

Step 1 - Register on the Portal

Before you can access our sandbox you must first register for HSBC UK Open Banking and activate your account on https://develop.hsbc.com using the email provided after you complete our registration steps. You will now be able to access Dev Hub where you will need to create a project.

 

Step 2 - Create a Project in Dev Hub

Creating a project simulates the registration step you will have to complete in the Open Banking live ecosystem, or in other words it facilitates the dynamic client registration (DCR) process on your behalf. This will register your app in the sandbox and generate your sandbox security credentials.

Once you’ve registered your app, you’ll be able to experiment with our resource APIs including redirection to consent authorisation journeys. Beware, that sandbox data is not real customer data, but rather test profiles.

The Dev Hub is the central location to manage all your sandbox projects. The link can be found in the top right corner of the screen.

Pre-requisite: You’ve registered an account on https://develop.hsbc.com

This section will take you through the steps involved in creating a project:

 

Start a new project

On the Dev Hub landing page, click on the red ‘Create Project’ button.

Create Project Step 1 of 4.** Name your project

On the project information page, enter a name and a short description for your project in the fields provided, then click ‘Continue’.

Create Project Step 2 of 4.** Generate test certificates

Our sandbox only accepts certificates issued by the sandbox. You will need to upload your Certificate Signing Request (CSR) and after clicking ‘Continue’ your sandbox Transport Certificate and Signing Certificate will be generated. You will be able to download them both from the next page as well as the project details page once you’ve completed project creation.

If you don’t have a CSR yet, you can follow the instructions provided to generate a private key and CSR.

Please note, in order to simplify the project creation process, both sandbox certificates will be generated from the same CSR. However, in production ecosystem you’ll require two CSRs: one for Transport Certificate and one for Signing Certificate.

Create Project Step 3 of 4.** Generate software statement

On the Generate software statement page, you will have to fill in the form with details of your client:

• Application name - a short name of your app, something that would be recognized by customers.
• Application description - a short description of what your app represents.
• Version - the version of your application.
• Client URL - the URL of your business (or application's) website.
• Redirect URLs - this is the callback URL which will be used to push the consent authorisation result back to your systems. If you have more than one URLs, then each one of them must be declared on a new line.
• Policy URI - the URL to the Policy of your application.
• Terms of Service URI - the URL to the Terms of Service of your application.
• Logo URI - the URL to the Logo of your application.
• Software roles - the role of your client which defines the access rights policy per API. Please consult our FAQ for more information on software roles.

Once you filled in the form, click ‘Continue’.

Please note, at this point the project has not been created yet and the software statement is valid only for 1 hour. If you don’t complete the next step before software statement expires the project will not be created and you’ll have to start the process again. This will also happen if you’re timed out due to inactivity or sign out from the portal before completing the next step.

Create Project Step 4 of 4.** Sandbox (Dynamic) Client Registration

This is the final step when the actual project is being created and an API client is generated for your sandbox app. Simply enter your auth method, click 'Complete' and wait for your project (including oauth client) details to be displayed.

Congrats, your project has been created and you've got everything you need to access our sandbox APIs.

Please note, this step performs the Dynamic Client Registration (DCR) on your behalf in sandbox only. Once you've decided to go live, you will be required to complete the DCR in the production ecosystem.

Also, in order to simplify access to the sandbox, registering your app once will enable you to access sandbox APIs for all applicable brands depending on what you have registered for. However, in our production environment you’ll be required to register your app separately for each brand you want to integrate with.

 

Step 3 - Using our Sandbox

Create & Authorise Account Information Consent

Because Event Notification works in conjunction with other API profiles and Account Information is one of them, here we will build our Event Notification example using Account Information resource.

To create and authorise an Account Information consent please follow the Sandbox Access Guide for your channel of interest.

Request `Access Token` (client_credentials)

To request an access token of grant type 'client_credentials' please follow the Sandbox Access Guide of Account Information API for your channel of interest.

Create Event Subscription

An Event Subscription is needed before one can pull for Events. Here is a cURL command example how to create an Event Subscription:

@POST/event_subscription_curl

A successful response will look like:

@POST/event_subscription_response

NOTE: The 'Authorisation' header is using a 'client_credentials' grant type access token. Please consult the Account Information / Sandbox Access Guide for your channel of interest on how to request this access token.

Trigger Event

In order to simulate creation of an event triggered by a customer when revoking a consent via the Open Banking dashboard in their online banking app, we have built a specialised helper endpoint. Note, this endpoint is not pat of the Event Notification API and is available only in Sandbox.

@DELETE/revoke_consent_curl

NOTE: the access token used in this request should be obtained by means of grant type 'authorisation_code' or 'refresh_token'. In other words, one should use the access token obtained during consent authorisation flow.

By calling this endpoint, an event of type 'consent-authorization-revoked' will be created. Details of this event can be retrieved by using the Agregated Polling API.

Poll for Events

Finally, using the access token of grant type client_credentials, you can poll for existing events. The steps below provide a general way of aggregated polling of events.

Step 1: Initial Polling - typicaly this would be the first time a TPP should poll for events. HSBC will respond with an array of awaiting events encoded as signed event notifications> An awaiting event is the event that has not been acknowledged by TPP, or has been reported as error by TPP.

@POST/initial_poll_curl

A successful response will look like:

@POST/initial_poll_response

Notice, each event from the response is a Signed JWT (JWS) which should be signature verified and processed accordingly when received by TPP. This particular example contains 3 events in the response.

Step 2a: Poll and Acknowledge - following the initial poll the TPP can repeatedly poll for more events and at the same time acknowledge successfully processed events or the ones for which processing has ended with an error at TPP side. Notice, acknowledging a successfully processed event, will stop it being returned in the next poll.

@POST/poll_acknowledge_curl

A successful response will look like:

@POST/poll_acknowledge_response

Note, the response may not contain events if more are not available. This particular example tells there are more awaiting events available.

Step 2b: Acknowledge Only - alternatively, the TPP has the option to only acknowledge the receipt of events without receiving further events.

@POST/acknowledge_only_curl

A successful response will look like:

@POST/acknowledge_only_response

Postman Collection

As an alternative to above CURL command examples, we have prepared an out of the box working postman collection for you available to download:

• Sandbox - UK - Postman Collection

Please note, before you can continue make sure:

• You have read Step 1 and registered yourself on the portal.
• You have read Step 2 and created a project in Dev Hub.
• You have read Step 3 to have a basic understanding about the API flow.

Now you can import the downloaded API & Environment Variables collections into your Postman. Once imported, you have to setup a number of environment variables before you can run the API. Please follow the Sandbox Access Guide of Account Information API for the channel of interest.

Now you can execute the API in the following order:

1. Create & Authorise Account Information Consent.
2. Get Client Credentials Token.
3. Create Event Subscription.
4. Trigger Event.
5. Poll for Events.

Return to top

 

 

================

WORK IN PROGRESS

================

 

 

Summary

Event Notification / polling is a mechanism for the bank server to create a notification event when resources change in the bank domain, and to provide notification of the resource change to the Third Party using the Open Banking API.

Endpoint	Function	API Supported	Market Supported
POST /event-subscriptions	Create Event Subscription	Account Information	UK, CIIOM, Europe
		Funds Confirmation	UK, CIIOM
GET /event-subscriptions	Get Event Subscription	Account Information	UK, CIIOM, Europe
		Funds Confirmation	UK, CIIOM
PUT /event-subscriptions/{EventSubscriptionId}	Change Event Subscription	Account Information	UK, CIIOM, Europe
		Funds Confirmation	UK, CIIOM
DELETE /event-subscriptions/{EventSubscriptionId}	Delete Event Subscription	Account Information	UK, CIIOM, Europe
		Funds Confirmation	UK, CIIOM
POST /events	Create outstanding notification events from the bank and to send event acknowledgement to the bank	Account Information	UK, CIIOM, Europe, Hong Kong
		Funds Confirmation	UK, CIIOM

 

API Request Headers

Key	Type	Required	Example Value	Description
Content-Type	String	Yes	application/json	This indicates the media type of the resource and the value must be application/json
Accept-Language	String	Optional		Standard HTTP header to indicate the natural language set used in the response. Available values : en-HK, zh-HK, zh-CN
Authorisation	String	Yes		Standard HTTP header that allows credentials to be provided to the authorisation/resource server. Based on the OAuth 2.0/OIDC framework, this consists of basic or bearer authentication schemes
x-fapi-auth-date	String	Optional		Customer last logged-in time with the TSP application. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-addres	String	Optional		Customer IP address when making a request with the TSP application
x-fapi-interaction-id	String	Optional		Unique correlation ID to playback response for each request

 

API Request Object

Name	Type	Required	Example Value	Description
ack	String	Optional	“4d3559ec67504aaba65d40b0363faad8”	List of successfully handled “jti”
returnImmediately	Boolean	Mandatory	true, false	Optional JSON Boolean value that indicates the SET transmitter should return an immediate response even if no results are available (short polling)
maxEvents	Integer	Mandatory	20	Size limit for the event collection size in the response, null or zero input for the field indicates the bank returned an empty set of outstanding events

 

API Response Object

Name	Description	Class	Enumeration
sets	JSON object containing zero or more SETs being returned. Each member name is the "jti" of a SET to be delivered, and its value is a JSON string representing the corresponding SET. If there are no outstanding SETs to be transmitted, the JSON object shall be empty. Note that both SETs being transmitted for the first time and SETs that are being retransmitted after not having been acknowledged are communicated here.	String	N/A

 

Error

Scenario	HTTP Code	Error Code	Error Description
Input Data Validations -  "maxEvents" is greater than 10	400	OB.Field.Invalid	maxEvents is not within the limits allowed by ASPSP
Input Data Validations - "returnImmediately" = false	400	OB.Field.Invalid	Invalid field
Input Data Validations - without maxEvents blocker	400	OB.FieldHeader	Bad Request - Missing headers Bad Request - Incorrect headers
[Pool and acknowledge] Validation - return an error when querying 'POST /events' with 1 mismatched ack e.g: maxevents=1 returnImmediately = true Only 1 jti value in ack and it is not found in database	400	OB.Unexpectederror	Jti in the request are not valid
[Pool and acknowledge] Validate - return an error when querying "POST /events" with 2 mismatched ack e.g: maxevents=10 returnImmediately = true 2 jit values in ack, both are not found in database	400	OB.Unexpectederror	Jti in the request are not valid
[Pool and acknowledge] Validate - return an error when querying "POST /events" with 2 mismatched ack e.g: maxevents=10 returnImmediately = true 2 jit values in ack, only 1 jit is found in database	400	OB.Unexpectederror	Jti in the request are not valid

 

POST /events request

@POST /events request

 

POST /events response

@POST /events response

 

Return to top