Variable Recurring Payments - UK - HSBC 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 HSBC UK Open Banking 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 to 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 in other words it facilitates the dynamic client registration (DCR) process on your behalf. This will register your app in the sandbox and generate your sandbox security credentials.

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

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

Pre-requisite: You’ve registered an account on 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/token_client_credentials_tls_curl

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/token_client_credentials_jwt_curl

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/token_client_credentials_response

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 the example below.

JWT Header:

@jwt_header_sample

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:

@jwt_payload_sample

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:

@client_assertion_jwt_sample

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

@jwt_signing_java_code_sample

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 Variable Recurring Payments API, in short `VRP Consent`. For other available `Consent` types please consult the API documentation.

The `VRP Consent` resource is used by a TPP to register an intent to initiate a Variable Recurring Payment. The request below is a typical example of VRP Consent, for all available properties please consult the API documentation.

@POST/vrp_consent_request_sample

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 `VRP Consent` resource:

@POST/vrp_consent_request_curl

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.

Also notice the header `x-jws-signature`, keep reading to find out how to generate one.

A successful response will look like:

@POST/vrp_consent_response_sample

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.

Header x-jws-signature

To put it simply, the value of the `x-jws-signature` header is a JWS Detached of content (body) of HTTP request or response. The purpose of this header is to allow to check whether the message has not been changed on it's way from the sender to the recipient.

JWS Detached generation algorithm is quite simple:

• Generate the standard signed JWT (JWS) where your HTTP body is used as JWT's payload.
• Remove the middle part (Payload) from JWS.
• Use the final string in the HTTP header `x-jws signature`.

Initiate Customer Authorisation

The ultimate goal of this step is to receive an `Auth Code` from HSBC which will allow a TPP 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:

@GET/authorize_request_jwt_payload_sample

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:

@GET/authorize_request_signed_jwt_sample

Authenticate & Authorise Consent

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

@GET/initiate_authorize_consent_curl

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 TPP's client interaction with HSBC server is interrupted until the customer completes (successfully or by rejecting) the authentication & consent authorisation steps within HSBCs domain.

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 TPP's domain:

@GET/tpp_authorize_callback_sample

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; TPPs 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 TPP 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/token_authorization_code_tls_curl

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/token_authorization_code_jwt_curl

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

Initiate Payment

This is the step where TPP will initiate the actual payment.

Using the `Access Token` from previous step, here is an example of a CURL command to initiate the Variable Recurring Payment:

@POST/initiate_vrp_curl

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

A typical successful response for initiating a domestic payment would look like this:

@POST/initiate_vrp_response

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

Postman Collection

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

• Sandbox - UK - Postman Collection

Please note, before you can continue make sure:

• You have read Step 1 and registered yourself on the portal.
• You have read Step 2 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 can 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_pisp_path` to `/obf/open-banking/v1.0/pisp`. This is market dependent, 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_PKCS8PEM` to your `Private Key` that was used to generate CSR during project creation steps 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_domestic_vrp_consent` to your `Variable Recurring Payment Consent` which is used as request body in `POST /pisp/domestic-vrp-consents`. This is market dependent, you will need to consult our swagger documentation for more details.
  NOTE: Debtor & creditor accounts used for payments are also channel specific. You can always appeal to Account Information API to find out which accounts are supported by sandbox for your channel of interest.

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.hsbc.com.bh`.
• 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 Domestic Payment 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 TPP'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. Initiate Payment.
6. Check Consent or Payment status.

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.

Return to top