API Reference

The Trade Finance API are structured around REST with resource-oriented URLs, which accepts and returns JSON-encoded request bodies and responses, with standard HTTP response codes and authentications.

Authentication

Today, API Security is a key priority for protecting important data, especially within Financial Services. Here at HSBC, when it comes to data security, our market leading API Developer platform goes further than just industry best practice.

The Trade Finance APIs uses JSON Wen Token to authenticate requests, which carries your identity, request timestamp, payload and your signature for non-repudation.

Errors

Trade Finance API returns conventional HTTP response codes to indicate status of your request.

The diagram below illustrates how Authentication, Authorisation, TLS and Message Level Encryption combined, stack up to provide you with world class API Security.

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.

 Digital Identity

Digital Signature is used to ensure that your API requests are not tampered with and originate from the expected source. It composes of:

• Message Level Encryption
• API Authentication and authorisation 

Message Level Encryption

Message Level Encryption (MLE) ensures Data privacy of messages either in transit or at rest and involves a PGP handshake and encryption key exchange.

HSBC uses Message Level Encryption for our Corporate and Institutional APIs to ensure the highest level of security is applied to the data exchanged by our APIs.

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.

We know that MLE carries an overhead, as both parties need to encrypt and decrypt both request and response messages, however this practice has the important advantage of non-repudiation, giving assurance to both sender and receiver that the message has not been modified.

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:

1. Signing algorithm: 2048-bit
2. 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 and Authorization

All our APIs confirm the identity of all requestors, this is Authentication.

All our APIs are called and activated only by trusted systems, this is Authorisation.

Both of the above are handled during the initial exchange between the Client Application and HSBC's API Gateway.

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:

1. Client Private Encryption Key
2. Client Public Encryption Key alias
3. Client Profile ID

The Client 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:

Fields in the JWT Header

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

Example structure:

Fields in the JWT Payload

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

Example structure:

The following Signature Algorithms are supported:

1. PS256 (preferred)
2. RS256

The chosen algorithm will be the used for the message payload decryption (request to HSBC) and encryption (response from HSBC).

Quick Start Guide:

Our APIs let you access financial solutions and approved customer data, then seamlessly implement them into your products and services.

Quick Start Guide

1. Register

Our quick registration process means you can start browsing our APIs straight away.

2. Explore

Get straight to work with technical documents and tools such as Security Schemes, Sample Client and Sandbox Access, etc. 

3. Build 

Discover our documentations with Step-by-step tutorial for your successful implementation

4. Launch

Transform your business process with HSBC's global network of products and services

Back to API home page

Bank Guarantee

Bank Guarantee status for Financial Institutions

B2B Buy Now, Pay Later

Support revenue growth and increase sales velocity by embedding financing solutions

Receivable Finance

Submit invoices or credit notes directly to HSBC in real-time

Trade Working Capital

Request Trade Working Capital loan for buyers and sellers.

Supply Chain Finance

Bank Guarantee status for Financial Institutions

Import Letters of Credit

Submit applications/amendments/enquiries for Import Letters of Credit

Import Collection

Seamlessly send enquiries to HSBC about Export Collection bills received by HSBC

Export Letters of Credit

Seamlessly send enquiries to Export Letters of Credit (LC/ DC) advised by HSBC

Export Collection

Seamlessly send enquiries to Import Collection bill’s received by HSBC

 

Related articles

Implementation Guide

Homepage: Corporate Banking

API Architecture Blog: Why we're automating API governance

Return to top