API Operations

The v3 /forms API has the following operations:

Views

The the Customer Onboarding and Credit Application API contain a number of views that represent stages of a customer onboarding or credit application.

Creating a New Request

The following process is cycled through to progress a Customer Onboarding or Product Application workflow:

1. Request a new form and start a session using GET /form/{form-type}. E.g. GET /form/customer_onboarding.
2. A form will be returned containing the first view and an form-instance-id.
3. Use the currentViewId to identify the next view in the response that should be completed.
4. Submit the data (including answers to the view) using PUT /form/{form-type}/{form-instance-id} The API will then respond as per step 1.

Once the required views have been completed, a review of answers is provided before submitting the form:

1. Submit the full set of data using POST /form/{form-type}/{form-instance-id}. This will execute all the business rules associated with the form and respond with a new 'review' view.
2. Submit the full set of data with the 'currentViewId' set to 'review' using POST /form/{form-type}/{form-instance-id}.

Put or Post Request Body

For the PUT and POST method calls please prepare the payload associated with the required action. Once the payload is prepared follow the below steps to encrypt and encode before submitting:

• Sign the payload with your private key then encrypt the payload using the bank public key.
• Encode the encrypted payload in Base64 encoding representation.
• Populate the encoded payload in the JSON field encryptedRequestBase64

Example request body:

{
  "encryptedRequestBase64": "ewogICAgImRhdGEiOiB7CiAgICAgICAgInRlc3RBdHRyaWJ1dGUiOiAidGVzdFZhbHVlIgogICAgfQp9"
}

Response Body

Responses from HSBC will be Base64 encoded and encrypted with your PGP public key. Please follow the below steps to decode and decrypt the response payload:

• Extract the value from JSON field encryptedResponseBase64
• Decode the payload in Base64 encoding representation
• Decrypt the payload using your private key

Example encoded and encrypted response body:

{
  "encryptedResponseBase64": "ewogICAgImRhdGEiOiB7CiAgICAgICAgInRlc3RBdHRyaWJ1dGUiOiAidGVzdFZhbHVlIgogICAgfQp9"
}

Error Handling

Error handling uses a modified (extended) RFC 7807 message structure. An example is given below.

Error Example:

{
    "type": "https://example.com/probs/client-id-missing",
    "title": "Client Id missing",
    "status": "400",
    "detail": "Client Id is missing. Request header not set.",
    "instance": "d72b7d9b-ccd9-4f98-8fb8-dbb3067effc3",
    "supportTeam": "Onboarding Support",
    "supportContactEmail": "onboardingsupport@hsbc.co.uk",
    "dateTime": "2021-09-16T09:50:17.108"
}

Return to top

Security and Authentication

This page will help you to:

• Understand the steps required to secure and encrypt a connection with HSBC
• View the fields to be provided in the JWT header and payload
• See code examples of how to generate the required JSON Web Token (JWT)

Security Overview

The following measures and their components are required to establish a secure connection between HSBC the API consumer:

Transport Layer Security

To encrypt the communication, the connection between the partner and HSBC uses Transport Layer Security (TLS) via HTTPS as a security protocol. TLS is a cryptographic protocol designed to provide communications security over a computer network.

When the partner requests a HTTPS connection to HSBC, a Digital Certificate is required. This certificate contains the cryptography needed to begin the automatic Secure Sockets Layer (SSL) handshake which involves the generation of shared secrets to establish a uniquely secure connection between the partner and HSBC.

Please ensure your organisation has a valid Digital Certificate from a recognised Certificate Authority before attempting connectivity to our APIs.

Message Level Encryption

In addition to the Transport Layer Security, HSBC adopts additional security on the message being passed through the connection session. Using public-key cryptography and asymmetric encryption, Message Level Encryption provides both your organisation and HSBC with enhanced security for the API message payload.

Public key encryption involves a pair of keys known as a public key and a private key. These keys are assigned to an entity that needs to authenticate its identity electronically, or to sign or encrypt data. Each public key is published and the corresponding private key is kept secret. Data that is encrypted with the public key can only be decrypted with the corresponding private key.

Public key cryptography enables encryption, decryption and non-repudiation. HSBC's APIs support asymmetric encryption that uses a public key to encrypt data and a private key to decrypt data. The public key is available in a trusted certificate, whereas the private key is confidential and not shared.

For Message Encryption purposes, both your organisation and HSBC will need to exchange Public Keys so both parties can decrypt and encrypt messages via the API communication. 

PGP Encryption

PGP is an encryption program that provides cryptographic privacy and authentication for data communication. PGP is used for signing, encrypting, and decrypting texts, e-mails, files, directories, and whole disk partitions and to increase the security of e-mail communications.

What is the purpose?

For API Message Encryption purposes, the Public PGP Keys have to be exchanged between the API Consumer (Client) and HSBC the API Provider (HSBC).

Where to get a set of PGP keys?

Clients can generate their own Private Key / Public Key pair using a key generation tool such as GnuPG or GPG.

Public PGP Key Specification:

• Signing algorithm: 2048-bit
• RSA Hashing algorithm: SHA-256

Once your Certificate is ready, contact your HSBC Client Integration contact to trigger the Key Exchange Procedure.

How to use the PGP keys?

The Client uses HSBC's Public Key to encrypt a message every time it sends to HSBC. The Client verifies HSBC's digital signature every time a message is received from HSBC. HSBC uses the Client's Public Key to do the same upon messages sent and received from the Client. 

For security purposes, HSBC's Public Key is renewed every year and a Certificate Renewal process will be triggered.

Key Storage and Duration of Validity

Component	Storage	Validity
Client's Private Key	The Private Key should be maintained and handled with the most secure approach possible. The most common and yet secure approach is: key password - Do not save the password in plain text or hard-coded in an application. We recommend to encrypt it by any Password Encryption Tools/ key storage - Store inside a password-protected key repository, such as JKS or PKCS12 keystore. The Keystore password should also be encrypted.	There is no Validity Period. However, if  the Client suspects there is a chance that the key is leaked, or any other security reason, a new Private Key and its associated Public Key should be generated.
Client's Public Key	Since the Public Key is publicly distributed, a moderately secure storage approach is acceptable. The Client can store the physical file in any machine's file system, or for centralised key management -  store all keys and certificates in one single key repository.	For a self-signed PGP Public key, the same condition as above applies. However, the validity period of a CA-signed Certificate is depended on the purchase plan of the issuing CA. The most common standard is 1 to 2 years.
HSBC's Public Key	Same as above.	The validity period is usually 1 Year plus 1 to 2 months extra. The extra period is a buffer to enable a client to switch a "to-be-expired" certificate to a new one during the PGP Key Renewal Process.

API Authentication - JWT Validation

API Authentication is performed using a signed JSON Web Token (JWT). The token must be provided in the header of the HTTP request every time you invoke HSBC's API services. This ensures only authorised and pre-approved organisations can access and utilise our API services.

The JWT is generated by the partner, not provided by HSBC. There are many utilities available that can provide JWT generation and validation logic for all commonly used programming languages. The following example uses the "io.jsonwebtoken" java library.

Building the JWT

What you will need:

• Partner Private Encryption Key
• Partner Public Encryption Key alias
• Partner Profile ID

The Partner Profile ID is the identifier HSBC provided you during the on-boarding process.

The Private Key is part of your Encryption Key Pair. The Public Key should be shared with HSBC as part of the partner on-boarding process.

For sandbox access, test encryption keys and profile ID will be provided as part of the sandbox project creation.

Code example

The below code provides a JWT example in Java:

// Build HSBC JWT Token
Map<string, object=""> claims = new HashMap<>();
long nowSeconds = System.currentTimeMillis() / 1000;

//set partner profile id
claims.put("sub", "GBHBEUR69CUST1APIT");

//set customer profile id and JWT body
claims.put("iat", nowSeconds);
claims.put("aud", "baas");
claims.put("jti", jwtId);
claims.put("payload_hash_alg", "RSASHA256");
//Generate hash code for request payload and put into JWT Token
claims.put("payload_hash", "151202eac315f1323a9ff...");

//set JWT header
Map<string, object=""> header = new HashMap<string, object="">();
header.put("typ", "JWT");
header.put("key_typ","PGP");
header.put("kid", " D4EFEE13D91D5D42s ");
header.put("alg", "PS256");
header.put("ver", "1.0");

String token = Jwts.builder().setHeader(header).setClaims(claims)
.signWith(clientPrivateKey, SignatureAlgorithm.PS256).compact();

Fields in the JWT Header

The below table defines the fields (“claims”) that should be put inside the JWT header:

Note: We recommend the PS256, PS384, and PS512 algorithms over the other RSA algorithms. The PKCS#1.5 padding scheme (RS256, RS384, and RS512) does not provide the desired level of security and generally should be replaced by the PSS padding scheme.

Example structure:

{
    "typ": "JWT", 
    "kid": "A9248D0E4A463426",
    "alg": "PS256"
    "ver": "1.0"
}

Fields in the JWT Payload

The below table defines the fields (“claims”) that should be put inside the JWT payload:

Note, the OBO claim is not provided for the first stage of the Customer Onboarding as at this point in the process the customer identifier has not been created. The OBO claim should be provided for subsequent stages of the Onboarding and Lending application, following successful completion of the first stage where the Customer Identification Number (CIN) has been created and returned.

Example structure - stage 1:

{
    "jti": "5ccfd3a0-36a1-11ea-b780-eeee0af2723c",
    "iat": 1578987726,
    "sub": "PARTNER-ID",
    "aud": "baas",
    "payload_hash": "a00ccb...",
    "payload_hash_alg": "RSASHA256"
}

Example structure - remaining stages of Onboarding and Lending application:

{
    "jti": "5ccfd3a0-36a1-11ea-b780-eeee0af2723c",
    "iat": 1578987726,
    "sub": "PARTNER-ID",
    "aud": "baas",
    "payload_hash": "a00ccb...",
    "payload_hash_alg": "RSASHA256",
    "obo":{
         "sub":"USCIN:000000001"
    }
}

Return to top

This page will help you to:

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

Making an API Request

For each request, prepare the following:

1. Prepare the plain HTTP request body in JSON structure. 
2. Encrypt the HTTP request body using HSBC's Public Key.
3. Generate Client Token (JWT).
4. Add the Signed JWT (JWS) in the relating Authorization request header.
5. 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
plainText	Plain HTTP request body (In JSON structure)	Refer to the API Reference Page for each endpoint.
encryptionKey	Public Key issued by HSBC	Public Key provided by HSBC during key exchange.

Steps to encrypt the message payload:

• Use the request body prepared in step 1.
• Use the HSBC Public key to encrypt the payload.
• Encode the encrypted payload using Base64 representation.

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:

//#2.1 Your plain payload prepared and put into string
public String encryptPlainText(List<PGPPublicKey> publicKeys, String plainText, boolean armor,
                               boolean withIntegrityCheck, boolean isMasterKey)
    throws PGPException, IOException {
  ByteArrayOutputStream out = new ByteArrayOutputStream();
  OutputStream opOut;
  if (armor) {
    opOut = new ArmoredOutputStream(out);
  } else {
    opOut = out;
  }
  ByteArrayOutputStream byteArray = new ByteArrayOutputStream();

//#2.2 Use IOUtils.toInputStream to convert Payload to inputStream.  
InputStream inputStream = IOUtils.toInputStream(plainText);
  PGPLiteralDataGenerator generator = new PGPLiteralDataGenerator();
  OutputStream outputStream = generator
      .open(byteArray, PGPLiteralData.BINARY, PGPLiteralData.CONSOLE, inputStream.available(),
          new Date());
  Streams.pipeAll(inputStream, outputStream);
  outputStream.close();
  JcePGPDataEncryptorBuilder c = new JcePGPDataEncryptorBuilder(SymmetricKeyAlgorithmTags.AES_256)
      .setWithIntegrityPacket(withIntegrityCheck).setSecureRandom(new SecureRandom())
      .setProvider("BC");

//#2.3 Retrieve HSBC's Public Key for encryption
  PGPEncryptedDataGenerator dataGenerator = new PGPEncryptedDataGenerator(c);
  PGPPublicKey encryptionKey = null;

//#2.4 Use HSBC's Public Key to encrypted plain payload inputStream
  Iterator keyIter = publicKeys.iterator();
  while (keyIter.hasNext()) {
    PGPPublicKey key = (PGPPublicKey) keyIter.next();
    if (key.isEncryptionKey() && (!key.isMasterKey() || isMasterKey)) {
      encryptionKey = key;
    }
  }
  if (encryptionKey == null) {
    throw new IllegalStateException("matching encrypted data not found");
  }
  JcePublicKeyKeyEncryptionMethodGenerator d =
      new JcePublicKeyKeyEncryptionMethodGenerator(encryptionKey)
          .setProvider("BC").setSecureRandom(new SecureRandom());
  dataGenerator.addMethod(d);
  byte[] bytes = byteArray.toByteArray();
  try (OutputStream dbOut = dataGenerator.open(opOut, bytes.length)) {
    dbOut.write(bytes);
    dbOut.close();
    opOut.close();

//#2.5 Encode crypto text to base64
    return Base64.toBase64String(out.toByteArray());
  }

2.1 Stringnify your plain payload.

2.2 Use IOUtils.toInputStream 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.

Next, let's follow an example 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	JWT - MUST be set to “JWT”
kid	Key Id	JWT header	900864F8C11EB743
alg	Signing 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	Issue At	JWT payload	1565150776
sub	Subject	JWT payload	PARTNER-ID
aud	Audience	JWT payload	baas
payload_hash	Payload hash value	JWT payload	1dab559f1f4bf4f3ca...
payload_hash_alg	Payload hash algorithm	JWT payload	RSASHA256

Steps to prepare the JWT:

• Build the JWT structure using the provided field structure.
• Generate hash code for the encrypted request payload from step 2.
• Form the JWT Header.
• Generate and Sign the JWT (JWS).

Code example

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

//3.1 Build the JWT structure
Map<string, object=""> claims = new HashMap<>();
long nowSeconds = System.currentTimeMillis() / 1000;
claims.put("jti", jwtId);
claims.put("iat", nowSeconds);
claims.put("aud", "baas");
claims.put("sub", "PARTNER-ID");

//3.2 Generate hash code for request payload and put into JWT Token
claims.put("payload_hash", "151202eac315f1323a9ff...");
claims.put("payload_hash_alg", "RSASHA256");

//3.3 Set JWT header
Map<string, object=""> header = new HashMap<string, object="">();
header.put("typ", "JWT");
header.put("key_typ","PGP");
header.put("kid", " D4EFEE13D91D5D42s ");
header.put("alg", "PS256");
header.put("ver", "1.0");

//3.4 Generate and Sign the JWT (JWS)
String token = Jwts.builder().setHeader(header).setClaims(claims)
.signWith(clientPrivateKey, SignatureAlgorithm.PS256).compact();

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:

1. For a successful response, the payload provided will be encrypted and Base64 encoded.
2. Use Base64 encoding to decode the response message payload.
3. Decrypt the decoded payload with your private key.
4. The payload response body will be defined in the API Reference document for your chosen end-point.

Typical encrypted and encoded response envelope:

{"encryptedResponseBase64": "ewogICJkYXRhIjoge1JlcXVlc3QgYm9keQ=="}

Code example

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

//#1 Use base64 decode crypto text from HSBC
  String epicStrNew = new String(Base64.decode(encryptedStr));
  BufferedInputStream dataStream = new BufferedInputStream(IOUtils
      .toInputStream(epicStrNew));
  InputStream decoderStream = PGPUtil.getDecoderStream(dataStream);

//#2 Build the PGPObjectfactory Object
  PGPObjectFactory pgpObjectFactory =
      new PGPObjectFactory(decoderStream, keyFingerPrintCalculator);
 
  PGPEncryptedDataList pgpEncryptedDataList =
      (PGPEncryptedDataList) pgpObjectFactory.nextObject();
 
  // find the matching public key encrypted data packet.
  PGPPublicKeyEncryptedData pgpPublicKeyEncryptedData = null;

//#3 build decryptor factory
  PublicKeyDataDecryptorFactory dataDecryptorFactory = null;
  for (Object pgpEncData : pgpEncryptedDataList) {
    PGPPublicKeyEncryptedData pkEnc = (PGPPublicKeyEncryptedData) pgpEncData;
    for (PGPPrivateKey privateKey : privateKeys) {
      if (pkEnc.getKeyID() == privateKey.getKeyID()) {
        pgpPublicKeyEncryptedData = pkEnc;
        dataDecryptorFactory = new JcePublicKeyDataDecryptorFactoryBuilder().setProvider("BC")
            .build(privateKey);
        break;
      }
    }
  }
 
  if (pgpPublicKeyEncryptedData == null || dataDecryptorFactory == null) {
    throw new IllegalStateException("matching encrypted data not found");
  }
 
  InputStream clear = pgpPublicKeyEncryptedData.getDataStream(dataDecryptorFactory);

//#4 Get the plain text by using your private key to decrypt the crypto text
  PGPObjectFactory plainFact = new PGPObjectFactory(clear, new JcaKeyFingerprintCalculator());
  Object message = plainFact.nextObject();
 
  ByteArrayOutputStream actualOutput = new ByteArrayOutputStream();
  Streams.pipeAll(((PGPLiteralData) message).getInputStream(), actualOutput);
  actualOutput.close();
  clear.close();
  // check data decrypts okay
  if (pgpPublicKeyEncryptedData.verify()) {
    return new String(actualOutput.toByteArray());
  }
  throw new IllegalStateException("Enc data is invalid!");
}

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.

Return to top

Getting started

To experiment with the Corporate Sandbox, first create a project. This generates the Client Credentials and Encryption Keys required for authentication when calling the Sandbox APIs.

To create your first project, please follow the Dev Hub link found in the top right of the screen in the main navigation.

The Dev Hub is the central location to manage your Sandbox projects and allow administrators to add/remove members to your organisation within the Developer Portal.

See also:

Detailed User Guide for Sandbox projects

Download the Sandbox Toolkit

Detailed Guide to Sandbox Data Management

Sandbox Response

We support two types of response in the Corporate Sandbox for this API:

Mock Sandbox returns a static file-based mock response to the requested endpoint. These endpoints can be used for rapid testing whilst you are preparing your encryption module to use with the smart sandbox.

• The keyword mock is present in the URL to route the call to the mock sandbox.
• The mock sandbox requires only Base64 encoding of the response payload.
• PGP keys and client credentials are not required.

Mock Sandbox URL: https://sandbox.corporate-api.hsbc.com/mock/{version}/{api endpoint name}

Example cURL script:

curl --location --request GET 'https://sandbox.corporate-api.hsbc.com/mock/v1/form/customer_onboarding' \
--header 'Content-Type: application/json' \
--header 'Authorization: encrypted-encoded-signed-token' \
--header 'x-HSBC-Request-Correlation-Id: mock-correlation-id-for-testing'

Smart Sandbox is a full testing environment. It returns a validated response from the database based on the request body content.  

• Smart Sandbox maintains the state of the data, i.e. new payment inputs, etc.
• It uses a JWT based security model and PGP encryption that replicates our production APIs.
• It requires message signing, encryption and Base64 encoding of the request and response payload.
• Encryption keys are provided in your Sandbox Project.
• The password for the client private key is available in client-pgp-keys.info file in your downloaded encryption keys zip file.

Smart Sandbox URL: https://sandbox.corporate-api.hsbc.com/{version}/{api endpoint name}

Smart Sandbox Accounts Information

The following test accounts have been added to the Smart Sandbox default dataset. Please use these accounts when preparing your test payload.

Sandbox Test Accounts

Currently there are two Sandbox Customers and Accounts defined in the default data that is created for your sandbox project.

Customers created via successful completion of the onboarding flow will be added to the sandbox and can be queried using the OBO query sandbox management API:

https://sandbox.corporate-api.hsbc.com/v1/form/customer_onboarding/obo_profiles

Postman Collection

A postman collection is available to download using the below shortcut to help get started with the smart sandbox:

Please either:

1. View the collection as read-only in the HSBC workspace, changes applied by HSBC will be visible.
2. Fork the collection for your own use - note, changes made by HSBC will not be visible.
3. Download the collection for use in desktop Postman.

Please note, a registration to web postman is required.

Return to top