Account Information - HK - Business

---

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.

To get started, you will need to register and login. Once logged in you will need to create a project in our Dev Hub that can be found in the top right of the portal. Creating a project simulates the pre-registration steps you'll need to complete in the live ecosystem and replicates our 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 fulfilment APIs including redirection to consent authorisation journeys.

---

Creating a project 

This section will take you through the steps involved in creating a project in the Dev Hub.

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

2. 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’.

3. Generate test certificates - Our sandbox only accepts test certificates. Upload your Certificate Signing Request (CSR) and click ‘Continue’ and your test Transport Certificates for Website Authentication (Organisational) and Signing Certificates (Encipherment) will be generated along with a public key and KID. Your test certificates, public key and KID will be available to download/copy from the project details page once you’ve completed project creation. 

If you don’t already have a CSR, follow the commands provided to generate a private key and CSR.

Please note - in order to simplify the project creation process, your test Transport and Signing certificates will be generated from the same CSR, however in the production ecosystem you’ll be required to provide different CSRs to generate your Transport and Signing certificates.

4. Generate software statement - On the generate software statement page, enter the details of your app including which Open Banking role(s) it supports and click ‘Continue’. 

Please note – The software statement will expire after 1 hour. If you don’t complete project creation before it expires your project will be removed and you’ll need to start the process again. This will also happen if you’re timed out due to inactivity or sign out of develop.hsbc before completing project creation.  

5. Sandbox Dynamic Client Registration (DCR) – We recommend that you perform sandbox DCR by completing the final step in the project creation process. Simply enter your auth method (For HSBC HK can only be only private_ket_jwt), click “Complete” and your project details, including ClientID, will be displayed.

Please note – in order to simplify access to the sandbox, registering your app once will enable you to access sandbox APIs for all applicable brands, however in our production environment, you’ll be required to register your app separately for each brand you want to integrate with. 

Alternatively, you can perform sandbox DCR directly from your own terminal, using the inputs displayed on the right-hand side of the screen. Refer to the technical documentation of the API for more information regarding DCR.

private_key_jwt

@POST/register_private_key_jwt_curl

Once you’ve successfully completed the process, your new project will be displayed on the sandbox screen. Click on the project card and your project details, including ClientID, will be displayed. 

Please note – If you perform sandbox DCR from your own terminal, your project will only be displayed on the sandbox screen once sandbox DCR has been completed successfully i.e. once you’ve been provided with a ClientID. If your project is not displayed, it means that you haven’t performed sandbox DCR successfully and you should try again or complete the process using the guided journey. Remember to complete the process within 1 hour of the software statement being generated otherwise you’ll have to start again. 

Please refer to the other sections for information on accessing Dynamic Client Registration and other APIs

---

Accessing Sandbox APIs

Pre-requisites

• Register on develop.hsbc
• Register an app on the sandbox by creating a project in the Dev Hub

Please refer to the specific API documentation in the portal for information on calling the sandbox APIs, replacing the production base URL with the sandbox base URL.

---

Customer Consent

Our sandbox access authorisation journeys replicate the function of our production journeys from a TSP’s perspective, in that they enable the customer to select/confirm which account(s) are to be shared, and an authorisation code is provided following successful authentication. However the look and feel of the screens and the steps involved from a customer’s perspective have been standardised in our sandbox across all brands, for the purposes of simplification.

For the purpose of testing please use the test customer security credentials below to authorise the customer consent within the UI.

Brand	Test Customer User ID	Test Customer Password
HSBC Business HK	customer00	123456

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_cert

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_certs

---

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

TSP Registration

TSPs need to register their client with HSBC's Open Banking platform. In order to achieve this, TSPs need to get their software statement issued first - as per RFC 7591.

To request access to Production APIs, TSPs need to submit a request using the Help, Contact Us form in the portal. Select 'Open Banking APIs - HK - HSBC Business' from the dropdown menu 'Which API does your query relate to?', and then select 'Production Access'.

On receipt of this information the HSBC support team will review the TSPs request and begin the process to on-board the TSP to the Open Banking eco-system. The Software Statement Assertion (SSA) will be securely mailed to the TSP’s registered email address.

TSPs need to check the address of HSBC's registration endpoint using our well-known endpoints available under API Information.

TSP performs dynamic registration:

Software Statement Sample (Full)	{ "software_mode": "Live", "software_environment": "TODO", "software_client_uri": "https://TODO.com", "software_logo_uri": "https://TODO.com", "software_policy_uri": "https://TODO.com", "software_tos_uri": "https://TODO.com", "software_on_behalf_of_org": "https://www.tsp.com", "software_client_description": "software statement for testing purposes", "software_jwks_revoked_endpoint": "https://TODO.com", "software_roles": ["AISP"], "org_jwks_endpoint": "https://TODO.com", "org_status": "Active", "org_contacts": [], "organisation_competent_authority_claims": [], "org_id": "5cb8572403f0df001d", "org_name": "ABC Merchant Ltd.", "org_jwks_revoked_endpoint": "https://TODO.com", "software_client_name": "ABC Merchant Ltd.", "iss": "2fNwVYePN8WqqDFvVf7XMN", "iat": 1556445993, "jti": "45903DAE-3174-4E9E-9047-BBAE9C1A723F", "software_client_id": "2qY9COoAhfMrsH7mCyh86T", "software_redirect_uris": ["https://www.tsp.com/", "https://www.tsp.com/ack"], "software_id": "2qY9COoAhfMrsH7mCyh86T", "software_jwks_endpoint": "https://www.tsp.com/jwks/public.jwks" }
Software Statement Sample (Minimal)	{ "software_on_behalf_of_org": "https://www.tsp.com", "software_roles": ["AISP"], "org_id": "5cb8572403f0df001d", "org_name": "ABC Merchant Ltd.", "software_client_name": "ABC Merchant Ltd.", "iss": "2fNwVYePN8WqqDFvVf7XMN", "iat": 1556445993, "jti": "45903DAE-3174-4E9E-9047-BBAE9C1A723F", "software_client_id": "2qY9COoAhfMrsH7mCyh86T", "software_redirect_uris": ["https://www.tsp.com/", "https://www.tsp.com/ack"], "software_id": "2qY9COoAhfMrsH7mCyh86T", "software_jwks_endpoint": "https://www.tsp.com/jwks/public.jwks" }
Register payload sample	{ iss="", "aud": "https://api.ob.hangseng.com", "scope": "openid accounts", "redirect_uris": ["https://www.tsp.com/", "https://www.tsp.com/ack"], "response_types": ["code id_token"], "grant_types": ["authorization_code", "refresh_token", "client_credentials"], "application_type": "mobile", "id_token_signed_response_alg": "PS256", "request_object_signing_alg": "PS256", "token_endpoint_auth_method": "private_key_jwt", "token_endpoint_auth_signing_alg": "PS256", "software_id": "2qY9COoAhfMrsH7mCyh86T", "software_statement": "{Software Statement signed JWT token}", "exp": 1674206304, "iat": 1555506046, "jti": "45903DAE-3174-4E9E-9047-BBAE9C1A723F" }

Implemented Endpoints:

Endpoints	Mandatory	Implemented
POST /register	Conditional	Y
GET /register/{ClientId}	Optional	Y
PUT /register/{ClientId}	Optional	Y

 

Supported authentication methods:

Method	Supported
private_key_jwt	Y

private_key_jwt

@private_key_jwt

Message signing

x-jws-signature

The iss value from x-jws-signature must match with full DN of HK Post certificate.

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
Authorisation Code	OIDC Section 3.1
ID Token	OIDC Section 2
Access Token	OIDC Section 3.1.3
Refresh Token	OIDC Section 12

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	60 minutes - OAuth Code elapsed time
Access Token	POST/token grant type:  refresh token	5 minutes
Refresh token	POST/token grant type:  authorisation code	AISP 90 days – If consent expiry date is left blank or more than 90 days OR If consent expiry date is provided and less than 90 days the refresh token will only be valid up to the provided date

 

Return to top

Customer Consent Management

Summary

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 by the customer	ExternalPermissionCode	ReadAccountAvailability ReadAccountStatus ReadAccountBalance ReadAccountTransaction
expirationDate	Specified expiration date and time of the permissions (open-ended if blank)	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
balanceFromDate	Specified filtering start date and time of the balance event (open-ended if blank)	ISODateTime
balanceToDate	Specified filtering end date and time of the balance 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
balanceFromDate	Populated from Request	ISODateTime
balanceToDate	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

Summary

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

Retrieve Accounts API

Endpoint	Mandatory/ Optional	Function
GET /accounts	Mandatory	Enables the TSP to retrieve a list of account information in bulk, including account status

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

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	Business
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

Account Balance

Summary

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

Intraday: real time ledger balance and real time available balance

Historical: day end ledger balance

The fromDate and toDate request parameters can be added to support a historical balance query. The Request and Response format is in JSON. Up to 200 accounts can be returned in a single request. 

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
fromDate	String	Optional		Specifies the start date time for filtering out the transactions date; a blank value will be treated open-ended. Time zone input will be ignored. Date format i.e. 2017-10-22
toDate	String	Optional		Specifies the end date time for filtering out the transactions date; a blank value will be treated as open-ended. Time zone input will be ignored. Date format i.e. 2017-10-22

API Request Parameters

Prepare the request parameters as shown below:

Key	Type	Required	Example Value	Description
accountId	String	Conditional		Unique identifier for account
fromDate	String	Optional		Specifies the start date time for filtering out the transactions date; a blank value will be treated open-ended. Time zone input will be ignored. Date format i.e. 2017-10-22
toDate	String	Optional		Specifies the end date time for filtering out the transactions date; a blank value will be treated as open-ended. Time zone input will be ignored. Date format i.e. 2017-10-22

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
Balances From and To Date Validation failure: fromDate > toDate	400	OB.Field.InvalidDate	DateTo must be after DateFrom	DateTo must be after DateFrom
Balances From and To Dates are in Invalid format	400	OB.Field.InvalidDateFormat	Invalid date format	Invalid date value
Date Range exceeds specific range	400	OB.Field.InvalidDateRange	invalid date range	1 year (365 days)
HSBC Server Errors	500	OB.UnexpectedError	Unexpected 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. Transactions can be retrieved in ascending order (oldest first) or descending order (latest first).

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 and 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 1 year	400	OB.InvalidDateRange	invalid date range.
Request query param: Transaction From Date is future date	400	OB.InvalidDate	DateFrom is Future date
Request query param: Transaction To Date is future date	400	OB.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

Summary

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.

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

Commercial Banking

Name	Definition	Mandatory/ Optional	Class	Examples
paramName	Specifies the parameter name to verify the available customer and account-type information	Mandatory	String	accountNumber businessRegistrationCertificate certificateOfIncorporation other HSBC accepts maximum three params
paramValue	Specifies the parameter value against the parameter type	Mandatory	String	HK AccountNumber format account number: 200123456888 format account number: 2009700002 businessRegistrationCertificate: P00022 certificateOfIncorporation: P00030 other: A000001
status	Specifies the status of the account availability for the requested parameter	Mandatory	String	Yes, No, Error

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 - businessRegistrationCertificate - certificateOfIncorporation - other - accountNumber	400	OB.InvalidRequestParams	Invalid paramName
There are more than 3 paramNames in the request	400	OB.UnexpectedParamsNo	Maximum number of paramNames is 3
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

Summary

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.

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