Account Information - HK - Personal

---

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 fulfilment APIs. The following is a step by step guide to help you on-board into our sandbox as quickly as possible and start working with our APIs. In the following chapters you will learn how to:

• Register on the portal
• Get to know your well known endpoints
• Create a new project
• Request an access token
• Create consent resource
• Ask the customer for consent authorisation
• Exchange auth code for an access token
• Call protected API resources

Step 1 - Register on the Portal

Before you can access our sandbox you must first register for Open Banking Hong Kong SAR and activate your account on http://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 - Get to know the well-known configuration

It's a good idea to consult the well-known endpoint (also known as Discovery Endpoint) in order to find out the configuration about the Identity Server Provider. It's a JSON document which contains information like the issuer name, supported API scopes, OAuth 2.0 endpoints, etc.

Remember, that the well-known configuration is market dependent and you can find it in the `API Information` of the targeted API within the portal.

Here are the most relevant bits of the info that you need pay attention to for the purpose of this tutorial:

• registration_endpoint - the URL of the Dynamic Client Registration Endpoint, which can be used to register your API clients.
• token_endpoint - the URL of the OAuth 2.0 Token Endpoint, you will use it to request various tokens.
• token_endpoint_auth_methods_supported - contains a list of Client Authentication methods supported by this Token Endpoint.
• authorization_endpoint - the URL of the OAuth 2.0 Authorization Endpoint, you will use it to initiate the customer journey for consent authorisation.
• scopes_supported - OAuth 2.0 scope values supported by the server.
• request_object_signing_alg_values_supported - contains a list of supported signing algorithms (`alg` values) used by the server to verify the signature of the signed Request Objects (request body, query parameters, headers).
• id_token_signing_alg_values_supported - contains a list of supported signing algorithms (`alg` values) used by the server to sign the ID Token JWT.

 

Step 3 - 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 replicating the dynamic client registration (DCR) process. This will register your app on 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 http://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 5.** 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 5.** Select Market

Select the Market which has the APIs you are interested in e.g. Hong Kong SAR and click on continue

Create Project Step 3 of 5.** 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 4 of 5.** 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 5 of 5.** 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 4 - Using our Sandbox

Request `Access Token` (client_credentials)

Before you can create an initial consent resource you have to request an access token of type `client_credentials`.

The way you request an access token depends on the token auth method which was used to register your oauth client:

• tls_client_auth
• private_key_jwt

If you are using `tls_client_auth` method then you must have the following ready at your hands:

• The `Private Key` that was used to generate CSR during project creation steps in Dev Hub.
• The `Transport Certificate` which can be downloaded from the project page you created in Dev Hub.
• The `Token Endpoint` from the well-known configuration (see `API Information` section).
• The `Client ID` from the project page you created in Dev Hub.
• The `Scope` of the requested token. For a list of supported scopes please consult the well-known configuration.

Here is a CURL command example on how to request a token with `client_credentials` grant type:

@POST/client credentials_tls

NOTE: please consult the well-known configuration to find out the 'token_endpoint' URL you have to use. 

If you are using `private_key_jwt` auth method then you must have all pre-requisites as for `tls_client_auth` method (see above) and additionally these:

• The `KID` from the project page you created in Dev Hub.
• Prepare `Client Assertion` JWT (instructions on how to prepare the JWT is provided below).

Here is a CURL command example on how to request a token with `client_credentials` grant type:

@POST/client credentials_jwt

NOTE: please consult the well-known configuration to find out the 'token_endpoint' URL you have to use.

The sandbox will validate your (client) Transport Certificate against the `Client ID` and `Scope` of the requested token, and return an access token:

@POST/client credentials_jwt_return_access_token

This access token will be used in the next API call to create a consent resource.

Prepare `Client Assertion` JWT

First you need to assemble the JWT with bear minimum fields as in below example.

JWT Header:

@POST/JWT_header

Where:

• The `alg` is the value from `token_endpoint_auth_signing_alg_values_supported` field from well-known configuration.
• The `kid` is the KID from the project page you created in Dev Hub.

JWT Payload:

@POST/JWT_Payload

Where:

• Both `iss` and `sub` are the `Client ID` from the project page you created in Dev Hub.
• The `aud` is the value from `token_endpoint` field from well-known configuration.
• The `exp` is the epoch timestamp in seconds when the JWT is going to expire (a typical value would be 5 min or so).

Next, use your `Private Key` to sign the Header and Payload. To accomplish this you would typically use a Token Signing/Verification Library, depending on your programming language of choice.

Here is an example of a signed `Client Assertion` JWT:

@POST/client_assertion_sample

Here is a Java code example that can be used to accomplish JWT signing:

@POST/JWT_Signing_example_Java

The PRIVATE_KEY_PEM_FILE is the `Private Key` in PEM format, which was used to generate the CSR (see project creation steps).  

Now that you have your JWT signed, you can use it as `Client Assertion` value in your token request call.

Prepare `Client Assertion` JWT (alternative)

As an alternative, if you are not ready to jump into coding yet, there are tools like `online JWT debuggers` available which can be used to sign a JWT.

For instance, one could use https://jwt.io:

• In the `HEADER` and `PAYLOAD` section (left side of debugger) edit your JWT according to your use case.
• In the `VERIFY SIGNATURE` section (the left side of debugger) use your `Private Key` to sign the data.
• As a result, the `Encoded` section (right side of debugger) will have your signed JWT.

Disclaimer: HSBC is not affiliated with any `online JWT debuggers`. Should you choose to use such tools, HSBC cannot be held liable in any way and it is only your responsibility what signing keys and data you are using with these tools.        

Create Consent

In this step you will create a `Consent` resource which is an important pre-condition before the Customer Authorisation step can be initiated. Remember, the structure of the `Consent` is API dependent and in this particular example we will create one for Account Information API - `Account Access Consent`.  For other available `Consent` types please consult the API documentation.

The `Account Access Consent` represents access permissions on customer's accounts. The example below sets only few permissions, for all available permissions please consult the API documentation. In production your application should allow the customer to preselect access permissions required by your application, then you create the consent with the chosen permissions.

@POST/account_access_consent_permissions

NOTE: please consult the swagger documentation for more details on how to build the API request.

Here is a CURL command example on how to create `Account Access Consent` resource:

@POST/account_access_consent_resource

NOTE: please consult the well-known configuration and swagger documentation to find out the URL you have to use.

Notice the value of the `Authorization` header, it must be the `access token (client_credentials)` acquired in previous step.

A successful response will look like:

@POST/account_access_consent_response

NOTE: please consult the swagger documentation for more details on the API response.

More details about the response fields can be found in the API documentation.

For now you need to remember the `Consent ID` value, as you are going to need it in the next step.

Also notice the value of the `Status` field, the `AwaitingAuthorisation` tells you that you are ready to initiate the next step - Customer Authorisation of the consent.  

Initiate Customer Authorisation

The ultimate goal of this step is to receive an `Auth Code` from HSBC which will allow a TSP to exchange it for an access token.

So in order to initiate customer authorisation you need the following pre-requisites at your hand:

• The `Client ID` from the project page you created in Dev Hub.
• The `Redirect URI` from the project page you created in Dev Hub.
• The `Consent ID` from the create consent step.
• The `Audience` which is the `authorization_endpoint` from well-known configuration.
• The `State` generated by client to prevent cross-site request forgery (RFC6749).  
• The `Nonce` generated by client to mitigate replay attacks (OpenID Connect specification).

You will have to prepare the `Request` object which is a Signed JWT which is explained below.

Prepare `Request` JWT

The header of the Request JWT must be prepared same way as the header of the `Client Assertion` (see above), regardless of the auth type of your registered client.  

JWT Payload:

@POST/prepare_request_JWT

Where:

• The `764325979` is the `Consent ID` and you will have to replace it with your's.
• Both `iss` and `client_id` have same value which is the `Client ID`.
• The `exp` is the epoch timestamp in seconds when the JWT is going to expire (a typical value would be 5 min or so).

Next, use your `Private Key` to sign the Header and Payload. To accomplish this you would typically use a Token Signing/Verification Library, depending on your programming language of choice.

Here is an example of a signed JWT:

@POST/signed_JWT

Authenticate & Authorise Consent

Now that you have your JWT signed, you can use it as your `Request` value in the initiate consent authorisation call:

@POST/authenticate_authorise_consent

NOTE: please consult the well-known configuration to find out the 'authorization_endpoint' URL you have to use.

Next, a typical client web app will direct their customer to 'GET /authorize' endpoint in the browser, in which case at this point TSP's client interaction with HSBC server is interrupted until the customer completes (successfully or by rejecting) the authentication & consent authorisation steps within HSBCs domain.

The same link will work for deeplinking into the production HSBC Mobile App.

To perform the authentication step successfully in sandbox, we have prepared a list of test customer profiles & credentials which can be found [here]

Auth Code

On successful customer authentication and confirming consent authorisation the customer journey is going to be redirected to `Redirect URI`, which is now TSPs domain:

@POST/auth_code

Notice the redirection call contains the following parameters:

• scope - is the scope of the access token (which will be requested in the exchange code step, which is the next step);
• code - is the `Auth Code` to be used in the exchange code for access token step;
• state - is the same state as it was sent as part of the `/oauth2/authorize` endpoint; TSPs are strongly advised to validate this parameter to prevent cross-site request forgery (RFC6749).
• id_token - computed by server, can be used to validate the `Auth Code` is not tampered during transit;

Whilst the sandbox uses a browser consent journey, some lines of business will support consent journey via mobile app. Please review the Sandbox Vs Production table at the bottom of this guide for more information.

Remember, the `Auth Code` is a very short lived resource. Typically it expires after 30s (or so), hence it has to be exchanged for an access token as quickly as possible.

Request `Access Token` (authorization_code)

In this step the TSP has to exchange the `Auth Code` (acquired in the previous step) for an access token.

If you are using `tls_client_auth` method then you must have the following ready at your hands:

• The `Client ID` from the project page you created in Dev Hub.
• The `Auth Code` from the previous step.
• The `Redirect URI` from the project page you created in Dev Hub, it must be same that was used in the previous step.

Here is a CURL command example on how to request a token with `authorization_code` grant type:

@POST/request_access_token_tls

NOTE: please consult the well-known configuration to find out the 'token_endpoint' URL you have to use.

If you are using `private_key_jwt` auth method then you must have all pre-requisites as for `tls_client_auth` method (see above) and additionally these:

• The `KID` from the project page you created in Dev Hub.
• Prepare `Client Assertion` JWT (check Prepare `Client Assertion` JWT section above).

Here is a CURL command example on how to request a token with `authorization_code` grant type:

@POST/request_access_token_JWT

NOTE: please consult the well-known configuration to find out the 'token_endpoint' URL you have to use.

The sandbox will validate your (client) Transport Certificate against the `Client ID`, `Code` and `Redirect URI` of the requested token. A typical response with a positive outcome will look like this:

@POST/request_access_token_response

The most important things that you need from this response are:

• The `Access Token` which can be used to call protected API resources.
• The `Token Expiration` which tells for how many seconds the `Access Token` is valid.
• The `Refresh Token` which can be used to refresh the `Access Token`.

Request `Account Information` resource

This is the step where you finally get to call the `Account Information` resource.

Using the `Access Token` from previous step, here is an example of a CURL command:

@POST/request_account_info_resource

NOTE: please consult the well-known configuration and swagger documentation to find out the URL you have to use.

A typical successful response for requesting account information would look like this:

@POST/request_account_info_resource_response

NOTE: please consult the swagger documentation for more details on the API response.

Request `Access Token` (refresh_token)

At this point you have probably already learned that the Access Token is a short lived resource and it becomes unusable after a period of time. In this case what you need to do is to request a new `Access Token` by using the `Refresh Token` acquired two steps back.

Here is an example of a CURL command to request a new `Access Token` (this may also be known as `refresh token operation`):

@POST/request_access_token_refresh

NOTE: please consult the well-known configuration to find out the 'token_endpoint' URL you have to use.

A typical successful response for refresh token command would look like this:

@POST/request_access_token_refresh_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 - HK - Postman Collection (29 FEB 2024)

Please note, before you can continue please make sure:

• You have read Step 1 and registered yourself on the portal.
• You have read Step 2 to learn about well-known configuration.  
• You have read Step 3 and created a project in Dev Hub.
• You have read Step 4 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 run the API. Here is what you need to do:

• In Postman open the `Manage Environments` window and select your particular environment `HSBC Open Banking Sandbox` (the one you have just imported).
• Set key `bank_sandbox_ob_api_server` to `issuer` value from well-known configuration.
• Set key `bank_sandbox_ob_token_endpoint` to `token_endpoint` value from well-known configuration.
• Set key `bank_sandbox_ob_authorize_endpoint` to `authorization_endpoint` value from well-known configuration.
• Set key `bank_sandbox_ob_account_consents_path` to `/open-banking/v1.0/aisp/account-consents` (example for HK market). This is market dependent, so you need to consult our swagger documentation for more details.
• Set key `bank_sandbox_ob_accounts_path` to `/open-banking/v1.0/aisp/accounts` (example for HK market). This is market dependent, so you need to consult our swagger documentation for more details.
• Set key `bank_sandbox_ob_clientId` to your `Client ID` value from the project page you created in Dev Hub.
• Set key `bank_sandbox_ob_kid` to your `KID` value from the project page you created in Dev Hub.
• Set key `bank_sandbox_ob_authorize_callbackURL` to your `Redirect URI` from the project page you created in Dev Hub.
• Set key `bank_sandbox_ob_PKCS8PEM` to your `Private Key` that was used to generate CSR during project creation steps in Dev Hub.
• Set key `bank_sandbox_ob_accounts_consent` to your `Account Access Consent` which is used as request body in `POST /aisp/account-consents`. This is market dependent, so you will need to consult our swagger documentation for more details. For now, here is an example based on HK market:

@POST/postman_permission

The next step is you need to instruct the Postman to use a Transport Certificate when calling the API server. Here is what you need to do:

• In Postman open the `Settings` window.
• Go to `Certificates` tab.
• Click `Add Certificate` button.
• Set `Host` to hostname value of the `issuer` field from well-known configuration, for instance `secure.sandbox.ob.hsbc.com.hk`.
• Set `CRT fle` to the `Transport Certificate` file which can be downloaded from the project page you created in Dev Hub.
• Set `KEY fle` to the `Private Key` file that was used to generate CSR during project creation steps in Dev Hub.
• Click `Add` button.

Now you can execute the API in the following order:

1. Get Client Credentials Token.
2. Create Account Access Consent.
3. Initiate Consent Authorisation. You are expecting a `302` response code with `Location` header. You need to copy/paste the value of `Location` header into the browser, authenticate yourself as a customer (use our test profiles) and confirm the consent. Once the consent is confirmed, you should be redirected back to TSP's domain (still in browser), which is `Redirect URI`. Now you need to extract the `code` query parameter from `Redirect URI`.
   NOTE: The 'Automatically follow redirects' feature must be switched off on Postman.
   NOTE: The copy/paste of the Location header value which is described here must be followed only when working with Postman ollection. You are not advised to use this aproach in your production app, but rather completely rely on the behaviour of 'GET /authorize' via browser.
4. Get Access Token. Now you are back to postman where you need to use the `code` from previous step and manually replace `code` parameter value in the request body. You need to be quick here as the `code` is set to expire shortly. 
5. Get Customer Accounts.
6. Refresh Access Token.

Sandbox vs Production

Name	Sandbox	Production
Customer Authentication	Limited range & brand specific test profiles.	Real customer profiles.
Customer Data	Limited test data.	Real customer data.
API Client Registration	Manual & DCR is available.	Only DCR.
Certificate Signing Request (CSR)	One single CSR, submitted to Sandbox in order to be issued Transport & Signing Test Certificates.	Two separate CSRs - one for Transport and one for Signing Certificate, submitted to a well known & trusted CA.
Transport & Signing Certificates	Provided by Sandbox after CSR submission.	Provided by CA after CSR submission.
Customer Consent	The sandbox consent journey is limited to browser.	The production consent journey is limited to HSBC Mobile App. Once the authorise consent journey in the HSBC Mobile App is completed, the customer is redirected back to TSP's web site or mobile app. From there the TSP can call token API to exchange the received Auth Code for tokens.

Return to top

Certificates

Generate Certificate

Onboarding any TSP to Open Banking requires the TSP to acquire the appropriate certificates signed by HK e-cert Post. The TSP shall apply for both organisational and encipherment certificates from HKPost.

There are 2 certificates required:

• Organisational certificate – The Organisational certificate from HK POST is used by the API client for mTLS authentication. It is also known as Client (Transport) Certificate.
• Encipherment certificate - The Encipherment certificate from HK POST is used for signature verification of APIs request data (subject to particular API: query params, request/response body etc.). It is also known as Signing Certificate.

The Signing certificate must be hosted on a publicly accessible URL and follow JWKS standard. This URL endpoint is owned by the TSP and it must be provided in every request from the TSP to HSBC Open Banking Services.

Certificates must be valid and follow x.509 v3 standard. The TSP does not need to upload a public certificate on the Open Banking Platform.

The following is the mapping between subject value and form input:

Subject value in organisational cert	Form Input
CN	User Name on section D of the application form. There are 4 entries means 4 different e-cert. the CN of the 4 difference cert refer to separate entries. Since we have 3 different cert type for organization. CN can map to user name of e-Cert (org) on section D (p.5-6), Unit Name of e-cert (Enc) on section E (p.7) and Server Name on section F (p.8-10)
E	Email address of the users on Section D of application form. The email addresses refer to separate entries in section D & section E on difference cert type
OU	Company Name as same as BR on section A1 on p.2 of the form
OU	BR CI Numbers on section A on p.2 of the form of the TSP
OU	The e-Cert Subscriber Reference Number
O	The e-cert Type

---

Generate public.jwks

How to extract public JWK from x.509 certificate

The following java program will help you to extract the public key for x.509 Signing Certificate and print it in JWK format.

@private_key_certificate

Here is an example of a fully qualified JWKS endpoint content, which contains public JWK used for digital signature validation. Notice you can have multiple JWK entries, and each entry must have a unique KID value within the JWKS.

@private_key_certificates

---

Upload public.jwks

Upload public JWKS file onto web server

Once the JWKS file is generated the TSP shall upload this file to their web server which should be publicly available. The recommendation is to use the TSP's organisational domain e.g. https://tsp-domain.com/your-jwks-path.

TSP embeds kid, certificate and private key in API call

When the TSP makes a call to connect to Open Banking APIs, ensure the following settings are correct:

Kid	Use the kid from the public JWKS, referring to Encipherment cert record
Connectivity certificate	Use Organisational cert and private key
Sign JWS Token	Use Encipherment Private Key

Return to top

OAuth APIs

Access tokens are used in token-based authentication to enable an authorised TSP to securely access the Open Banking API based on the OAuth 2.0 and the Open ID Connect framework. Access tokens consist of the following grant types – authorisation code, ID token, access token and refresh token.

Grant Type	Endpoint Specifications	notes
Authorisation Code	OIDC Section 3.1
ID Token	OIDC Section 2	Hybrid flow
Access Token	OIDC Section 3.1.3
Refresh Token	OIDC Section 12	Refresh Token rotation implemented

Sequence Flow

Token Expiry

Please see the summary table for token expiry:

Token	Endpoint	Time To Live
OAuth Code	POST/customer-auth/confirmation	2 minutes
Access Token	POST/token grant type:  client credentials	5 minutes
Access Token	POST/token grant type:  authorisation code	5 minutes
Access Token	POST/token grant type:  refresh token	5 minutes
Refresh token	POST/token grant type:  authorisation code	365 days

 

Return to top

Customer Consent Management

The below endpoints are used by TSPs to enable the customer consent management process.

Endpoint	Function
POST /account-consents	Enables the TSP to request the bank to create an account-consents resource. The POST API function is used to create an account-consents resource with consideration given to common API development practice
GET /account-consents/{consentId}	Enables the TSP to retrieve account-consents resource
DELETE /account-consents/{consentId}	Enables the TSP to perform deletion of account-consents resource

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 Parameters

Prepare the request parameters as shown below:

Key	Type	Required	Example Value	Description
consentId	String	Conditional		Unique identifier for consent

 

API Request Object

Name	Definition	Class	Enumeration
permissions	Specifies the Banking Open API account access data types. This is a list of data fields being consented to by the customer	ExternalPermissionCode	ReadAccountAvailability ReadAccountStatus ReadAccountBalance ReadAccountTransaction
expirationDate	Specified expiration date and time of the permissions. The maximum value is 365 days from current date.	ISODateTime
transactionFromDate	Specified filtering start date and time of the transaction event (open-ended if blank)	ISODateTime
transactionToDate	Specified filtering end date and time of the transaction event (open-ended if blank)	ISODateTime

 

API Response Object

Name	Definition	Class	Enumeration
permissions	Populated from Request	ExternalPermissionCode	ReadAccountAvailability ReadAccountStatus ReadAccountBalance ReadAccountTransaction
expirationDate	Populated from Request	ISODateTime
transactionFromDate	Populated from Request	ISODateTime
transactionToDate	Populated from Request	ISODateTime
consentId	Unique reference of consent object in the bank	String
status	Specifies the status of consent resource in code form	ConsentStatusCode	PendingAuthorise Rejected Authorised Revoked
creationDate	Date and time of consent resource creation	ISODateTime
statusUpdateDate	Date and time of consent status update	ISODateTime

Errors

Scenario	HTTP Code	Error Code	Error Description
Input Data Validations - Incorrect permissions	400	OB.Field.Invalid	Bad Request - Invalid field
Input Data Validations - Invalid date - ExpirationDateTime - TransactionFromDateTime - TransactionToDateTime - Incorrect field format (Such as, date format is not met pattern, value is outside of enum list, incorrect length, etc)	400	OB.Field.Invalid	Bad Request - Invalid field
Input Data Validations - Invalid dates - TransactionFromDateTime - TransactionToDateTime	400	OB.Field.InvalidDate	Bad Request - DateFrom must be before DateTo Bad Request - DateTo must be after DateFrom
- Missing headers - Incorrect headers	400	OB.FieldHeader	Bad Request - Missing headers Bad Request - Incorrect headers

POST /account-consents request

@POST/account-consents request

POST /account-consents response

@POST /account-consents response

Consent Object Statuses 

Statuses implemented are in line with the Hong Kong Monetary Authority (HKMA) API Specification.

On top of what is articulated in the HKMA specifications:

• PSU inactivity results in timeout and consent is kept in PendingAuthorise status.
• Web/mobile browser window closure results in keeping the consent in PendingAuthorise status. Intentional actions of the PSU on the HSBC authentication page result in moving the consent to REJECTED status.
• At any point in time a PSU can revoke a consent within HSBC's access dashboard. If this occurs, the consent will have a REVOKED status. If TSPs attempt to access any accounts using the original consent, a 403 FORBIDDEN error will be returned.

Consent Status Definition

PendingAuthorise

• Account-consents resource is initialised and pending for customer authorisation.

Rejected

• Account-consents resource is rejected due to any cancellation or interruption of customer authorisation.

Authorised

• Account-consents resource is successfully authorised; the TSP is allowed to request in-scope customer data before expiry.

Revoked

• Account-consents resource is revoked due to customer consent revocation request.

Account Status

The below endpoints are used by TSPs to retrieve consented accounts for a customer.

Endpoint	Mandatory/ Optional	Function
GET /accounts	Mandatory	Enables Data Requestor to retrieve a list of account information including account status in bulk
GET /accounts/{accountId}	Mandatory	Enables the TSP to retrieve a list of account information, including the account status for a specific account ID

API Request Headers

Key	Type	Required	Example Value	Description
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 Parameters

Prepare the request parameters as shown below:

Endpoint	Key	Type	Required	Example Value	Description
GET /accounts/{accountId}	accountId	String	Conditional		Unique identifier for consent

Response

Name	Definition	Mandatory/ Optional	Class	Examples
accountId	Specifies the unique identifier used internally by Data Provider to identify an account	Mandatory	String	201137243039306132394A5553778B
accountNumber	Specifies the account number assigned by Data Provider to identify an account	Mandatory	String	01XXXXX188
accountType	Specifies the type of account	Mandatory	AccountTypeCode	Personal
accountSubType	Specifies the sub type of account	Mandatory	AccountSubTypeCode	Savings, Current
productName	Specifies the name of the product	Mandatory	String	Zero Balance Savings
accountStatus	Specifies the status of account	Mandatory	AccountStatus	Active, Inactive
currency	Specifies the account currency code	Mandatory	ISOCurrencyCode	HKD, RMB, USD

Errors

Scenario	TSP Facing HTTP Code	TSP Facing Error Code	Error Description
The TSP tries to access an account resource but the TSP does not have a consent authorisation for the AccountId e.g. an attempt to access GET /accounts/2001 when the PSU has not selected AccountId 2001 for authorisation	403	NA	Forbidden
HSBC Server Errors	500	OB.UnexpectedError /OB.InternalError
Invalid request  Invalid account number Invalid currency	400	OB.InternalError

GET /accounts request

@GET /accounts request

GET /accounts response

@GET /accounts response

GET /accounts/{accountId} request

@GET /accounts/{accountId} request

GET /accounts/{accountId} response

@GET /accounts/{accountId} response

Account Balance

Account Balance is a synchronous enquiry API that retrieves the following Account Balances:

Intraday: real time ledger balance and real time available balance

The Request and Response format is in JSON. Up to 200 accounts can be returned in a single request. The below endpoints are used by TSPs to retrieve consented account balances for a customer.

Retrieve Account Balance API

Endpoint	Function
GET /accounts/{accountId}/balances	Enables Data Requestor to retrieve account balance for specific Account ID

API Request Headers

Prepare the request parameters as shown below:

Key	Type	Required	Example Value	Description
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
accountId	String	Mandatory		Unique identifier for account

API Request Parameters

Prepare the request parameters as shown below:

Key	Type	Required	Example Value	Description
accountId	String	Conditional		Unique identifier for account

API Response Object

Name	Definition	Class	Examples
accountId	Specifies the unique identifier used internally by the bank to identify an account	String	201137243039306132394A5553778B
balance	Specifies the balance object of the account	BalanceData
type	Specifies the type of account balance	BalanceTypeCode	ledgerBalance, availableBalance, dayEndLedgerBalance
creditDebitIndicator	Specifies whether the account balance is a credit or debit balance	CreditDebitCode	Credit, Debit
amount	Specifies the account balance amount	String	10000.25
currency	Specifies the account currency code	ISOCurrencyCode	HKD, RMB, USD
datetime	Specifies the date and time of the account balance	ISODateTime	2020-12-22T07:06:20Z

Errors

Scenario	TSP Facing HTTP Code	TSP Facing Error Code	TSP Facing Causes	Error Description
The TSP tries to access an account resource but the TSP does not have a consent authorisation for the AccountId e.g. an attempt to access GET/accounts/2001/balance when the PSU has not selected AccountId 2001 for authorisation	403	NA		Forbidden
HSBC Server Errors	500	OB.InternalError	Internal Server Error	Internal Server Error

API Request Body

Account balances can be requested individually per account, or in a multi-account request of up to 50 accounts.

Example request body:

@Example request body

Example response payload:

@Example response payload

Account Transaction(s)

Account Transaction(s) is a synchronous enquiry API that retrieves the current day or historical date transactions. Request and Response format is JSON. The API request provides the transactions for a single account per API call. Each transaction enquiry call returns up to 200 transactions in single API response, additional transactions can be retrieved via subsequent calls using the next link, i.e. via pagination. The below endpoints are used by TSPs to retrieve consented account transactions for a customer.

Retrieve Account Transaction API

Endpoint	Function
GET /accounts/{accountId}/transactions	Enables Data Requestor to retrieve account transactions for specific Account ID

API Request Headers

Key	Type	Required	Example Value	Description
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 Parameters

Query Parameter	Definition	Mandatory/ Optional	Class	Examples
accountId	Unique identifier for account	Mandatory	String
fromDate	Specifies the start date time for filtering out of the transactions date, blank value will be treated as open end. Time Zone input will be ignored.	Optional	ISODateTime	2020-12-22T07:06:20Z
toDate	Specifies the end date time for filtering out of the transactions date, blank value will be treated as open end. Time Zone input will be ignored	Optional	ISODateTime	2020-12-22T07:06:20Z

Response

Data Dictionary – AccountTransactionData

Name	Definition	Mandatory/ Optional	Class	Examples
accountId	Specifies the unique identifier used internally by Data Provider to identify an account	Mandatory	String	201137243039306132394A5553778B
accountNumber	Specifies the account number assigned by Data Provider to identify an account	Mandatory	String	XXXXXXXXXX02
transactionId	Specifies the unique identifier for the transaction used by the Data Provider	Mandatory	String	MBKFT42508230004073
transactionDescription	Specifies the description of transaction	Mandatory	String	Bill Payment
transactionDate	Specifies the date and time of the transaction. posted	Mandatory	ISODateTime	2020-12-22T07:06:20Z
creditDebitIndicator	Specifies whether the transaction is a credit or debit entry	Mandatory	CreditDebitCode	Credit Debit
status	Specifies the status of the transaction entry	Mandatory	TransactionStatusCode	Pending Booked
amount	Specifies the transaction amount	Mandatory	String	10079.36
currency	Specifies the account currency code	Mandatory	ISOCurrencyCode	HKD, RMB, USD

Errors

Scenario	TSP Facing HTTP Code	TSP Facing Error Code	Error Description
Transaction From and To Date Validations. When FromDate > toDate.	400	OB.Field.InvalidDate	DateTo must be after DateFrom
Transaction From and To Dates are in Invalid format. When Format of the date is not in ISOdatetime.	400	OB.Field.InvalidDate	Invalid date value
The TSP tries to access an account/balance resource but the TSP does not have a consent authorisation for the AccountId e.g. an attempt to access GET /accounts/2001 or GET /accounts/2001/transaction when the PSU has not selected AccountId 2001 for authorisation	403	NA	Forbidden
Request query params: Date Range exceeds specific range of 60 days.	400	OB.Field.InvalidDateRange	Invalid date range.
Request query param: Transaction From Date is future date	400	OB.Field.InvalidDate	DateFrom is Future date
Request query param: Transaction To Date is future date	400	OB.Field.InvalidDate	DateTo is Future date
HSBC Server Errors	500	OB.InternalError	Internal Server Error

 

GET /accounts/transactions request sample

@GET /accounts/transactions HTTP/1.1

GET /accounts/transactions response sample

@x-fapi-interaction-id

Account Availability

This API is used by the TSP to verify customer information for those customers that have granted consent, in order for the TSP to conduct KYC for customer. The below endpoints are used by TSPs to retrieve consented account availability for a customer.

Retrieve Account Availability API

Endpoint	Mandatory/ Optional	Function
POST/accounts/availability	Mandatory	Enables the TSP to check customer information against the specific account and return account availability status

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

Response

Personal Banking

Name	Definition	Mandatory/ Optional	Class	Examples
paramName	Specifies the parameter name to verify the available customer and account-type information	Mandatory	String	fullName accountType email phoneNumber
paramValue	Specifies the parameter value against the parameter type	Mandatory	String	Dawen Chan Personal XX_name@email.com 87654321
status	Specifies the status of the account availability for the requested parameter	Mandatory	String	Yes,No

Errors

Error Description	HTTP Status	Error Code	Error Description
When consent is invalid	403	403	Forbidden
When account number sent in the request is invalid	403	403	Forbidden
Field validation failure - fullName - accountType - email - phoneNumber	400	OB.InvalidRequestParams	Invalid paramName
There are more than 4 paramNames in the request	400	OB.UnexpectedParamsNo	Maximum number of paramNames is 4
paramName requested is duplicated. The same pair of values	400	OB.ParamsDuplicated	Duplicated requested paramName
HSBC Server Errors	400	OB.MissingAccountNumber	paramName doesn't have accountNumber
HSBC Server Errors	500	OB.InternalError	Internal Server Error

POST /accounts/availability request

@POST /accounts/availability request

POST /accounts/availability response

@POST /accounts/availability response

 

Event Polling

Event 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 TSP using the Open Banking API. The below endpoints are used by TSPs to get outstanding notification events and send event acknowledgements to the bank.

Endpoint	Function
POST /events	Enables the TSP to get outstanding notification events from the bank and to send event acknowledgement to the bank

 

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