Making a Mock Sandbox Request

Using Mock Sandbox

Simple scenarios based on the provided header values. For example, you can get a BAD_REQUEST response by specifiying it in the request header (requestId).
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}

Making an API Request via cURL

Client URL (cURL) enables developers to transfer data to and from a servers by command line. Use it to:

Specifying the location (in the form of a URL)
Specifying data you want to send
Supports various protocols such as HTTP and HTTPS

Let's try this out with a simple cURL script:

Open Terminal

Open the terminal with respect to your operating system.

cURL Command Syntax

Prepare the following:

API Operation and Endpoint. For example, we want to make a POST Request to an API, use the following syntax: --request POST '{{API Endpoint}}'
Request Headers. e.g. --header 'requestTime: 2023-01-01 06:55:30'
Request Body. e.g. --data-raw '{{Plain JSON Request Body}}'

Execute API Request

Here is an example of the cURL:


curl --location --request POST 'https://sandbox.corporate-api.hsbc.com/mock/v1/trade finance/invoices/detail' \ 
  --header 'requestTime: 2023-01-01 06:55:30' \ 
  --header 'requestId: 92aef07bdc4243e99afa9dc2af02c1cf' \ 
  --header 'countryCode: HK' \ --header 'schemaVersion: 1' \ 
  --header 'Content-Type: application/json' \ 
  --data-raw '{ 
  "pageNumber":"1",
  "pageSize":"1000",
  "extnlCustomerId":"customer001",
  "ultimateDebtorIdentifier":"KYB_BHK001",
  "fileId":"",
  "endToEndIdentification":"",
  "requestedExecutionDate":"",
  "invoiceNumber":""
  }'

Process API Response

Upon request is sent successfully, you will receive the response in Plain JSON:


{
  "code": "EMKT200",
  "message": "Success",
  "repliedTime": "2023-01-01 06:55:59",
  "correlationId": "F57e31838ceaC0f1dFe9DBCf5e06f11c",
  "responseData": {
    "totalCount": "4",
    "pageSize": "2",
    "pageNumber": "1",
    "records": [
      {
        "creationDateTime": "2023-01-01 00::00:33",
        "originalFileId": "20aE8C636a3BfE986bA7e0d61BD155AD",
        "originalCreationDateTime": "2023-01-01 00:00",
        "originalNumberOfTransactions": "2",
        "originalControlSum": "",
        "groupStatus": "ACCP",
        "originalInvoiceNumber": "INV230101-SHK002-01",
        "originalEndToEndIdentification": "BPRN230101-SHK002",
        "invoiceStatus": "ACCP",
        "statusReasonInformation": [
          {
            "statusReasonCode": "",
            "additionalInformation": ""
          }
        ],
        "originalInstructedCurrency": "HKD",
        "originalInstructedAmount": "250",
        "originalRequestedExecutionDate": "2023-01-30",
        "originalUltimateDebtorName": "BUYER 1 HK Corporate Limited",
        "originalUltimateDebtorIdentifier": "KYB_BHK001",
        "originalSupplierName": "Supplier 1 HK Corporate Limited",
        "originalSupplierUniqueReference": "KYB_SHK002"
      },
      {
        "creationDateTime": "2023-01-01 00::00:33",
        "originalFileId": "20aE8C636a3BfE986bA7e0d61BD155AD",
        "originalCreationDateTime": "2023-01-01 00:00",
        "originalNumberOfTransactions": "2",
        "originalControlSum": "",
        "groupStatus": "ACCP",
        "originalInvoiceNumber": "INV230101-SHK002-02",
        "originalEndToEndIdentification": "BPRN230101-SHK002",
        "invoiceStatus": "ACCP",
        "statusReasonInformation": [
          {
            "statusReasonCode": "",
            "additionalInformation": ""
          }
        ],
        "originalInstructedCurrency": "HKD",
        "originalInstructedAmount": "250",
        "originalRequestedExecutionDate": "2023-01-30",
        "originalUltimateDebtorName": "BUYER 1 HK Corporate Limited",
        "originalUltimateDebtorIdentifier": "KYB_BHK001",
        "originalSupplierName": "Supplier 1 HK Corporate Limited",
        "originalSupplierUniqueReference": "KYB_SHK002"
      }
    ]
  },
  "errorDetails": null
}

Making an API Request for other Response scenario

There are three response scenario that can be triggered by various value input in requestId header.

SUCCESS: To trigger a success scenario from the mock response.
BAD_REQUEST: To trigger a bad request payload scenario from the mock response.
INTERNAL_ERROR: To trigger an internal server error scenario from the mock response.

Next, let's try to sending a mock sandbox request via Open API Specifications.

Making an API Request via Open API Specifications

Open API Specification is an API description format for REST APIs.

Read more about Open API Specification at this website https://swagger.io/specification

You may also try mock sandbox response via Endpoint Specifications.

View API Endpoint Specifications

You may view or download the Open API Specification from the Endpoints tab on the top navigation bar.

Select specific API Endpoint

Expand the API Endpoint that you wanted to test. Click Try it out button.

Prepare API Request Header

Upon clicking Try it out button, editable textboxes will be populated for the header parameters with the default value pre-filled. You may edit the requestId for triggering various response scenarios.

Prepare API Request Body

You will be able to select the request body content type and edit the request body based on the pre-filled default values.

Execute API Request

Click Execute once you have reviewed your request contents. The API Request will be sent to the mock sandbox.

Process API Response

Upon a successful request, the server response with http code 200 will be displayed:

process-response-mock-oas

Next, let's try to sending a mock sandbox request via Postman.

Making an API Request via Postman

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.

Access/ Download Postman Collections

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

Trade Finance API Sandbox.postman_collection.zip

Web Postman Service is also available:

Import Postman Collections

Click File -> Import
Click Upload File
Select trade-finance.postman_collections.json
Confirm the collections selected, click Import

Select API Endpoint

Once Imported, select under Corporate APIs collection -> Trade Finance Sandbox -> {{Product Folder}} ->{{API Endpoint}} you want to test.

Prepare API Request Headers