Real Time Direct Debit - 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. 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

Its 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 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 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.

A valid response is considered if you get a `302 Found` and `Location` header with it.

Next, a typical client web app will direct their customer to this `Location` and at this point your client interaction with HSBC server is interrupted until the customer completes (successfully or by rejecting) the authentication & consent authorisation steps within HSBCs domain.

Notice, you can also initiate the authorisation (CURL from above) via browser, in which case all redirection to HSBC logon page happens automatically.  

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;

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:

• Real Time Direct Debit - Postman Collection (06OCT2022)
• Environment Variables - Postman Collection (06OCT2022)

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`.
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

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:

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.

import org.apache.commons.io.FileUtils;
import com.nimbusds.jose.jwk.JWK;

class JwksTest {

    private final static String CERT_PATH = "C:\\...\\abc.cer";

    public static void main(final String[] args) throws Exception {
        JWK jwk = JWK.parseFromPEMEncodedObjects(FileUtils.readFileToString(new File(CERT_PATH)));
        System.out.println("JWK:");
        System.out.println(jwk.toJSONString());
        System.out.println("x5t#S256:");
        System.out.println(jwk.computeThumbprint("SHA-256").toString());
}
}

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.

{
    "keys": [
    {
        "kty": "RSA",
        "x5t#S256": "8IsNK2Cv7ciD_L6XXys-g0F_79d3OJjnhKOFzYRop6k",
        "e": "AQAB",
        "use": "sig",
        "kid": "533efc9a-ec63-4c27-9105-f4e30733b8c9",
        "x5c": ["MIIEIzCCAwugAwIBAgIKcPsHQlOJMoK78zANBgkqhkiG9w0BA
QsFADBIMQswCQYDVQQGEwJERTEMMAoGA1UECgwDQkRSMREwDwYDVQQLDAhJVCAtIER
ldjEYMBYGA1UEAwwPUFNEMiBUZXN0IFN1YkNBMB4XDTE5MDMyNjA4MDYxNFoXDTE5MD
kyMjA4MDYxNFowgaExCzAJBgNVBAYTAlVLMRAwDgYDVQQKDAdIU0JDIFVLMRswGQYDV
QQLDBIxIENlbnRlbmFyeSBTcXVhcmUxEzARBgNVBAcMCkJpcm1pbmdoYW0xEzARBgNV
BAkMCkJpcm1pbmdoYW0xDTALBgNVBAMMBEhTQkMxGTAXBgNVBGETEFBTREdCLUZDQS0
3NjUxMTIxDzANBgNVBBETBkIxIDFIUTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQ
oCggEBAKHNo4NkC+avERqD68xIRSgMHcDlfeSg3nodsaqlBUfoy7oEbU1qsiHriYQEo
jQa8zadDGiBd9nnsalzAaBvlIKHBV3+PrM\/xpbZ7FmCUNnCwuNy0FtutoAQDYuBeHu
lq3lV2ms0EsD2O4JtBGdEPze+EGEj6wi7fvc5K2ohDsS0KKqiwbK2QM7JvktbP+CxO5
HNuQJ\/QefYcteINy4NO5Cb1NKrHXxfWgrf+lMpjavu5B7alut26Ofk7fU1NOx8i8hA
VCfn3a\/sR5jLqUWJREjHZpuGEejrUGeckhCiSAZY2a0vi2A247b03pt1h3C0OMpBum
gvhor1jlNqh3T0Ls8CAwEAAaOBtDCBsTCBgAYIKwYBBQUHAQMEdDByMHAGBgQAgZgnA
jBmMDkwEQYHBACBmCcBAQwGUFNQX0FTMBEGBwQAgZgnAQMMBlBTUF9BSTARBgcEAIGY
JwECDAZQU1BfUEkMIUZpbmFuY2lhbCBDb25kdWN0IEF1dGhvcml0eSAoRkNBKQwGR0I
tRkNBMAsGA1UdDwQEAwIGQDAfBgNVHSMEGDAWgBRczgCARJu0XDNe5JrFOPI4CIgFoj
ANBgkqhkiG9w0BAQsFAAOCAQEAwW7zWg7jBrSRnUwDiuSR2RR91QcZFGoG+KFKABv5b
6t+97lHSzRWe90BNaKoDFIJbG35UrqQkUfgMpfs2mTg0xx9IXWxJwg6NXO1NLMlAEbG
US3vqQQZufpvfkdHo+Du+DN1UfpUlCwtMDAHzvrcsv8e8bcVvdCsJRiuyI62At0S7rl
cE6uc3mTfOUN0hb0S89FvsrAHMjLd9mlrhDif9xHn3QWfEYJ6dmEr7tfuJzsJtVveZO
3LjgjMWwAjg5vfGB6l1M1nRg4vXfgbq+uxB+fGv5vtI66a1KvjLVIOnrbSuKfnEX0Id
sZ2JWsjw9RATn8EVm\/yKbo5FtaT7cgsow==",],
        "n": "oc2jg2QL5q8RGoPrzEhFKAwdwOV95KDeeh2xqqUFR-jLugRtTWqyI
euJhASiNBrzNp0MaIF32eexqXMBoG-UgocFXf4-sz_GltnsWYJQ2cLC43LQW262gBAN
i4F4e6WreVXaazQSwPY7gm0EZ0Q_N74QYSPrCLt9zkraiEOxLQoqqLBsrZAzsmS1s_4
LE7kc25An9B59hy14g3Lg07kJvU0qsdfF9aCt_6UymNq-7kHtqW63bo5-Tt9TU07HyL
yEBUJ-fdr-xHmMupRYlESMdmm4YR6OtQZ5ySEKJIBljZrS-LYDbjtvTem3WHcLQ4ykG
6aC-GivWOU2qHdPQuzw"
    },
    {
        "kty": "RSA",
        "x5t#S256": "1VOzgpR7_fMr40BoV77m7sFm55NiPMMW5cTvPacXMuk",
        "e": "AQAB",
        "use": "sig",
        "kid": "640241387865492011407431561399385246076601802398",
        "x5c": ["MIIFdzCCBF+gAwIBAgIUcCVqsH8LX3a6xwCtpTktomNynp4wDQY
JKoZIhvcNAQELBQAwfDELMAkGA1UEBhMCSEsxEjAQBgNVBAgTCUhvbmcgS29uZzESMBA
GA1UEBxMJSG9uZyBLb25nMRYwFAYDVQQKEw1Ib25na29uZyBQb3N0MS0wKwYDVQQDEyR
Ib25na29uZyBQb3N0IFRyaWFsIGUtQ2VydCBDQSAyIC0gMTcwHhcNMjAxMjAyMDIyMDA
5WhcNMjExMjAyMDIyMDA5WjCBzjELMAkGA1UEBhMCSEsxNDAyBgNVBAoTK0hvbmdrb25
nIFBvc3QgVHJpYWwgZS1DZXJ0IChPcmdhbmlzYXRpb25hbCkxEzARBgNVBAsTCjAwMDE
2MTQ0OTIxITAfBgNVBAsTGDExMjIzMzQ0MDAwMDAwMDAwMDAwMDAwMDEYMBYGA1UECxM
PVEVTVElORyBMSU1JVEVEMR8wHQYJKoZIhvcNAQkBFhBvcmcxQHRlc3RpbmcuY29tMRYw
FAYDVQQDEw1PUkcgVFJJQUwgT05FMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCA
QEAmVb5g+PJXHuRCajuxLHvVebgZL8bnalmrb9L6yKiJW61Hc6LB9TtBbe3Ke2QYZAp3B
MQrWAaLYVrF2CELbzcx27ZM3+0cakzlU5zZNvKQpV18z7Oncck7\/co+cKTwpHTY9BxbY
5+8BkXhy1JWKEEb2+o+o6fsN9ksZBfv+bG8SG5pe+DXKP4XWmSKL91bj2MTKRAMwTUy9F
OC2\/49z8YynQuwmQkxefWPNe8fAb35rdgnoMNrc3WToDbeN4\/1WX+C+nKN7bsBrxlvi
zwiG93jIz01kR4h2r7cZ64oQV4PJAQsvUsYf+gwd6cBEZ0HcjLy7ki8jqRBds52aVPKO1
mhwIDAQABo4IBnDCCAZgwNwYDVR0gBDAwLjAsBgorBgEEAf0eAQEtMB4wHAYIKwYBBQUH
AgEWEHd3dy5lQ2VydC5nb3YuaGswPAYDVR0RBDUwM6QfMB0xGzAZBgNVBAsMEua4rOipp
uaciemZkOWFrOWPuIEQb3JnMUB0ZXN0aW5nLmNvbTAJBgNVHRMEAjAAMA4GA1UdDwEB\/
wQEAwIF4DAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwQwgZwGA1UdIwSBlDCBka
F5pHcwdTELMAkGA1UEBhMCSEsxEjAQBgNVBAgTCUhvbmcgS29uZzESMBAGA1UEBxMJSG9
uZyBLb25nMRYwFAYDVQQKEw1Ib25na29uZyBQb3N0MSYwJAYDVQQDEx1Ib25na29uZyBQ
b3N0IFRyaWFsIFJvb3QgQ0EgMoIUOJ++qbSk\/JqFCXYJZGkZZuz5Ov4wRgYDVR0fBD8w
PTA7oDmgN4Y1aHR0cDovL3RyaWFsY3JsMS5lQ2VydC5nb3YuaGsvY3JsL2VDZXJ0Q0EyL
TE3Q1JMMi5jcmwwDQYJKoZIhvcNAQELBQADggEBACLz0AXlACfc0+0RqTzYlhfshQ11XH
AZXcyydsFoi9J16WKsazkiKKebrgLVCZVxTtdWZJp2A73G3rs51A86nvNJafrGs3YVTxp
UGyB4LuS2Z3i2KsJHcjefZQ3gCDwiHCldA7\/Fk4tSR8Rrae3+K3o\/VO4Mfj8Gcw6WwC
2YAg\/n0MrC7ctlB9lIQhvBDOA4BPkrqyV5swLNpVmvTnAkOq9oymsgCrfMX5RuUe8qbW
ZhG3LzarlGhHcTzXJFNOYhtKn1yS+twmEGwunhR4eUXW5td4faRJHFI1N3LL3HRXZUHLR
8hbKnJiTnk9ddgfiriy4ZJ629oQfOVH35npWGdU0="],
        "n": "mVb5g-
PJXHuRCajuxLHvVebgZL8bnalmrb9L6yKiJW61Hc6LB9TtBbe3Ke2QYZAp3BMQrWAaLYVr
F2CELbzcx27ZM3-0cakzlU5zZNvKQpV18z7Oncck7_co-cKTwpHTY9BxbY5-8BkXhy1JWK
EEb2-o-o6fsN9ksZBfv-bG8SG5pe-DXKP4XWmSKL91bj2MTKRAMwTUy
9FOC2_49z8YynQuwmQkxefWPNe8fAb35rdgnoMNrc3WToDbeN4_1WX-C-nKN7bsBrxlvizwi
G93jIz01kR4h2r7cZ64oQV4PJAQsvUsYf-gwd6cBEZ0HcjLy7ki8jqRBds52aVPKO1mhw"
    }]
}

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:

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:

Implemented Endpoints:

Supported authentication methods:

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.

Sequence Flow

Token Expiry

Please see the summary table for token expiry:

Return to top

Customer Consent Management

Summary

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

POST /direct-debit-consents

API Request Headers 

API Request Object

API Response Object

Errors

Sample request

@POST /direct-debit-consents HTTP/1.1

Sample response

@RESPONSE

GET /direct-debit-consents/{consentId}

API Request Headers

API Request Parameters

Prepare the request parameters as shown below:

API Response Object

Errors

404

Consent is in Revoked state

Sample request

@DD1

Sample response

@DD2

DELETE /direct-debit-consents/{consentId}

API Request Headers

API Request Parameters

Prepare the request parameters as shown below:

Errors

Sample request

@DD3

Sample response

@DD4

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.

Consent Status Definition

PendingAuthorise

• Direct-Debit-consents resource is initialised and pending for customer authorization.

Rejected

• Direct-Debit-consents resource is rejected due to any cancellation or interruption of customer authorization.

Authorised

• Direct-Debit-consents resource is successfully authorized; the TSP is allowed to request in-scope customer data before expiry.

Revoked

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

Summary:

Real-time Direct Debit API Specification for Hong Kong Open Banking.

Request Headers

Error Handling

Direct Debit Set Up

Summary:

This API is used to setup direct debit.

Request Body

Response Body

Direct Debit OTP Confirmation

Summary:

This API is used confirm Authorisation OTP for direct debit.

Request Body

Response Body

Direct Debit OTP Regeneration

Summary:

This API is used to request for new OTP for direct debit.

Request Body

Response Body

Direct Debit Authorisations Status

Summary:

This API is used to fetch direct debit authorisation status.

Request Body

Response Body

Direct Debit Instructions

Summary:

This API is used to send direct debit instructions.

Request Body

Response Body

Direct Debit Instructions Status

Summary:

This API is used to fetch direct debit instructions status.

Request Body

Response Body

Direct Debit Reports

Summary:

This API is used to fetch direct debit reports.

Request Body

Response Body