General

Who is develop.hsbc designed for?

This site is for software developers from client or third party organisations who want to integrate HSBC’s APIs into their applications. It provides access to comprehensive technical documentation, sandbox facilities and support from our team of experts to get you up and running.

The File Validator tool on this site is available to clients who want to validate the payment files they are developing to be sent via HSBCnet, HSBC Connect, SWIFT FileAct or API. 

If you’re looking for information about HSBC UK and Open Banking more generally, please follow the links below.

HSBC UK public website

HSBC UK Open Banking for customers

 

Which markets does develop.hsbc support?

develop.hsbc is HSBC’s global developer portal, which will in time support all our market facing APIs - both Open Banking and commercial.

Commercial APIs: this site supports a set of APIs designed for corporate banking customers with accounts in the majority of markets in which HSBC operates around the world.

Open Banking APIs: this site supports APIs which cover Hong Kong SAR, UK, Europe, Bahrain and Mexico. Please refer to our Open Banking Get Started guide for a detailed view of how each market is supported. Our Phase 1 and 2 Hong Kong APIs are currently supported from our Hong Kong Developer Portal

File Validator: this tool supports file validation for majority of markets in which HSBC operates around the world. 

Why do I need to register?

You can browse our API catalogue and access overviews for all of our APIs without registering and logging in.

Commercial APIs: you need to register and log in to access the technical documentation and sandbox facilities.

Open Banking APIs: you can access technical documentation without registering or logging on, but will need to register and log in to access our sandbox facilities. In addition, developers interested in our Mexico Open Banking APIs need to register on develop.hsbc in order to generate a Software Statement Assertion (SSA), which must be provided as part of the Dynamic Client Registration (DCR) process for our production APIs.Finally, registration enables us to contact you with service updates and product developments if you’re interested in receiving them.

File Validator: you need to register and log in to use the file validator.

For more specific help on registration please review our knowledge article

Can multiple users from the same company be added to the same organisation in develop.hsbc?

Commercial APIs / File Validator: when the first user from a company registers on develop.hsbc, a new organisation is created as part of the registration process. When subsequent users from the same company register, they will be added to the same organisation within develop.hsbc. One user in each organisation will be designated as the admin user and be able to manage membership of that organisation.

Open Banking APIs: When you register for our Open Banking APIs, a separate organisation is created for each registered user. Each user will be designated as the admin user and will be able to manage membership of that organisation. If a user has already registered but wants to belong to a different organisation they must be invited by the admin user of said organisation. The invited user can choose to accept the invite. After accepting they will lose access to any projects in their previous organisation.

 

I had an account on the old developer portal. Do I need to re-register for develop.hsbc?

Yes, your old login details won’t work on develop.hsbc. Please register on develop.hsbc to set up a new account. This will give you immediate access to our latest documentation and you’ll also be able to generate new test certificates if you need them.

 

I haven’t received an activation email. What should I do?

Please check the spam/junk mail folder in your mailbox to see if your activation email accidentally fell into these folders. If you still don't see the activation email you can try to reset your password from the log On screen. If you are still experiencing issues, please send us a message using the Contact us form found under the Help menu.

 

How can I reset my password?

Please use the forgotten password option from the Log On screen to reset your password.

 

Which internet browsers are recommended to use with develop.hsbc?

The portal is optimised for use in Chrome, FireFox, Edge and Safari browsers. Whilst Internet Explorer 11 is supported there may be some lost formatting on certain images and loss of dynamic features when viewing the technical documents.

 

Can I register to access production APIs through develop.hsbc?

No, at present develop.hsbc provides documentation, which will guide you through the steps involved in accessing our production APIs, but the process of registering your app to consume our production APIs must be initiated be calling the relevant registration APIs directly. 

The pre-requisites and technical steps involved differ by market and/or type of API so please refer to our implementation documentation to help you get on board as quickly as possible. 

 

How can I get additional assistance or provide feedback?

If you need any additional assistance or have any feedback which will help us improve our services, please send us a message using the Contact us form found under the Help menu.

Is there a glossary of terms and abbreviations?

Yes, you can view the glossary here.

Technical documentation

How do I start using your APIs?

The pre-requisites to use APIs in production is differ by market and/or type of API. Please refer to our implementation documentation to help you on board as quickly as possible.

 

Why can’t I view the technical documentation?

Commercial APIs: You need to be a registered user to view the API technical documentation. Please complete the registration form to be granted access. You’ll be given access once approved by our Operations team. If we need more details from you to complete your registration, one of our team will get in touch.

Open Banking APIs: If you’re registering for our Open Banking APIs, you’ll be given access to the documentation as soon as you’ve completed the registration process.

 

How can I obtain the file format guide to facilitate file development prior to using the File Validator for validation

Please reach out to your HSBC relationship or service contact or alternatively please send us a message using the Contact us form found under the Help menu. Please include the market(s) and the payment type(s) for which you require the file format guides

Testing facilities

Do all your APIs have a sandbox?

The type and availability of the testing environments are specified in the technical documentation for each API. Where a sandbox is available you’ll find the required instructions on how to access the environment in the technical documentation.

Commercial APIs: All of our commercial APIs have a testing environment, however some are managed environments and not an open sandbox. This means we may need to perform some setup activities to grant you access.

Open Banking APIs: We’ve now launched our new Open Banking Sandbox, which supports our Hong Kong SAR, UK, and Bahrain. You can find full instructions on how to access and use the sandbox with our technical documentation. We don’t provide sandboxes for our Open Data APIs in the UK or Mexico.

 

Is the data in the sandbox real customer data?

No, all the data in our sandboxes is test data and does not contain any real HSBC customer or legal entity data. The sandbox data is designed to provide a representative sample of what can be expected in production to provide a valid test input for your apps.

How do I access the Open Banking Sandbox?

Once you’re ready to start testing you’ll need to register your app in the sandbox. Our OB sandbox only supports test certificates issued by HSBC so before completing sandbox DCR, there are a few pre-requisite steps you’ll need to complete to generate your test certificates and a software statement. Create a project in the Dev Hub, which will guide you through the process. Full details are provided in the Sandbox Access Guide for the API(s) you’re interested in.

Once you’ve completed sandbox DCR, you’ll be able to view the certificates you’ve generated and the apps you’ve registered, along with their associated Client IDs, for use when calling the sandbox APIs.

 

Will test certificates generated on the old developer portal work in the new Open Banking Sandbox?

No, the new OB Sandbox will only accept test certificates generated in the new developer portal. Please register on develop.hsbc and follow the instructions provided to generate new test certificates.

 

Will test certificates generated on the old developer portal continue to work in the MCI Test Facilities?

Yes, our MCI Test Facilities support test certificates generated on the old developer portal as well as those generated on develop.hsbc.

In the Open Banking Sandbox, can I call the endpoints directly using Postman?

Yes, you can call the sandbox APIs directly, however please note that OB Sandbox only supports test certificates generated on develop.hsbc, so there are number of steps you need to complete within the sandbox in order to generate the certificates you need. Once you’ve generated your test certificates you can call the /register (in order to register your app) and fulfilment end points end points directly.

 

In the Open Banking Sandbox, are the consent authorisation journeys the same as the those provided in production?

The consent authorisation journeys in the OB Sandbox replicate the function of our production journeys from a TPP’s perspective in that they support scenarios where the account(s) the consent relates to is provided by the TPP or selected by the customer and an authorisation code is provided following successful authentication. However, the look and feel of the screens and the steps involved from a customer’s perspective have been standardised across all brands (and payment types for PIS journeys) for the purposes of simplification.

 

Are the test certificates generated by the site valid as per the ETSI standard specification?

The test certificates generated are valid X.509 certificates, meaning they’re a valid a substitute for connecting to the OB Sandbox or the MCI Test Facilities. However, production certificates issued by a Qualified Trust Service Provider or the OBIE may be slightly different in structure. The test certificates generated on this site cannot be used for any purpose other than using the testing facilities provided by HSBC.

 

Using the File Validator tool

 

From the File Validator report, how do I determine that the file has no errors?

If there are no errors, the File Validator report header will contain three green ticks;
•    File validation report – Validation completed successfully
•    File level – Accepted
•    Instruction level – Accepted (or Accepted with value date rolled over)

 

Is there any validation that is not covered under the File Validator tool?

File Validator will only help you test the syntax and file schema of the payments files. It does not help validate the data accuracy, the following type of validations will not be covered by the File Validator on this site;
•    validations against your production profile; eg. debit account numbers, ACH ID/code, duplicate check on file reference/file name/transaction ID, etc.
•    validations based on your production HSBCnet for file uploaded or authorization on HSBCnet; eg. HSBC beneficiary validation, entitlement, etc.
•    validations during payment processing; eg. account balance check, beneficiary account and bank details, payment advising, WHT certificate issuance, etc.

 

Can the File Validator be used to validate all file formats and payment types across all markets?

Currently the File Validator generates a comprehensive validation report for  the following combination of file format, payment types and markets;
File format – XML V3
Payment types – Cross Border wires, domestic wires, ACH, real time payments
Markets – France, Hong Kong, India, Singapore, United Kingdom, United States

For combination of other file formats, payments types and markets, the validation report may not contain ‘Invalid field name’, ‘Invalid value’ and ‘Reference/Additional comment’ under the validation details section of the report.

HSBC will continue to enhance the File Validator tool to generate comprehensive validation report for additional combination of file formats, payments types and markets.

 

On the File Validator tool validation report, why do certain Validation details appear as ‘N/A’?

If all three fields; ‘Invalid field name’, ‘Invalid value’ and ‘Reference/Additional comment’ appear as ‘N/A’, then most likely the tool has not been enhanced to generate the comprehensive validation report for the combination of file formats, payments type and market which was tested.

Also refer to FAQ - Can the File Validator be used to validate all file formats and payment types across all markets?
 

The File Validator report includes errors such as ‘Unable to Identify Country Code or Payment Type’, when there is no field on the file for the debit account location. How do I rectify this? 

Select the Debit account location and File format before reuploading an amended file. If this does not still rectify the error, please contact us with the details.

 

Production 

I'm experiencing issues with Open Banking APIs in Production

If you are experiencing problems with our Open Banking APIs in the United Kingdom, you can access AIS, PIS or funds confirmation services using our Modified Customer Interface (MCI), subject to having the correct permissions. Further details on how to get access to the MCI can be found here.

 

After a successful validation of the payment file using the File Validator can I send the live payment files to the bank for processing?

Even though file has passed validation, please ensure the following before submitting the live payment files for processing:
1. Receive confirmation from HSBC that all relevant set-up has been completed for the intended services, accounts and payment types.
2. Perform end-to-end penny test (small payment amount) with satisfaction, on the live environment