Trade Finance - Seller Loans
- Version: v3
- Protocol: HTTPS
- URL Pre-Prod Test (UAT): Please speak to your Client Integration contact
- URL Production: Please speak to your Client Integration contact
On this page
Description
In this document, you'll find the steps your organization needs to take to use our API services. Also in this guide are details of request and response messages used to support your organization’s integration.
The intended audience for this document are Technical Architects, Development Engineers, Test Engineers, and Operation & Maintenance Engineers involved in development and support of your organization’s integration.
Setting up our API Services is best completed with the assistance of your organization’s IT team, or someone with experience and knowledge of application programming interfaces. This should include experience with - JSON payloads and security and public key infrastructure (PKI).
Quick Start Guide:
Click on the Left Menu to explore the following topics:
| Topics | This page will help you to: | References |
|---|---|---|
| API Specification |
|
|
| Securing a Connection |
|
|
| Making an API Request |
|
|
| Response Codes and Formats |
|
|
| Sandbox Access |
|
Coming soon.* *The sandbox environment for the latest version is not available yet. However, you may try out earlier version. |
Version History
Change log and release history:
| Version | Release Date | Status | Description |
|---|---|---|---|
| v1 | December 2021 | To be deprecate | Seller Loans - First Release |
Go-Live preparations
This page will help you to:
- Contact HSBC Client Integration Team
- Generate your credentials required secured connections
- Steps for credentials exchange
Generate Credentials
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. |
Contact HSBC Client Integration Team
If API connectivity suits your business needs, you’ll need to contact HSBC Client Integration Team to setup your organization for using our API services.
Exchange Credentials
Once setup is complete, you’ll receive a unique profile for your organization i.e. Profile ID, via secure email. These profiles are used to construct the authentication token which must be provided in the header of the HTTP request every time you invoke our APIs.
Both yourself and HSBC will need to securely exchange the Public Key Certificate for Message Encryption purposes. As part of the setup you’ll receive HSBC's public key via secure email.
