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 and the API consumer:

Transport Layer Security

To encrypt the communication, the connection between the customers 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 customer 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 customer 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 customer, 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:

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

The Customer 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 customer 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 customer profile id and JWT body
claims.put("sub", "PC000012345");
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("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:

Example structure:

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

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 - see Endpoints menu.

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 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	PC000012345
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", "PC000012345");

//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("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 representation to decode the response message payload.
3. Decrypt the decoded payload with your private key.
4. The payload response body is defined in the Endpoints specification for your chosen API.

Typical encrypted and encoded response envelope:

{
  "profileId": "PC12345678",
  "referenceId": "b7e0fdacd8bd",
  "statusCode": "ACCP",
  "statusDesc": "Accepted Technical Validation (L2)",
  "reportBase64": "PFJlc3BvbnNlPg0KICA8UGF5bWVudElkPmI3ZTBmZGFjLWQ4YmQtNDk1MC1iZDNGljSWQ+UEMxMjM+"
}

Code example

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

//#1 Decode the encoded response using Base64
  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. Decode the encoded response using Base64.

2. Create the PGPObjectFactory Object. 

3. Retrieve your Private Key as the decryption key.

4. Use your private key to decrypt the encrypted response.

Return to top

Summary

• Payment initiation for asynchronous processing of bulk transactions with instant acknowledgement.
• Supports up to 500 instructions per API payload.
• Request payload should be provided in the ISO 20022 XML version 3 (pain.001.001.03) format.
• The response provided by the API is a technical status on file validation.
• The client should call the payment status enquiry API to enquire on the eventual payment processing status.
• For UK Faster Payments, each batch will incur additional batch fees including if a single transaction is in the batch

API Request Header

Prepare the header parameters as shown below:

API Request Body

ISO pain.001.001.03 Specification: HSBC_pain.001.001.03_HighValuePayment

How to prepare the request payload.

• Prepare the payload format. Maximum number of instructions for bulk payment request is 500.   
• Sign the message with your private key and encrypt the payload using the bank public key.
• Encode the encrypted payload in BASE64 encoding representation.
• Populate the encoded payload in the JSON field paymentBase64

Example encoded request payload:

{
"paymentBase64":
"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxEb2N1bWVz="
}

API Response Body

The successful response body will contain the following fields:

Example response payloads:

200 - ACTC (Technical Acceptance)

{
   "referenceId":"b7e0fdac-d8bd-4950-bd3a-38fac5cc25df",
   "profileId":"PC12345678", 
   "statusCode":"ACTC",
   "statusDesc":"Accepted Technical Validation (L1) - Authentication and syntactical and semantical validation are successful.",
   "responseBase64":"+DQogIDxTdGF0dXNDb2RlPlNVQk1JVFRFRDwvU3RhdHVzQ28U3RhdHVzRGVzYz5QYXltZW5"
}

200 - ACCP (Accepted)

{
   "referenceId":"b7e0fdac-d8bd-4950-bd3a-38fac5cc25df",
   "profileId":"PC12345678", 
   "statusCode":"ACCP",
   "statusDesc":"Accepted Instruction Validation (L2) - Description: Preceding check of instruction validation was successful. Customer profile check was also successful.",
   "responseBase64":"+DQogIDxTdGF0dXNDb2RlPlNVQk1JVFRFRDwvU3RhdHVzQ29kZT4gIA0KICA8U3RhdHVzRZhZm9"
}

200 - PART (Partially Accepted)

{
   "referenceId":"b7e0fdac-d8bd-4950-bd3a-38fac5cc25df",
   "profileId":"PC12345678", 
   "statusCode":"PART",
   "statusDesc":"Partially Processed - A number of transactions have been accepted, whereas another number of transactions have not yet achieved 'accepted' status.",
   "responseBase64":"+DQogIDxTdGF0dXNDb2RlPlNVQk1JVFRFRDwvU3RhdHVzQ29kZT4gzRGVzYz5QYXlGtzaHZhZm9"
}

How to process the response payload:

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

The decoded and decrypted Bulk payment initiation payload content will be provided as an acknowledgement confirming if the file validation has been successful.

Return to top

Summary

• Payment initiation for asynchronous processing a single transaction with instant acknowledgement.
• Request payload should be provided in the ISO 20022 XML version 3 (pain.001.001.03) format.
• The response provided by the API is a technical status on file validation.
• The client should call the payment status enquiry API to enquire on the eventual payment processing status.
• For Indian Rupee (INR) vostro accounts a special header identifying Cross Border remittance is required. For this scenario please add Payment Type of CBRR in the header. This header is not required for other currency, account or payment types.
• This API should not be used for UK Faster payments and incurs an additional batch fees if used. Please use the single payment initiation with instant settlement API for any single UK Faster payments.

API Request Header

Prepare the header parameters as shown below. Please note the additional required header value for Cross Border remittance:

API Request Body

ISO pain.001.001.03 Specification: HSBC_pain.001.001.03_HighValuePayment

How to prepare the request payload.

• Prepare the payload format.
• Sign the message with your private key and encrypt the payload using the bank public key.
• Encode the encrypted payload in BASE64 encoding representation.
• Populate the encoded payload in the JSON field paymentBase64

Example encoded request payload:

{
"paymentBase64":
"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxEb2N1bWVz="
}

API Response Body

The successful response body will contain the following fields:

Example response payloads:

200 - ACTC (Technical Acceptance)

{
   "referenceId":"b7e0fdac-d8bd-4950-bd3a-38fac5cc25df",
   "profileId":"PC12345678", 
   "statusCode":"ACTC",
   "statusDesc":"Accepted Technical Validation (L1) - Authentication and syntactical and semantical validation are successful.",
   "responseBase64":"+DQogIDxTdGF0dXNDb2RlPlNVQk1JVFRFRDwvU3RhdHVzQ28U3RhdHVzRGVzYz5QYXltZW5"
}

200 - ACCP (Accepted)

{
   "referenceId":"b7e0fdac-d8bd-4950-bd3a-38fac5cc25df",
   "profileId":"PC12345678", 
   "statusCode":"ACCP",
   "statusDesc":"Accepted Instruction Validation (L2) - Description: Preceding check of instruction validation was successful. Customer profile check was also successful.",
   "responseBase64":"+DQogIDxTdGF0dXNDb2RlPlNVQk1JVFRFRDwvU3RhdHVzQ29kZT4gIA0KICA8U3RhdHVzRZhZm9"
}

200 - PART (Partially Accepted)

{
   "referenceId":"b7e0fdac-d8bd-4950-bd3a-38fac5cc25df",
   "profileId":"PC12345678", 
   "statusCode":"PART",
   "statusDesc":"Partially Processed - A number of transactions have been accepted, whereas another number of transactions have not yet achieved 'accepted' status.",
   "responseBase64":"+DQogIDxTdGF0dXNDb2RlPlNVQk1JVFRFRDwvU3RhdHVzQ29kZT4gzRGVzYz5QYXlGtzaHZhZm9"
}

How to process the response payload:

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

The decoded and decrypted payment initiation payload content will be provided as an acknowledgement confirming if the file validation has been successful.

Return to top

Summary

• Currently supporting UK Faster Payments, SEPA Instant Payments, US Real Time Payments, TH PromptPay, and JP RTP.
• For UK Faster Payments (FPS) and SEPA Instant Payments, the API operates synchronously. This means payment settlement is confirmed instantly with the beneficiary bank (status: ACSC – Accepted Settlement Completed). No further action is required unless a “Pending” response is received. In such cases, settlement can be tracked using the Payment Status Enquiry API, and for FPS, real-time notifications (webhook) are also available.
• For US RTP and TH PromptPay, the API confirms that HSBC has accepted the payment instruction (ACCP – Accepted Instruction Validation). Final settlement (status: ACSC – Accepted Settlement Completed) can be monitored via the Payment Status Enquiry API or by subscribing to real-time notifications (webhook).
• UK Faster Payments are subject to a default limit of 1 transaction per second (TPS). Please ensure your systems are configured to comply with this limit. For higher throughput needs, please engage with your HSBC implementation teams.
• Duplicate checks are enabled by default to safeguard against repeated payment instructions. For further details or to discuss tailored requirements, please contact your HSBC representative.

API Request Header

Prepare the header parameters as shown below. Please note the variance for country payment types:

API Request Body

ISO pain.001.001.03 Specification: HSBC_pain.001.001.03_HighValuePayment

How to prepare the request payload.

• Prepare the payload format.
• Sign the message with your private key and encrypt the payload using the bank public key.
• Encode the encrypted payload in BASE64 encoding representation.
• Populate the encoded payload in the JSON field paymentBase64

Example encoded request payload:

{
"paymentBase64":
"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxEb2N1bWVz="
}

API Response Body

The successful response body will contain the following fields:

Example response payloads:

200 - ACCP (Accepted Instruction Validation(L2))

{  
     "referenceId":"b7e0fdac-d8bd-4950-bd3a-38fac5cc25df",  
     "profileId":"PC12345678",    
     "statusCode":"ACCP",  
     "statusDesc":" Accepted Instruction Validation(L2)).", 
     "responseBase64":"PFJlc3BvbnNlPg0KICA8UGF5bWVudElkPmI3ZTBmZGFjLWQ4YmQtNDk1MC1iZDNhLTM4ZmFjNWNjMjVkZjwvUGF5bW+"
}

200 - ACSC (Accepted Settlement Completed)

{  
     "referenceId":"b7e0fdac-d8bd-4950-bd3a-38fac5cc25df",  
     "profileId":"PC12345678",    
     "statusCode":"ACSC",  
     "statusDesc":"AcceptedSettlementCompleted - Settlement on the account has been completed.", 
     "responseBase64":"PFJlc3BvbnNlPg0KICA8UGF5bWVudElkPmI3ZTBmZGFjLWQ4YmQtNDk1MC1iZDNhLTM4ZmFjNWNjMjVkZjwvUGF5bW+"
}

How to process the response payload:

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

The decoded and decrypted payment initiation payload content will be provided as an acknowledgement confirming if the settlement has completed and been accepted by the beneficiary bank.

Return to top

Summary

• Payment initiation for asynchronous processing of a single transaction via India Immediate Payments System with instant settlement.
• This documentation is specifically for Real-time Payments initiated via India Immediate Payments System (IMPS)
• India Immediate Payments require Country Code of IN and Payment Type of IMPSRTP in the header.
• Request payload should be provided in the proprietary XMLPF format that is specified below.
• The successful response provided by the API is that the payment is Accepted Settlement Completed, i.e. payment has been accepted by the beneficiary bank.

API Request Header

Prepare the header parameters as shown below. Please note the additional required header value for Cross Border remittance:

API Request Body

This API supports a proprietary XML (XMLPF) format applicable only for India RTP API.

This format is supported for 'Real Time Payment Initiation with instant settlement' and 'Payment Status Enquiry' of the Real-time payments sent by this format only when country is India.

Request Parameters for XMLPF IMPS Realtime Payment  Initiation

All parameters are case sensitive and are required to be captured in sequential order as per specifications. Optional parameters can be omitted from the XML structure:

Example Request Body:

<?xmlversion='1.0'encoding='windows-1252'?>
<p2aRequest>
  <SERVICEPROVIDERID>PC000016070</SERVICEPROVIDERID>
  <REQUESTID>IMPS0001000001D073000005050025</REQUESTID>
  <REQUESTTYPE>R</REQUESTTYPE>
  <REMITTORACCOUNTNO>073048084001</REMITTORACCOUNTNO>
  <BENEFICIARYBANKIFSC>HDFC0000007</BENEFICIARYBANKIFSC>
  <BENEFICIARYACCOUNTNO>073048084001</BENEFICIARYACCOUNTNO>
  <AMOUNT>1</AMOUNT>
  <CHANNELID>CDP</CHANNELID>
  <AUTHENTICATIONTOKEN>1234</AUTHENTICATIONTOKEN>
</p2aRequest>

How to prepare the request payload.

• Prepare the payload format.
• Sign the message with your private key and encrypt the payload using the bank public key.
• Encode the encrypted payload in BASE64 encoding representation.
• Populate the encoded payload in the JSON field paymentBase64

Example encoded request payload:

{
"paymentBase64":
"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxEb2N1bWVz="
}

API Response Body

The successful encrypted and encoded response body will contain the following fields:

Example encrypted and encoded response payload:

200 - ACSC (Accepted Settlement Completed)

{  
     "referenceId":"b7e0fdac-d8bd-4950-bd3a-38fac5cc25df",  
     "profileId":"PC12345678",    
     "statusCode":"ACSC",  
     "statusDesc":"AcceptedSettlementCompleted - Settlement on the account has been completed.", 
     "responseBase64":"PFJlc3BvbnNlPg0KICA8UGF5bWVudElkPmI3ZTBmZGFjLWQ4YmQtNDk1hMjVkZjwvUGF5bW+"
}

How to process the response payload:

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

The decoded and decrypted payment initiation payload content will be provided as an acknowledgement confirming if the settlement has completed and been accepted by the beneficiary bank.

Decoded and decrypted response payload

20200403182414

Example decoded and decrypted response payload

<p2aResponse>
  <REQUESTID>zwCjcJuci7nIjk2a</REQUESTID>
  <REQUESTTYPE>R</REQUESTTYPE>
  <REMITTORACCOUNTNO>002197994001</REMITTORACCOUNTNO>
  <MERCHANTID>123</MERCHANTID>
  <RESPONSECODE>00</RESPONSECODE>
  <RESPONSEDESCRIPTION>Successful</RESPONSEDESCRIPTION>
  <RRN>012119135399</RRN>
  <BENEFICIARYNAME>P3ACustomer</BENEFICIARYNAME>
  <TRANSACTIONDATETIME>20200430194741</TRANSACTIONDATETIME>
  <AUTHENTICATIONTOKEN>@@@</AUTHENTICATIONTOKEN>
  <ADDITIONALINFO1>INDIA VIX</ADDITIONALINFO1>
  <ADDITIONALINFO2>Creditor Name Test Bene Account EQ 20</ADDITIONALINFO2>
  <ADDITIONALINFO7>A</ADDITIONALINFO7>
</p2aResponse>

Return to top

Summary

• Provides the capability to track the status of the payments from initiation to completion with HSBC or settlement bank.
• Uses payment reference fields returned following the initiation of a payment to return the relating status acknowledgement.
• Please use this method to retrieve status acknowledgement for Single and Bulk payments initiated using the /payments/instant-receipt and /bulk-payments/instant-receipt end points.

API Request Header

Prepare the header parameters as shown below:

API Request Body

Prepare the request payload following the below message structure, please note the field names are case sensitive.

<StatusEnquiry>
  <ProfileID>PC000001111</ProfileID> 
  <Key> 
    <ReferenceID>0137fb84-b66d-40fb-9a4f-1c7d62288ff9</ReferenceID> 
    <MessageID></MessageID> 
    <PmtInfID></PmtInfID> 
    <InstructionID></InstructionID> 
    <EndToEndID></EndToEndID> 
  </Key> 
</StatusEnquiry> 

The various reference input parameters are defined below:

How to prepare the request payload.

• Prepare the payload format.
• Sign the message with your private key and encrypt the payload using the bank public key.
• Encode the encrypted payload in BASE64 encoding representation.
• Populate the encoded payload in the JSON field paymentEnquiryBase64

Example encoded request payload:

{
"paymentEnquiryBase64":
"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxEb2N1bWVz="
}

API Response Body

The successful response body will contain the following fields:

Example of a successful response payload:

200 - ACCP (Accepted)

{
   "referenceId":"b7e0fdac-d8bd-4950-bd3a-38fac5cc25df",
   "profileId":"PC12345678", 
   "statusCode":"ACCP",
   "statusDesc":"Accepted Instruction Validation (L2) - Description: Preceding check of instruction validation was successful. Customer profile check was also successful.",
   "responseBase64":"+DQogIDxTdGF0dXNDb2RlPlNVQk1JVFRFRDwvU3RhdHVzQ29kZT4gIA0KICA8U3RhdHVzRZhZm9"
}

This message represents the L2 acknowledgement that the instruction has passed validation and has been accepted. The below table defines the possible status codes and descriptions.

Payment status codes and descriptions

How to process the response payload:

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

The actual payload content will be in ISO 20022 pain.002.001.03 format as shown below.

Payment status response specification - pain.002.001.03

Link to document: HSBC_pain_002_001_03_PaymentStatusReportCombined_Core.pdf

 

Payment status response example - pain.002.001.03

<?xml version="1.0" encoding="UTF-8"?> <Document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:iso:std:iso:20022:tech:xsd:pain.002.001.03"> <CstmrPmtStsRpt> <GrpHdr> <MsgId>93a8f0703f0911eb974d39b880a13651</MsgId> <CreDtTm>2020-12-15T19:13:12</CreDtTm> <InitgPty> <Id> <OrgId> <BICOrBEI>MIDLGB22ABC</BICOrBEI> </OrgId> </Id> </InitgPty> </GrpHdr> <OrgnlGrpInfAndSts> <OrgnlMsgId>MSGREFPAPI003</OrgnlMsgId> <OrgnlMsgNmId>pain.001.001.03</OrgnlMsgNmId> <OrgnlNbOfTxs>2</OrgnlNbOfTxs> <OrgnlCtrlSum>0.03</OrgnlCtrlSum> <GrpSts>ACCP</GrpSts> </OrgnlGrpInfAndSts> <OrgnlPmtInfAndSts> <OrgnlPmtInfId>PYMTREFINAPI003</OrgnlPmtInfId> <OrgnlNbOfTxs>1</OrgnlNbOfTxs> <TxInfAndSts> <StsId>D350000400850001</StsId> <OrgnlInstrId>INSRTIDREFAPI002</OrgnlInstrId> <OrgnlEndToEndId>E2EIDREFAPI002</OrgnlEndToEndId> <TxSts>ACCP</TxSts> <StsRsnInf> <AddtlInf>/UETR/8e195783-db5a-4f78-bb73-e08589c7b921</AddtlInf> </StsRsnInf> <OrgnlTxRef> <Amt> <InstdAmt Ccy="USD">0.01</InstdAmt> </Amt> <ReqdExctnDt>2020-12-15</ReqdExctnDt> <Dbtr> <Nm>DEBTOR NAME</Nm> </Dbtr> <DbtrAcct> <Id> <Othr> <Id>123456789</Id> </Othr> </Id> </DbtrAcct> <DbtrAgt> <FinInstnId> <BIC>MRMDUS33</BIC> </FinInstnId> </DbtrAgt> <CdtrAgt> <FinInstnId> <BIC>MRMDUS33</BIC> </FinInstnId> </CdtrAgt> <Cdtr> <Nm>John Doe</Nm> </Cdtr> <CdtrAcct> <Id> <Othr> <Id>987654321</Id> </Othr> </Id> </CdtrAcct> </OrgnlTxRef> </TxInfAndSts> </OrgnlPmtInfAndSts> <OrgnlPmtInfAndSts> <OrgnlPmtInfId>PYMTREFINAPI005</OrgnlPmtInfId> <OrgnlNbOfTxs>1</OrgnlNbOfTxs> <TxInfAndSts> <StsId>D350000400860001</StsId> <OrgnlInstrId>INSRTIDREFAPI005</OrgnlInstrId> <OrgnlEndToEndId>E2EIDREFAPI005</OrgnlEndToEndId> <TxSts>ACCP</TxSts> <StsRsnInf> <AddtlInf>/UETR/c39057ec-df84-4a35-8953-8435d3f237e0</AddtlInf> </StsRsnInf> <OrgnlTxRef> <Amt> <InstdAmt Ccy="USD">0.02</InstdAmt> </Amt> <ReqdExctnDt>2020-12-15</ReqdExctnDt> <Dbtr> <Nm>DEBTOR NAME</Nm> </Dbtr> <DbtrAcct> <Id> <Othr> <Id>123456789</Id> </Othr> </Id> </DbtrAcct> <DbtrAgt> <FinInstnId> <BIC>MRMDUS33</BIC> </FinInstnId> </DbtrAgt> <CdtrAgt> <FinInstnId> <BIC>MRMDUS33</BIC> </FinInstnId> </CdtrAgt> <Cdtr> <Nm>John Doe</Nm> </Cdtr> <CdtrAcct> <Id> <Othr> <Id>987654321</Id> </Othr> </Id> </CdtrAcct> </OrgnlTxRef> </TxInfAndSts> </OrgnlPmtInfAndSts> </CstmrPmtStsRpt> </Document>

Return to top

Getting started

To experiment with the Corporate Sandbox, first create a project. This will generate 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 that can be found on 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 and 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 2 types of response in the Corporate Sandbox:

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.

• Mock Sandbox requires only Base64 encoding of the request and response payload.
• It uses the Client Credentials provided in your Sandbox Project.
• Please use 200 for the x-hsbc-profile-id to trigger a successful mock response.
• PGP keys are not required.

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

Example cURL script:

curl --location --request POST 'https://sandbox.corporate-api.hsbc.com/mock/v2/balances' \
--header 'Content-Type: application/json' \
--header 'x-hsbc-client-id: mock-clientId' \
--header 'x-hsbc-client-secret: mock-secret' \
--header 'x-report-type: JSON' \
--header 'x-hsbc-profile-id: 200';

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 requires message signing, encryption and Base64 encoding of the request and response payloads.
• It uses the Client Credentials, Profile ID and Encryption keys 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}/{treasury api endpoint}

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

Download the Sandbox Toolkit

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 Accounts per country.

Return to top

API Guide in Chinese

For customers require API Guide in Chinese for Payments and Account Information APIs (OpenAM version only), please refer here.

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

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.

Return to top