On this page
Treasury - Payment Pre-validation
- Version: v1
- Protocol: HTTPS
- URL Sandbox: Coming soon
- URL Production: **Live - please speak to your Client Integration contact**
On this page
Description
This service aims to enable customers to verify payee details prior to a payment being sent, ensuring our customers can make payments with greater confidence and helping to reduce the number of payments initiated with missing, incomplete or incorrect beneficiary account and name details.
Version History
Change log and release history:
Version | Release Date | Status | Description |
---|---|---|---|
v1 | Jan 2023 | Live | First release of Payment Pre-validation API |
v1 | Sep 2023 | Live | Enhanced of payment pre-validation API to support SWIFT |
Authenticating and Invoking
The communication between your application and the Treasury API infrastructure is based on server side TLS 1.2, PGP encryption and unique client credentials.
Security Credentials
Your application has three types of mandatory credentials:
- A Client ID and Client Secret for authentication.
- Message Level Encryption for encryption and non-repudiation.
- A Digital Signature to certify that only the organisation holding the private key is the one that has signed the payload.
Connectivity
Transport Layer Security - SSL Certificate
The connection between your organisation and HSBC relies on a security protocol to encrypt the communication. The protocol used is SSL (Secure Sockets Layer) via HTTPS over the Internet.
A SSL Digital Certificate is used when you request an HTTPS connection to HSBC. This certificate contains the public key needed to begin the automatic SSL handshake which involves the generation of shared secrets to establish a uniquely secure connection.
In summary, with an HTTPS connection, all communications are securely encrypted between the customer and HSBC. This is commonly known as Transport Layer Security (TLS) or (communication) channel security, where a "tunnel" is established between two parties (customer and HSBC) so as to ensure encryption and secure communication.
SSL certificates are essential for securing API communications and protecting sensitive data exchanged between HSBC and your organization. To ensure the integrity of the API requests and responses, please regularly check the validity of the SSL certificate. Given that SSL Digital Certificates have expiration dates and need to be renewed frequently, please make sure to verify the validity of the certificate, and its authenticity by checking the certificate's chain of trust in HTTPS connection. This chain of trust typically involves verifying that the certificate has been signed by a trusted Certificate Authority (CA). You will need to ensure your organization has maintained an up-to-date list of trusted CAs before attempting connectivity to our APIs service. Please contact your HSBC representative should you have any questions.
Client ID and Client Secret
These credentials are used for authentication and must be provided in the headers of the HTTP request every time you invoke the Treasury API services. This ensures only authorised and pre-approved organisations can access and utilise our API services.
Message Encryption
In addition to the Transport Layer Security, HSBC adopts additional security on the message being passed through the connection session - called Message or Data Security.
Message Level Encryption provides both your organisation and HSBC, enhanced security for API message payload by using public-key cryptography and asymmetric encryption.
Public key encryption involves a pair of keys known as a public key and a private key which are assigned to an entity that needs to authenticate its identity electronically, or to sign or encrypt data. The public key is published and the corresponding private key is kept secret. Data that is encrypted with the public key can be decrypted only with the corresponding private key.
Public key cryptography enables encryption, decryption and non-repudiation.
The Treasury 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.
Both you and HSBC need to exchange Public Key Certificate for Message Encryption purposes. This requires a separate pair of keys from the ones used for TLS authentication mentioned above.
You need to provide your HSBC Relationship manager or Client Service manager your public key during setup on our systems.
Where to get the Public Key Certificate?
- In order to use the Treasury API, first generate a set of Production Public and Private PGP Keys. To do this, you can use software such as OpenSSL and PGP.
- You receive HSBC's Public PGP Key via secure email as part of the HSBC Connect Digital setup process.
- Please contact your HSBC Sales or Client Service manager for further details.
How to use the Public Key Certificate?
- You must use HSBC's Public PGP Key to encrypt a message every time you send a request, and/or verify a signed message you have received from us. HSBC will use your Public PGP Key to do the same upon messages sent to you.
- For security purposes, you are required to renew your Public PGP Key every year.
Supported Algorithms
For asymmetric encryption, the HSBC Connect APIs support the RSA and Digital Signature Algorithm (DSA) algorithms.
Type | Format | Description |
---|---|---|
GnuPG/GPG | ascii/binary | Based on GnuPG - a complete and free implementation of the OpenPGP standard. |
PGP | ascii/binary | Based on the OpenPGP standards. |
Validations
The following validations will be performed on the Public key:
Type | Format | Description |
---|---|---|
Life Span | Min=6 months and Max= 2 years (from the date of upload) | validate PGP public key expiry date |
Bit Size | Min=2048, max=4096 | validate PGP Public key bit size |
Encryption Algorithms | RSA, DSA, El Gamal | validate PGP Public key algorithm |
Hash/Digist Algorithms | SHA224, SHA256, SHA384, SHA512 | validate hash algorithm |
Symmetric Algorithms | IDEA, AES_128, AES_192,AES_256, TRIPLE_DES, BLOWFISH | validate Symmetric algorithm |
Key Format | ASCII & BINARY | validate File Key Format |
Digital Signature
A Digital Signature provides the customer and HSBC an assurance of the origin, identity, and status of the message, as well as an acknowledged consent of the signer. Please sign the payload with your PGP private key as part of the encryption and base64 encoding process.