Quick Start Guide - Build

Implementation Guide

This page will help you to:

Set up API Client
Prepare an API request payload and perform payload encryption
Generate and sign a client token (JWT)
Steps required to process a response

Setting up API Client

Pre-requisite: You need to setup HSBC Testing or Smart Sandbox. Refer to Environments at HSBC API Service.

To setup your organisation to use our APIs, use the following steps:

Download the sample JAVA code
Unzip the sample file and follow the instruction steps in the readme.txt file.

Making an API Request

For each request, prepare the following:

Prepare the plain HTTP request body in JSON structure.
Encrypt the HTTP request body using HSBC's Public Key.
Generate Client Token (JWT).
Add the Signed JWT (JWS) in the relating Authorization request header.
Add Correlation ID header to uniquely identify the request in your system and submit.

The following section contains an implementation guide with examples.

Step 1 - Prepare the request body

Use the API reference document to prepare the payload based on the required format for your specific end-point.

Request body examples are provided against each end-point in the API reference documentation.

Step 2 - Encrypt the HTTP request Body

Encryption requirements

Component	Description	Remark
plainJsonString	Plain HTTP request body (In JSON structure)	Refer to the API Reference Page for each endpoint.
encryptionKey	Public Key Certificate issued by HSBC	Public Key provided by HSBC during key exchange.

Code example

To understand how to construct an Encrypted Message, let's take the Java program below as an example to describe all the required components:
Convert your plain payload to string format.

2.1 Stringnify your plain payload.

2.2 Use the IOUtils.toInputStream tool to convert the Payload to inputStream.

2.3 Retrieve HSBC's Public Key as the encryptor.

2.4 Use HSBC's Public Key to encrypt the plain payload inputStream.

2.5 Encode the crypto text to base64.

If you are not familiar with Message Level Encryption at HSBC, refer to Knowledge article: Message Level Encryption.

Next, let's look into the following example to see how to generate the JWS.

Step 3 - Generate and Sign the Client Token

JWT components

The below table defines the fields to be provided in the JWT, all fields are mandatory. Note, for JWT field definitions please see the Securing a Connection page:

Code	Name	In	Example
typ	Token Type	JWT header	MUST be set to “JWT”
kid	Key Id	JWT header	4EC693BF69A4AED2
alg	Algorithm	JWT header	PS256
ver	Version	JWT header	1.0 - MUST be set as "1.0"
jti	JWT ID	JWT payload	74760410-f963-11e8-b2a3-1bb26e1e5b69
iat	Issued At	JWT payload	1565150776
sub	Subject	JWT payload	HSBC Profile ID
aud	Audience	JWT payload	HSBC.MKT
payload_hash	Payload hash value	JWT payload	92a772406ac5d3...
payload_hash_alg	Payload hash algorithm	JWT payload	RSASHA256

Code example

Following java example can be used to describe the required JWT components:

3.1 Build the JWT structure.

3.2 Generate hash code for encrypted request payload from step 2.

3.3 Form the JWT Header

3.4 Generate and Sign the JWT (JWS)

Next, let's add the JWS to the HTTP Header

Step 4 - Add the Signed JWT (JWS) in HTTP Header

Add the JWS to the Authorization header:

Authorization=JWS eyJ2ZXIiOiIxLjAiLCJraWQiOiJBNjI4RjhBRDY3NERCQz..

Next, add the remaining headers as per the API reference documentation for your specific end-point

Step 5 - Add remaining headers and submit

Follow the API reference documentation for your specific end-point to determine if any additional header values are required.

Correlation ID is a UUID generated by your system to uniquely identify each request.

Processing a Response

Responses are returned with the relating HTTP code and an encrypted response message.

Processing a Response

Steps to process a response:

A response message will be returned from HSBC with a success or failure status code and description.
For a successful response, the payload will provided in an encrypted and encoded envelope.
Use Base64 encoding to decode the response message payload.
Decrypt the decoded crypto text with your private key.
The payload response body will be defined in the API Reference document for your chosen end-point.

Typical encrypted and encoded response envelope:

In the unlikely event of a failure with our crypto service, a plain JSON response with an error code will be returned.

Related article: Response Code and Formats

Code example

The following Java program provides an example of how to decrypt the response body:

1. Use the base64 decode crypto text from HSBC.

2. Create the PGPObjectFactory Object.

3. Retrieve your Private Key as the decryption key.

4. Obtain the plain text by using your private key to decrypt the crypto text from HSBC’s response.