Sandbox Project - User Guide
Creating a sandbox project
On this page
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.
Creating a Project
Use the following steps:
- On the Dev Hub landing page, click on the red button Create Project. The Project Information page is displayed. Enter a name for the project and a short description in the field provided. Click on Continue.
- The Select APIs page is displayed.
- Select the required API type from the Product category drop down menu.
Important Note: As there are APIs with different security models across HSBC, the product category selection only displays APIs that have a compatible security model. If APIs with different security models are required please set up separate projects.
- Check one or more APIs to work with in the Sandbox. Click on Continue
- The Invite Team Members page is displayed. Enter the team member email and role: Administrator or Developer. This step can be revisited after the project is created. Click on Continue.
- The Generating encryption keys page is displayed. This page requires no input from the user.
Important Note: During key generation, the following processes occur in the background.
- Client ID and Client Secret are generated and returned by the Sandbox Gateway.
- Client PGP keys and the HSBC public key are generated.
- The client public key is stored in the gateway crypto store. This effectively completes the key exchange.
- When the generation is complete, click on View Project. The Project Details page is displayed.
Summary
After following steps 1- 7 above:
- you now own the credentials and keys to use the sandbox
- you can begin to encrypt, sign and encode message payloads
- you can begin working and interacting with the Corporate API sandbox
Project Details Page
Following the creation of each project, a Project Details page is available in the Sandbox. The page is presented to the client immediately after creating a new project. It is also available after selecting a project from the Latest projects pane of the Projects tab.
To view the Project Details page, use the following steps:
- From the top of the Dev Hub page, select the Projects tab. The Projects pane shows current statistics of all Projects in the Sandbox.
- Scroll down to the Latest projects pane.
- Click on the required project. The Project Details page is displayed.
Credentials and Keys
Use these fields to secure your access to the Sandbox:
| Field | Description |
|---|---|
| Client ID and Client Secret | Alphanumeric identifier codes generated after project creation. These credentials are used for authentication and must be provided in the headers of the HTTP request every time you invoke Treasury API services. This ensures only authorised and pre-approved organisations can access and utilise our API services. |
| Profile ID | This is your organisation Identifier within the Developer Portal, it will be replaced in the live environment with a profile identified from our back-office system that will be provided by the assigned Client Integration Manager. This value is required in the API call header x-hsbc-profile-id. |
| Download Encryption Keys | Click to download a zip file containing the encryption keys. See Downloading the Encryption Keys below. |
Downloading the Encryption Keys
- On the Credential and Keys pane, click on the Download Keys button.
- A zip file containing the HSBC public key and the clients private and public keys is presented.
- Save the file to a secure location for use in the message encryption process.
Files Provided include:
| File | Description |
|---|---|
| hsbc-public.key | Use the HSBC Public Key to encrypt the request sent to the Treasury API Sandbox. |
| client-private.key | Use the Client Private key to sign the request sent to the Treasury API Sandbox and decrypt the response received from the Treasury API Sandbox. |
| client-public.key | The Treasury API sandbox will use this key to encrypt the response message before sending, this file is included for reference purpose only. |
| client-pgp-keys.info | This file contains the default passphrase for the key files. |
APIs Accessed
This pane lists the APIs currently selected in the Sandbox project.
Use the links defined in Details to download the API swagger file or link to the selected API reference page.
| Field | Description |
|---|---|
| API | The name of the API selected as part of the client’s sandbox operations. |
| Details | Download the Swagger File and link to the selected API reference pages. |
Test Data
The Sandbox has a basic set of representative test data; this is enough for approximately 24 hours of operation. To add more data (csv rows), a CSV Template is available which can be downloaded and filled-in by the client, it is then loaded into the Sandbox using the Upload CSV button or via API. An example of a cURL request for adding test data is shown later in this document.
To return to the basic data set, simply click on Reset all data. For every project created, a new set of basic data is generated and linked to the client id. All members of the project will have access to that data in the Sandbox.
| Field | Description |
|---|---|
| Upload CSV file | Loads a client’s csv data file into the Sandbox. Max 10 files (appended) Max 2.5 MB each |
| Reset all data | Reverts to original Sandbox seed test data only. Start date = project creation date. |
| Download CSV Template(s) | Downloads a template csv data file. This is used by the client to populate the Sandbox with additional test data and is appended to the existing data set(s). |
Adding More Data
This example is a POST request that adds user generated data to the Sandbox. In the example below, the authentication credentials are inserted as 'x-hsbc-client-id' and 'x-hsbc-client-secret'. The target table to update is specified in the ‘table-names' header field.
curl --location --request POST 'https://sandbox.corporate-api.hsbc.com/v1/sandbox-self-service/baseline/data' \
--header 'x-hsbc-client-id: your-project-client-id' \
--header 'x-hsbc-client-secret: your-project-client-secret' \
--header 'x-hsbc-profile-id: your-project-profile-id' \
--header 'product-category: treasury' \
--header 'category-version: 1.0' \
--header 'table-names: comma-separated-table-names' \
--header 'product-names: comma-separated-product-names'
Note: The cURL script above creates new entries in the Sandbox database based on the CSV file attached to the request. The table to update is specified in the table-names header. If the database contains an entry matching a row in the CSV (same accountNumber, accountCountry, institutionCode, and accountType), that row is updated with new data taken from the CSV.
Members
This pane lists the members of the current project. Use the Add Members button to add members of the Dev Portal to a project.
| Field | Description |
|---|---|
| Name | Name of the project member |
| Role | Administrator/Developer |
| Projects | Number of the project, e.g, 2 |
Add a member to a project
Use the following steps:
- From the Members pane click on Add Members. The Invite team members dialoq box appears.
- In the Add team Member box, enter the email address of the requested member.
- In the Assign their role field select a role from the dropdown menu i.e. Administrator or Developer.
- Click on Invite. An email is sent to the prospective member.
Note: The Sandbox processes the invitation and checks the validity of the prospective member’s email.
The status of the invitation can be viewed as follows:
- Go to the top of the page and select the Members tab.
- Scroll down to the All members pane.
- Select the Invitations tab. The Invitations tab shows any invitations that are currently being checked. The member’s details will not be present if the invitation is successful.
- If the invitation is successful, the new member will appear in the Members pane.
Checking the status of a member
The status of all project members is displayed in the Members pane of the Members tab.
Related articles