Sandbox project

To experiment with the Corporate Sandbox APIs, first create a project in the Dev Hub. This will generate the Client Credentials and Encryption Keys that are required when calling the Sandbox APIs. The Dev Hub is available for registered Corporate users of the site, the link can be found on the Corporate homepage.

You can find a detailed guide on how to create a sandbox project here: Creating a Sandbox Project

If you've already created a project, use the toolkit below to get started..

Sandbox responses

We support two types of response in the Corporate Sandbox:

• A Mock sandbox
• A Smart sandbox

Mock sandbox

The Mock sandbox returns a static sample response based on a called end-point.

It also supports:

• Simple scenarios based on the provided header values. For example, if you request a JSON format response in the request header the mock end-point will return the pre-defined JSON sample.
• Does not require message encryption so you can quickly trial the API response whilst you are preparing your encryption module for use with the smart sandbox.
• Mock responses can be triggered by adding /mock to the Sandbox URL.
• Mock Sandbox URL: https://sandbox.corporate-api.hsbc.com/mock/{version}/{end-point}

For Treasury APIs, let's try this out with a simple cURL script:

curl --location --request POST 'https://sandbox.corporate-api.hsbc.com/mock/v2/transactions' \
--header 'Content-Type: application/json' \
--header 'x-hsbc-client-id: mock-client-id' \
--header 'x-hsbc-client-secret: mock-secret' \
--header 'x-hsbc-profile-id: 200' \
--header 'x-report-type: JSON' \
--header 'x-sort-order: ASC' \
--data-raw '{
    "transactionsRequestBase64": "Not-Validated-Returns-Mock-Response"
}'

• The response is Base64 encoded, so to read the response payload you need to decode the value provided in the response JSON.
• To see the XML version of the mock response, try submitting again using header x-report-type: CAMT

For Trade Finance APIs, let's try this out with a simple cURL script:

curl --location --request POST 'https://sandbox.corporate-api.hsbc.com/mock/v1/guarantee/fi/get-status' \
--header 'Content-Type: application/json' \
--header 'Authorisation: JWS header.payload.signature' \
--header 'requestId: SUCCESS' \
--data-raw '{
    "tradeAccountNumber": "GBHSBC000000000001"
    "fiTransactionId" : "CR001DR"
}'

The response is in plain JSON.

Smart sandbox

The Smart sandbox is a full testing environment. It returns a validated response from the database based on the chosen endpoint parameters.

Other features include:

• Any input data, such as payment instructions, are stored in the database and are reflected in the balances of the account being used. The data persists during your testing and can be used over multiple days.
• Requires client credentials, message signing, message encryption and base64 encoding so reflects our production API journey. Please use the PGP keys provided in your Sandbox project as we have configured your access to use these credentials.
• The password for the client private key is available in client-pgp-keys.info file in your downloaded encryption keys zip file.
• The sandbox database contains a base set of test data for all our major markets, however you can add more rows using our upload facility if required.
• The sandbox supports both positive and negative test scenarios that reflect our production system behaviour. Details of specific test scenarios are added to the API reference documentation and knowledge articles, including: Sandbox scenario generator.
• We provide sandbox management APIs that will allow you to add more data or reset your sandbox back to the base data set.
• Smart sandbox URL: https://sandbox.corporate-api.hsbc.com/{version}/{end-point}

Note: for full details of the test data supported, please see the sandbox section in your chosen API documentation.

Postman Collection

Postman is a third-party application that is used to make API calls from a user interface. A complete API OAS specification, or a collection is imported and managed in Postman. A Postman Collection is generally a group of API calls saved in JSON.

Read more about Postman at this website https://www.getpostman.com. 

Please note the following points when working with the sandbox Postman collection:

• Configure the Request Headers to use your Sandbox project Credentials.
• If you are calling the Smart Sandbox, note the points in the table below:

• For any specific treatment required when calling your chosen API, please read the API reference documentation.

Desktop Postman

The attached collection can be used to setup a desktop Postman session.

Treasury APIs

Please download the file, unzip the content and load to your local instance of Postman.

Treasury API Sandbox.postman_collection.zip

Trade Finance APIs

Please download the file, unzip the content and load to your local instance of Postman.

Trade Finance API Sandbox.postman_collection.zip

The below collection can be used to add new data into the sandbox database:

Sandbox Management APIs.postman_collection.zip

See also:

Detailed guide to Sandbox Data Management

PGP Helper Application

We have developed a PGP helper collection in web Postman that can help shortcut the testing effort when manually calling the corporate sandbox from Postman.

The PGP helper collection works in parallel with a small Java application to complete the process of creating a JWT (if necessary) and performing the encryption and decryption of request and response payloads. 

Steps to use PGP Helper:

1. Create a Dev Hub project to create the required encryption keys and client credentials for use against the sandbox.
2. Download and configure the pgp-helper Java application. See the ReadMe file within the Java project for detail on how to configure the code project with your keys and credentials.
3. Run the pgp-helper application on your local machine and leave the project running in the background.
4. Switch to Postman and create and environment variables to match 

Sample Java Client

Click the below links to download example code of a successful encryption/decryption of the payload for use with the Smart Sandbox.

To successfully call the Smart Sandbox, your client application is required to configure the following resources:

• The HSBC public key provided in your Sandbox Project is stored on the class path or on absolute path, usually in a resources folder.
• Place the client private key in the same location as the banks public key.
• Configure the password for the client private key - this is available in the client-pgp-keys.info file in your downloaded zip file.
• To complete the encryption processes. You can now write the client service class using the sample code snippets
   

Tips for using the JWT based Java clients:

Encryption:
Request payload which needs to be encrypted should be made available in the file ../jwt-tool-test-instance/src/main/resources/request-content/requestContent2.json
(For GET calls with no request payload, the content of requestContent2.json should be empty.)

Run ClientSideTokenNEncryption.java for payload encryption and JWT creation. Once it is run, in the console you'll find the encrypted Base64 string denoted as "request payload encrypted Base64 String:". And the JWT token denoted as "JWT Token:".

Decryption:
Response to be decrypted needs to be made available in the file ../jwt-tool-test-instance/src/main/resources/request-content/bankResponseEncrypted.json

Run ClientSideDecryption.java for response decryption.

Related articles

Sandbox project user guide

Sandbox scenario generator

Return to top