Get started

Getting started is really simple! Please follow these steps to start working with our APIs:

1. Register for a Corporate account to get access to the documentation and sandbox environments.
2. Find the APIs that meet your requirements from the API catalogue and read the documentation.
3. Once you are happy with how our APIs work, use the Dev Hub to create a sandbox project.
4. Use the Corporate sandbox to build your integration and test connectivity.
5. During this process your organisation will be allocated a Client Integration contact who will guide you through onboarding and setup in our managed test environments and support connectivity to the live APIs.

See the Business quick start guide for more help on eligibility and service availability.

Working with the Developer Portal

We have streamlined the journey through the portal to get you working with code as quickly as possible. To help with this we've provided lots of code examples and helpful tools to accelerate your first interaction with our APIs.

Here's some more detail on the tools available to help you quickly start working with our APIs:

Technical Documentation

Supporting technical documentation is provided for each API. Please register for a Corporate account and login to the portal to view the documentation.

You will find the following information under the Documentation link in the catalogue and from the API overview page:

API Information - provides the details of the API version, protocol, high-level description and change log.

Security - details the security model applicable for the specific API and how you can go about authenticating and invoking a connection.

Tutorials and Guides - provides specific information about how to interact with each API including header values, example request/response bodies, example payload structures and any specific criteria about the data that will be returned by the API.

Knowledge articles are also provided on the site and can be found using the site search facility (magnifying glass icon on top right of screen). Try running a search for "Sandbox" to see what results are returned.

API Reference - Endpoints

Explore the API code using the swagger viewer and test basic connectivity using the Try it out feature.

This section contains lots of detail on the request and response body schema including the encryption envelope and the underlying message payload.

Code samples are provided in the following languages: C#, Java, Javascript, Node js, PHP, Python

Developer Portal Notifications

We can send you notifications through the portal. New notifications will be shown as a red dot on your profile avatar. Please follow the profile menu to access your notification message.

Examples of when we may send a notification:

1. Notice of upcoming changes to the Developer Portal and Sandbox.
2. Notice of key rotation in the sandbox with instruction on how to refresh your encryption keys.
3. Announcement of new API products and capabilities that have been added to the catalogue.

Any critical service messages regarding our live APIs will be sent directly to the nominated contact by our client service team and not via the Developer Portal notification service.

Securing a connection

HSBC's corporate APIs typically employ the following security patterns:

The exact details of the Security model employed by the API you wish to use will be specified in the Technical Documentation. This will include examples of how to compile any related security components such as JSON Web Token (JWT) and supported encryption algorithms.

To ensure you can self-serve with your sandbox access, the portal will be provide the necessary credentials and PGP encryption keys to work with the sandbox during the sandbox project creation. For live usage, you will need to source your own PGP keys and exchange them with your Client Integration contact.

More information on API Security and sandbox setup can be found below:

API Security at HSBC

Sandbox project user guide

Testing your connection

A sandbox is available for the corporate APIs to help you develop your integration and test connectivity.

Sandbox base URL and health check:

curl --location --request GET 'https://sandbox.corporate-api.hsbc.com/healthcheck'

We support 2 types of response in the corporate sandbox:

Mock sandbox - returns a static sample response with no encryption.

• For rapid testing whilst you are developing your encryption module.
• 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}

Smart sandbox - a full testing environment that returns a validated response from the database based on the provided request parameters. 

• Requires client credentials, message encryption, message signing 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.
• Supports positive and negative testing on our default dataset with the ability to upload your own data and generate test scenarios.
• Smart sandbox URL: https://sandbox.corporate-api.hsbc.com/{version}/{end-point}

To establish a connection to the sandbox, first create a project using the simple workflow found in the Dev Hub. This will create the secure credentials and encryption keys needed to connect to the sandbox.

The Dev Hub provides a dashboard where you can manage your sandbox projects and team members who are part of your organisation. You will see the Dev Hub link in the top right of your screen once you have registered for a corporate account and are logged on to the portal.

More information on Sandbox setup can be found below:

Sandbox project user guide

Managing data in the sandbox

Sandbox toolkit

We've created some resources to help you get started with the sandbox, including Postman collections and a sample client application.

For desktop Postman, the attached collection can be used to setup a session for the corporate APIs currently in the sandbox.

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

Treasury API Sandbox.postman_collection.zip

Trade Finance API Sandbox.postman_collection.zip

More information on Sandbox Toolkit and access to the sample client application can be found below:

Using the sandbox toolkit

Sandbox scenario generator

Help and feedback

Dive in and start coding your applications using our APIs. If you get stuck or require additional support then please speak to your nominated Client Integration contact or alternatively contact our team using the Contact Us form that is available under the Help menu.

Please note, the portal is optimised for use in Chrome, FireFox, Edge and Safari browsers. Whilst Internet Explorer 11 is supported there will be some lost formatting on certain images and loss of dynamic features when viewing the technical documents. Please contact our support team for further information on IE 11 support.

Related articles

Use case library - explore real-world examples

What's new on the Developer Portal?

Frequently asked questions

Return to top