Trade Finance - Seller Loans - V1
Trade Finance - Seller Loans - V1

On this page

API Information

Trade Finance - Seller Loans

  • Version: v1 
  • Protocol: HTTPS
  • URL Pre-Prod Test (UAT): Please speak to your Client Integration contact
  • URL Production: Please speak to your Client Integration contact

Description

In this document, you'll find the steps your organization needs to take to use our API services. Also in this guide are details of request and response messages used to support your organization’s integration.

The intended audience for this document are Technical Architects, Development Engineers, Test Engineers, and Operation & Maintenance Engineers involved in development and support of your organization’s integration.

Setting up our API Services is best completed with the assistance of your organization’s IT team, or someone with experience and knowledge of application programming interfaces. This should include experience with - JSON payloads and security and public key infrastructure (PKI).

Quick Start Guide:

Click on the Left Menu to explore the following topics:

Topics This page will help you to: References
API Specification
  1. Description of API headers, request and response body
View specifications (OAS)
Securing a Connection
  1. Understand the steps required to secure and encrypt a connection with HSBC
  2. View the fields to be provided in the JWT header and payload
  3. See code examples of how to generate the required JSON Web Token (JWT)
View
Making an API Request
  1. Prepare an API request payload and perform payload encryption
  2. Generate and sign a client token (JWT)
  3. Steps required to process a response
View
Response Codes and Formats
  1. Understand the response code
  2. How to perform troubleshooting
View
Sandbox Access
  1. Perform Testing on Sandbox
View

Version History

Change log and release history:

Version Release Date Status Description
v1 December 2021 To be deprecate Seller Loans - First Release

 

Return to top

On this page

Sandbox Access

Sandbox Access

On this page

This page will help you to:

  • Understand various types of Sandbox Response
  • Making an API Request via Mock Sandbox
  • Making an API Request via Smart Sandbox
  • Test Scenarios

Sandbox Response

We support two types of response in the Trade Finance - Seller Loans Sandbox:

Mock Sandbox:

Returns a static mock response to the requested endpoint. These endpoints can be used for rapid testing whilst you are preparing your encryption module to use with the smart sandbox.

  • Mock Sandbox requires only Plain JSON of the request and response payload.
  • 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.
  • PGP keys are not required.

Mock Sandbox URL: https://sandbox.corporate-api.hsbc.com/mock/twc/v1

Using Mock Sandbox:

Refer to Making a Mock Sandbox Request for step-by-step guidance on sending Mock Sandbox Request via command line, Open API Specification and Postman.

Smart Sandbox:

This is a full testing environment. It returns a validated response from the database based on the request body content.

  • Smart Sandbox maintains the state of the data, i.e. new invoices inputs, etc.
  • It requires message signing, encryption and Base64 encoding of the request and response payload.
  • It uses the Client Credentials, Profile ID and Encryption keys provided in your Sandbox Project.
  • The password for the client private key is available in client-pgp-keys.info file in your downloaded encryption keys zip file.

Smart Sandbox URL: https://sandbox.corporate-api.hsbc.com/twc/v1

Using Smart Sandbox:

Refer to Making a Smart Sandbox Request for step-by-step guidance on sending Sandbox Sandbox Request via Postman.

Smart Sandbox Test Scenarios

The following testing scenarios are available with the Trade Finance - Seller Loans Smart Sandbox:

  1. Submit Seller loan application to HSBC sandbox via Submit Seller loan application API.
  2. Extend Seller Loan Duration via Submit Seller loan extension request API.
  3. Enquire status of Seller Loans via Request Trade Loan summary list API.
  4. Settle Seller Loan via Submit Seller loan settlement request API.
  5. Enquire status of a specific Seller Loan via Request Trade Loan detail API.

Pre-Requisites:

  1. You have created sandbox access for Trade Finance - Seller Loans via Dev Hub Project and retrieved HSBC Profile ID and credentials.
  2. You have setup your postman and client. Refer to Making a Smart Sandbox Request for details.

Scenario 1 - Submitting Seller Loan application to HSBC

You as a/ on-behalf of your customer PLT-CUSTID-001 (who is a seller), send loan application to HSBC via Submit Seller Loan Application API.

Pre-Requisites
  1. Seller possess valid transaction account in HSBC.
    1. For Smart Sandbox testing, you may define your own transaction account number, e.g. "tradeAccountNumber": "SGHSBC12345678912".
  2. (Optional) Supporting documents have been submitted successfully via Submit Supporting Documents API.
Preparing Unencrypted Request Body

Prepares the Unencrypted Request Body as per Example from POST Seller-loans/standard/Request body/Examples/Unencrypted Request.

  1. API Authorisation:

    HSBC authorises API requests by extnlCustomerId and tradeAccountNumber value pair.

    1. extnlCustomerId:
      1. If you are a partner of HSBC making API requests on-behalf of your platform's customers, specify the unique logon id of your customer on your platform, e.g. "extnlCustomerId":"PLT-CUSTID-001". (per agreed with HSBC during on-boarding)
      2. If you are a direct client of HSBC, specify the API Profile ID assigned to you during on-boarding, e.g. "extnlCustomerId":"Kdet5h221BWKOD5umjrg1fOH4j8iXdS" // HSBC Profile ID
    2. tradeAccountNumber:
      1. Specify the applicant's HSBC current account number. e.g. "tradeAccountNumber":"SGHSBC123456789123".
    					
	  {
        ...
        "extnlCustomerId": "PLT-CUSTID-001",
        "tradeAccountNumber": "SGHSBC123456789123",
        ...
      }

    The above value pair are also required for authorisations of other linked operations.

  2. Loan Details:

    Specify terms, preference, amount, duration and related accounts like below example:

    1. Valued SGD 1000.00, effective from 2023-04-01.
    2. Expected to be repaid in SGD within 30 days from now, i.e. 2023-04-30.
    					
	{
      ... 
      "loanNumber": "",
      "typeOfGoods": "GOODS",
      "goodsShipped": "Y",
      "loanStartDate": "2023-04-01",
      "tenor": "30",
      "loanMaturityDate": "2023-04-30",
      "paymentCurrency": "SGD",
      "paymentAmount": "1000.00",
      "loanCurrency": "SGD",
      "loanAmount": "1000.00",
      "loanRepaymentAccount": "",
      "interestRepaymentAccount": "SGHSBC123456789123",
      "chargesRepaymentAccount": "SGHSBC123456789123",
      "goodsDescription": "T-shirt",
      ...
    }
  3. Involved Parties:

    Specify associated buyer(s) for this loan.

    					
		{
		  ...
		  "buyerDetails": [
			{
			  "buyerName": "BUY-SG001 Holdings Plc.",
			  "buyerCountry": "SG",
			  "buyerAddressLine1": "BUY-SG001 Tower #01-01",
			  "buyerAddressLine2": "1 BUY-SG001 Street",
			  "buyerAddressLine3": "SINGAPORE 12345"
			}
		  ],
		  ...
		}

    It is possible to include multiple buyers.

    					
	{
      ...
      "buyerDetails": [
        {
          "buyerName": "BUY-SG001  Holdings Plc.",
          "buyerCountry": "SG",
          "buyerAddressLine1": "BUY-SG001 Tower #01-01",
          "buyerAddressLine2": "1 BUY-SG001 Street",
          "buyerAddressLine3": "SINGAPORE 12345"
        },
        {
          "buyerName": "BUY-SG002 Holdings Plc.",
          "buyerCountry": "SG",
          "buyerAddressLine1": "BUY-SG001 Tower #01-01",
          "buyerAddressLine2": "1 BUY-SG002 Street",
          "buyerAddressLine3": "SINGAPORE 12345"
        }
      ],
      ...
    }
  4. Payment Details:

    Specify beneficiary's information.

    					
	{
      ...
      "paymentDetails": {
        "beneficiaryName": "BEN-SG001 Holdings Plc.",
        "beneficiaryCountry": "SG",
        "beneficiaryAddressLine1": "BEN-SG001 Tower #01-01",
        "beneficiaryAddressLine2": "1 BEN-SG001 Street",
        "beneficiaryAddressLine3": "SINGAPORE 12345",
        "beneficiaryBankAccount": "AC-BEN-SG001",
        "beneficiaryBankName": "BANK-SG001 Holdings Plc.",
        "beneficiaryBankSwiftBicBranchCode": "HSBCSGS2001",
        "beneficiaryBankBranchName": "BRANCH001",
        "beneficiaryBankCountry": "SG",
        "beneficiaryBankAddressLine1": "BANK-SG001 Tower #01-01",
        "beneficiaryBankAddressLine2": "1 BANK-SG001 Street",
        "beneficiaryBankAddressLine3": "SINGAPORE 12345"
      },
      ...
    }
  5. Supporting Documents:

    Specify supporting documents submitted prior to loan application if any.

    					
	{
      ...
      "supportingDocuments": [
        {
          "docId": "idd_500E9B7F-0000-C23C-AEAB-1B037067FE09",
          "docName": "HSBC-gif.GIF",
          "docCategory": "APP"
        }
      ],
      ...
    }
  6. Instructions to bank::

    Optionally you may specify any special instructions to Bank.

    					
		{ 
		  ... 
		  "instructionsToBank": "Input instructions here if any",
		  ... 
		}
  7. Additional Information:

    Optionally you may specify additional information needed. Please note these information needs to be specified as JSON String.

    					
		{ 
		  ... 
		  "miscStates": "{\"additionalInfo\":\"something\"}"
		}
  8. Full Example: 
    					
	{
      "extnlCustomerId": "PLT-CUSTID-001",
      "tradeAccountNumber": "SGHSBC123456789123",
      "customerReference": "",
      "loanNumber": "",
      "typeOfGoods": "GOODS",
      "goodsShipped": "Y",
      "loanStartDate": "2023-04-01",
      "tenor": "30",
      "loanMaturityDate": "2023-04-30",
      "paymentCurrency": "SGD",
      "paymentAmount": "1000.00",
      "loanCurrency": "SGD",
      "loanAmount": "1000",
      "loanRepaymentAccount": "SGHSBC123456789123",
      "interestRepaymentAccount": "SGHSBC123456789123",
      "chargesRepaymentAccount": "SGHSBC123456789123",
      "goodsDescription": "T-shirt",
      "buyerDetails": [
        {
          "buyerName": "BUY-SG001  Holdings Plc.",
          "buyerCountry": "SG",
          "buyerAddressLine1": "BUY-SG001 Tower #01-01",
          "buyerAddressLine2": "BUY-SG001 Street",
          "buyerAddressLine3": "SINGAPORE 12345"
        }
      ],
      "paymentDetails": {
        "beneficiaryName": "BEN-SG001 Holdings Plc.",
        "beneficiaryCountry": "SG",
        "beneficiaryAddressLine1": "BEN-SG001 Tower #01-01",
        "beneficiaryAddressLine2": "1 BEN-SSG001 Street",
        "beneficiaryAddressLine3": "SINGAPORE 12345",
        "beneficiaryBankAccount": "AC-BEN-SG001",
        "beneficiaryBankName": "BANK-SG001 Holdings Plc.",
        "beneficiaryBankSwiftBicBranchCode": "HSBCHKH2001",
        "beneficiaryBankBranchName": "BRANCH001",
        "beneficiaryBankCountry": "SG",
        "beneficiaryBankAddressLine1": "BANK-SG001 Tower #01-01",
        "beneficiaryBankAddressLine2": "BANK-SG001 Street",
        "beneficiaryBankAddressLine3": "SINGAPORE 12345"
      },
      "supportingDocuments": [
        {
          "docId": "idd_10349C86-0000-C515-AB9B-65B893B9744B",
          "docName": "test.tif",
          "docCategory": "APP"
        }
      ],
      "instructionsToBank": "message for your bank",
      "miscStates": "{\"additionalInfo\":\"something\"}"
    }

Tips: If you are using Sample Java Client provided, copy the above unencrypted request under src/main/resources/stl/SubmitSellerLoanApplication.json

Generating API Request

Encrypts the above request and base64 encodes it as per Making an API Request.

  1. Example of encrypted request body and JSON Web Token:
    1. Encrypted Request: LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tC...
    2. JSON Web Token: JWS eyJ2ZXIiOiIxLjAiLCJraWQiOiIy...
  2. Send API Request
    1. Send the request directly via Sample Java Client, run SubmitSellerLoanApplicationRequest.java under src/main/java/com.runner/stl
    2. Send the request via Postman:
      1. Generate your encrypted request and JSON Web Token via ClientSideTokenEncryption.java under src/main/java/com.runner/
      2. Put the encrypted request string in under Body in Postman
        LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tC...
      3. Specify Header. The JSON Web Token generated should be placed under Authorisation. 
        						
          Authorization:JWS eyJ2ZXIiOiIxLjAiLCJraWQiOiIy...
          requestTime:2023-04-01 00:00:00
          requestId:92aef07bdc4243e99afa9dc2af02c1cf
          Content-Type:application/json
          countryCode: SG
          schemaVersion:1.0
      4. Click Send next to the endpoint URL.
Processing API Response

Upon a successful request, encrypted response in base64 string shall be received

  1. Example of encrypted response:
    1. Encrypted Request: LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tC...
    2. Decodes and decrypts the response as per Processing a response or via Sample Java Client.
  2. Upon successful decryption, you shall be able to obtain the Unencrypted response in JSON structure, as per POST seller-loans/standard/Responses/200/Examples/Unencrypted Response - Success. 
    				
	{
        "code": "EMKT200",
        "message": "Success",
        "repliedTime": "2023-04-01 00:00:43",
        "correlationId": "92aef07bdc4243e99afa9dc2af02c1cf",
        "responseData": {
          "customerReference": "CRSG23040101",
          "applicationId": "20230401SG02",
          "loanNumber": "LNSG23040102",
          "status": "Submitted"
        },
        "errorDetails": null
    }
  3. Congratulations! A loan application request is submitted successfully.
    1. loanNumber = LNSG23030101
    2. applicationId = 20230401SG02
    3. status = Submitted.
    4. You may further process/ enquire this loan via following linked operations.
      1. Request extension of loan via Submit Loan Extension Request
      2. Request settlement of loan via Submit Loan Extension Request
      3. Enquire status of this and other loans via Request Trade Loan Summary List
      4. Enquire details of this loan via Request Trade Loan Detail

Next, let's try enquiring detail of this loan LNSG23040102 via Request Trade Loan Detail .

Scenario 2 - Enquiring detail of a specific loans submitted from HSBC

You as a/ on-behalf of your customer PLT-CUSTID-001, request for details of an already submitted loan LNSG23040102.

Pre-Requisites
  1. Seller possess valid transaction account in HSBC.
    1. For Smart Sandbox testing, you may define your own transaction account number, e.g. "tradeAccountNumber": "SGHSBC12345678912".
  2. Retrieved loanNumber from loan application submission via:
    1. Submit Seller Loan Application Request API .
    2. Submit Seller Loan Extension Request API .
    3. Submit Seller Loan Settlement Request API .
Preparing Unencrypted Request Body

Prepares the Unencrypted Request Body as per Example from POST Seller-loans/standard/Request body/Examples/Unencrypted Request.

  1. API Authorisation:

    HSBC authorises API requests by extnlCustomerId and tradeAccountNumber value pair.

    1. extnlCustomerId:
      1. If you are a partner of HSBC making API requests on-behalf of your platform's customers, specify the unique logon id of your customer on your platform, e.g. "extnlCustomerId":"PLT-CUSTID-001". (per agreed with HSBC during on-boarding)
      2. If you are a direct client of HSBC, specify the API Profile ID assigned to you during on-boarding, e.g. "extnlCustomerId":"Kdet5h221BWKOD5umjrg1fOH4j8iXdS" // HSBC Profile ID
    2. tradeAccountNumber:
      1. Specify the applicant's HSBC current account number. e.g. "tradeAccountNumber":"SGHSBC123456789123".
    3. loanNumber/ applicationId:
      1. Specify either loanNumber or applicationId for the specific loan you would like to enquire. e.g. "loanNumber": "LNSG23040102"/ "applicationId": "20230401SG02".
    					
	{
        "extnlCustomerId": "PLT-CUSTID-001",
        "tradeAccountNumber": "SGHSBC123456789123",
        "applicationId": ""
        "loanNumber": "LNSG23040102"
    }

Tips: If you are using Sample Java Client provided, copy the above unencrypted request under src/main/resources/stl/GetTradeLoanSummaryDetailRequest.json

Generating API Request

Encrypts the above request and base64 encodes it as per Making an API Request.

  1. Example of encrypted request body and JSON Web Token:
    1. Encrypted Request: LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tC...
    2. JSON Web Token: JWS eyJ2ZXIiOiIxLjAiLCJraWQiOiIy...
  2. Send API Request
    1. Send the request directly via Sample Java Client, run GetTradeLoanDetailRequest.java under src/main/java/com.runner/stl
    2. Send the request via Postman:
      1. Generate your encrypted request and JSON Web Token via ClientSideTokenEncryption.java under src/main/java/com.runner/
      2. Put the encrypted request string in under Body in Postman
        LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tC...
      3. Specify Header. The JSON Web Token generated should be placed under Authorisation. 
        						
          Authorization:JWS eyJ2ZXIiOiIxLjAiLCJraWQiOiIy...
          requestTime:2023-04-01 00:00:00
          requestId:92aef07bdc4243e99afa9dc2af02c1cf
          Content-Type:application/json
          countryCode: SG
          schemaVersion:1.0
      4. Click Send next to the endpoint URL.
Processing API Response

Upon a successful request, encrypted response in base64 string shall be received

  1. Example of encrypted response:
    1. Encrypted Request: LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tC...
    2. Decodes and decrypts the response as per Processing a response or via Sample Java Client.
  2. Upon successful decryption, you shall be able to obtain the Unencrypted response in JSON structure, as per POST seller-loans/standard/Responses/200/Examples/Unencrypted Response - Success. 
    				
		{
          "code": "EMKT200",
          "message": "Success",
          "repliedTime": "2023-04-01 00:00:43",
          "correlationId": "efbf054e8f9c477493bfb3d2a19781b2",
          "responseData": {
            "tradeAccountNumber": "SGHSBC123456789123",
            "customerReference": "",
            "loanNumber": "LNSG23040102",
            "productType": "Seller loan",
            "typeOfGoods": "GOODS",
            "loanStartDate": "2023-04-01",
            "tenor": "30",
            "loanMaturityDate": "2023-04-30",
            "paymentCurrency": "SGD",
            "paymentAmount": "1000.00",
            "loanAmountInPaymentCurrency": "1000.00",
            "loanCurrency": "SGD",
            "status": "Settled",
            "outstandingCurrency": "SGD",
            "outstandingAmount": "0.00",
            "loanAmountOutstanding": "0.00",
            "totalInterestPaid": "SGD 0.00",
            "interestOutstanding": "1000.00",
            "fixedOrVariableRateLoan": "Fixed",
            "currentInterestRate": "0%",
            "interestCalculationPreference": "S",
            "interestCollectionFrequency": "S",
            "loanRepaymentAccount": "SGHSBC123456789123",
            "interestRepaymentAccount": "SGHSBC123456789123",
            "chargesRepaymentAccount": "SGHSBC123456789123",
            "beneficiaryDetail": [
              {
                "paymentMethod": "local payment",
                "amountCurrency": "",
                "amount": "",
                "beneficiaryName": "",
                "beneficiaryReferenceNumber": "",
                "beneficiaryCountry": "",
                "beneficiaryAddressLine1": "",
                "beneficiaryAddressLine2": "",
                "beneficiaryAddressLine3": "",
                "beneficiaryBankAccount": "AC-BEN-SG001",
                "beneficiaryBankName": "BANK-SG001 Holdings Plc.",
                "beneficiaryBankSwiftBicBranchCode": "HSBCSGS2001",
                "beneficiaryBankBranchName": "BRANCH001",
                "beneficiaryBankCountry": "SG",
                "beneficiaryBankAddressLine1": "BANK-SG001 Tower #01-01",
                "beneficiaryBankAddressLine2": "1 BANK-SG001 Street",
                "beneficiaryBankAddressLine3": "SINGAPORE 12345"
              }
            ],
            ,
            "dateRecorded": "2023-04-01",
            "creationDateAndTime": "2023-04-01 00:00:43"
          },
          "errorDetails": null
        }
  3. Records matches filtering criteria in the request shall be listed. (Up to specified pageSize) You may enquire summary of loans submitted via following linked operations.
    1. Enquire summary list of this and other loan(s) via Request Trade Loan Summary List

Next, let's try submitting extension request for this loan LNSG23040102 via Submit Seller Loan Extension Request .

Scenario 3 - Extending duration of loan submitted to HSBC

You as a/ on-behalf of your customer PLT-CUSTID-001, request for an extension of for loan LNSG23040102's duration from 30 days to 60 days. Hence, the new due date, i.e. loanExtensionMaturityDate to be changed from 2023-04-15 to 2023-05-14.

Pre-Requisites
  1. Seller possess valid transaction account in HSBC.
    1. For Smart Sandbox testing, you may define your own transaction account number, e.g. "tradeAccountNumber": "SGHSBC12345678912".
  2. Retrieved corresponding loanNumber via:
    1. Submit Seller Loan Application Request API during application.
    2. Request Trade Loan Summary API if you have saved corresponding loanNumber during application.
  3. status of corresponding loan is Disbursed.
  4. Corresponding loanMaturityDate is larger or equal to current date.
Preparing Unencrypted Request Body

Prepares the Unencrypted Request Body as per Example from POST Seller-loans/standard/Request body/Examples/Unencrypted Request.

  1. API Authorisation:

    HSBC authorises API requests by extnlCustomerId and tradeAccountNumber value pair.

    1. extnlCustomerId:
      1. If you are a partner of HSBC making API requests on-behalf of your platform's customers, specify the unique logon id of your customer on your platform, e.g. "extnlCustomerId":"PLT-CUSTID-001". (per agreed with HSBC during on-boarding)
      2. If you are a direct client of HSBC, specify the API Profile ID assigned to you during on-boarding, e.g. "extnlCustomerId":"Kdet5h221BWKOD5umjrg1fOH4j8iXdS" // HSBC Profile ID
    2. tradeAccountNumber:
      1. Specify the applicant's HSBC current account number. e.g. "tradeAccountNumber":"SGHSBC123456789123".
    3. loanNumber:
      1. Specify the loan number for the specific loan you would like to extend. e.g. "loanNumber": "LNSG23040102".
    					
		{
			...
			"extnlCustomerId": "PLT-CUSTID-001",
			"tradeAccountNumber": "SGHSBC123456789123",
			"loanNumber": "LNSG23040102",
			...
        }
  2. Extension Duration:

    Specify the to-be duration and reason for loan extension. For example:

    1. Seller would like to extend the duration from 30 days to 60 days. Hence, set "loanExtensionTenor": "60".
    2. Optionally, specify the to-be maturity date, i.e. "loanExtensionMaturityDate": "2023-05-29".
    					
		{
          ...
          "loanExtensionTenor": "60",
          "loanExtensionMaturityDate": "",
          "reasonForLoanExtension": "extend loan date",
          "instructionsToBank": "message for your bank",
          ...
        }
  3. Additional Information:

    Optionally you may specify additional information needed. Please note these information needs to be specified as JSON String.

    					
		{ 
          ... 
          "miscStates": "{\"additionalInfo\":\"something\"}"
        }
  4. Full Example: 
    					
		{
          "extnlCustomerId": "PLT-CUSTID-001",
          "tradeAccountNumber": "SGHSBC123456789123",
          "loanNumber": "LNSG23040102",
          "loanExtensionTenor": "60",
          "loanExtensionMaturityDate": "",
          "reasonForLoanExtension": "extend loan date",
          "instructionsToBank": "message for your bank",
          "miscStates": ""
        }

Tips: If you are using Sample Java Client provided, copy the above unencrypted request under src/main/resources/stl/SubmitSellerLoanExtensionRequest.json

Generating API Request

Encrypts the above request and base64 encodes it as per Making an API Request.

  1. Example of encrypted request body and JSON Web Token:
    1. Encrypted Request: LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tC...
    2. JSON Web Token: JWS eyJ2ZXIiOiIxLjAiLCJraWQiOiIy...
  2. Send API Request
    1. Send the request directly via Sample Java Client, run SubmitSellerLoanExtensionRequest.java under src/main/java/com.runner/stl
    2. Send the request via Postman:
      1. Generate your encrypted request and JSON Web Token via ClientSideTokenEncryption.java under src/main/java/com.runner/
      2. Put the encrypted request string in under Body in Postman
        LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tC...
      3. Specify Header. The JSON Web Token generated should be placed under Authorisation. 
        							
          Authorization:JWS eyJ2ZXIiOiIxLjAiLCJraWQiOiIy...
          requestTime:2023-04-01 00:00:00
          requestId:92aef07bdc4243e99afa9dc2af02c1cf
          Content-Type:application/json
          countryCode: SG
          schemaVersion:1.0
      4. Click Send next to the endpoint URL.
Processing API Response

Upon a successful request, encrypted response in base64 string shall be received

  1. Example of encrypted response:
    1. Encrypted Request: LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tC...
    2. Decodes and decrypts the response as per Processing a response or via Sample Java Client.
  2. Upon successful decryption, you shall be able to obtain the Unencrypted response in JSON structure, as per POST seller-loans/standard/Responses/200/Examples/Unencrypted Response - Success. 
    					
	{
        "code": "EMKT200",
        "message": "Success",
        "repliedTime": "2023-04-01 00:00:43",
        "correlationId": "92aef07bdc4243e99afa9dc2af02c1cf",
        "responseData": {
          "applicationId": "46338647WB6W",
          "loanNumber": "LNSG23040102",
          "status": "Extension Submitted"
        },
        "errorDetails": null
    }
  3. Upon a loan extension request is submitted successfully, status will be changed to Extension Submitted for the corresponding loan. You may further process/ enquire this loan via following linked operations.
    1. Request extension of loan via Submit Loan Extension Request
    2. Request settlement of loan via Submit Loan Extension Request
    3. Enquire status of this and other loans via Request Trade Loan Summary List
    4. Enquire details of this loan via Request Trade Loan Detail

Next, let's try submitting settlement request for this loan LNSG23040102 via Submit Seller Loan Settlement Request.

Scenario 4 - Settling loan submitted to HSBC

You as a/ on-behalf of your customer PLT-CUSTID-001, request for settlement of loan LNSG23040102 valued SGD 1000.00 on 2023-05-29.

Pre-Requisites
  1. Seller possess valid transaction account in HSBC.
    1. For Smart Sandbox testing, you may define your own transaction account number, e.g. "tradeAccountNumber": "SGHSBC12345678912".
  2. Retrieved corresponding loanNumber via:
    1. Submit Seller Loan Application Request API during application.
    2. Request Trade Loan Summary API if you have saved corresponding loanNumber during application.
  3. status of corresponding loan is Disbursed.
  4. Corresponding loanMaturityDate is larger or equal to current date.
Preparing Unencrypted Request Body

Prepares the Unencrypted Request Body as per Example from POST Seller-loans/standard/Request body/Examples/Unencrypted Request.

  1. API Authorisation:

    HSBC authorises API requests by extnlCustomerId and tradeAccountNumber value pair.

    1. extnlCustomerId:
      1. If you are a partner of HSBC making API requests on-behalf of your platform's customers, specify the unique logon id of your customer on your platform, e.g. "extnlCustomerId":"PLT-CUSTID-001". (per agreed with HSBC during on-boarding)
      2. If you are a direct client of HSBC, specify the API Profile ID assigned to you during on-boarding, e.g. "extnlCustomerId":"Kdet5h221BWKOD5umjrg1fOH4j8iXdS" // HSBC Profile ID
    2. tradeAccountNumber:
      1. Specify the applicant's HSBC current account number. e.g. "tradeAccountNumber":"SGHSBC123456789123".
    3. loanNumber:
      1. Specify the loan number for the specific loan you would like to settle. e.g. "loanNumber": "LNSG23040102".
    					
		{
			...
			"extnlCustomerId": "PLT-CUSTID-001",
			"tradeAccountNumber": "SGHSBC123456789123",
			"loanNumber": "LNSG23040102",
			...
        }
  2. Repayment Details:

    Specify the date and amount for loan settlement. For example:

    1. Repayment date 2023-05-29. Hence, specify "repaymentDate": "2023-05-29".
    2. Loan valued 1000.00. Hence, specify "repaymentAmount": "1000.00".
    					
		{
          ...
          "repaymentDate": "2023-05-29",
          "repaymentAmount": "1000.00",
          "repaymentAccountNumber": "SGHSBC123456789123",
          "interestAccountNumber": "SGHSBC123456789123",
          "chargesAccountNumber": "SGHSBC123456789123",
		  "instructionsToBank": "message for your bank",
          ...
        }
  3. Additional Information:

    Optionally you may specify additional information needed. Please note these information needs to be specified as JSON String.

    					
		{ 
          ... 
          "miscStates": "{\"additionalInfo\":\"something\"}"
        }
  4. Full Example: 
    					
		{
          "extnlCustomerId": "PLT-CUSTID-001",
          "tradeAccountNumber": "SGHSBC123456789123",
          "repaymentDate": "2023-05-29",
          "repaymentAmount": "1000.00",
          "repaymentAccountNumber": "SGHSBC123456789123",
          "interestAccountNumber": "SGHSBC123456789123",
          "chargesAccountNumber": "SGHSBC123456789123",
          "instructionsToBank": "message for your bank",
          "miscStates": ""
        }

Tips: If you are using Sample Java Client provided, copy the above unencrypted request under src/main/resources/stl/SubmitSellerLoanSettlementRequest.json

Generating API Request

Encrypts the above request and base64 encodes it as per Making an API Request.

  1. Example of encrypted request body and JSON Web Token:
    1. Encrypted Request: LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tC...
    2. JSON Web Token: JWS eyJ2ZXIiOiIxLjAiLCJraWQiOiIy...
  2. Send API Request
    1. Send the request directly via Sample Java Client, run SubmitSellerLoanSettlementRequest.java under src/main/java/com.runner/stl
    2. Send the request via Postman:
      1. Generate your encrypted request and JSON Web Token via ClientSideTokenEncryption.java under src/main/java/com.runner/
      2. Put the encrypted request string in under Body in Postman
        LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tC...
      3. Specify Header. The JSON Web Token generated should be placed under Authorisation. 
        							
          Authorization:JWS eyJ2ZXIiOiIxLjAiLCJraWQiOiIy...
          requestTime:2023-04-01 00:00:00
          requestId:92aef07bdc4243e99afa9dc2af02c1cf
          Content-Type:application/json
          countryCode: SG
          schemaVersion:1.0
      4. Click Send next to the endpoint URL.
Processing API Response

Upon a successful request, encrypted response in base64 string shall be received

  1. Example of encrypted response:
    1. Encrypted Request: LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tC...
    2. Decodes and decrypts the response as per Processing a response or via Sample Java Client.
  2. Upon successful decryption, you shall be able to obtain the Unencrypted response in JSON structure, as per POST seller-loans/standard/Responses/200/Examples/Unencrypted Response - Success. 
    					
	{
        "code": "EMKT200",
        "message": "Success",
        "repliedTime": "2023-04-01 00:00:43",
        "correlationId": "92aef07bdc4243e99afa9dc2af02c1cf",
        "responseData": {
          "applicationId": "46338647WB6W",
          "loanNumber": "LNSG23040102",
          "status": "Settlement Submitted"
        },
        "errorDetails": null
    }
  3. Upon a loan settlement request is submitted successfully, status will be changed to Settlement Submitted for the corresponding loan. You may further process/ enquire this loan via following linked operations.
    1. Enquire status of this and other loans via Request Trade Loan Summary List
    2. Enquire details of this loan via Request Trade Loan Detail

Next, let's try enquiring a summary list for all submitted/ processed loans via Request Trade Loan Summary .

Scenario 5 - Enquiring Status of Loans submitted from HSBC

You as a/ on-behalf of your customer PLT-CUSTID-001, request for a summary for already submitted loan applications.

Pre-Requisites
  1. Seller possess valid transaction account in HSBC.
    1. For Smart Sandbox testing, you may define your own transaction account number, e.g. "tradeAccountNumber": "SGHSBC12345678912".
  2. Loan(s) had been submitted/ processed via:
    1. Submit Seller Loan Application Request API .
    2. Submit Seller Loan Extension Request API .
    3. Submit Seller Loan Settlement Request API .
  3. status of corresponding loan is Disbursed.
  4. Corresponding loanMaturityDate is larger or equal to current date.
Preparing Unencrypted Request Body

Prepares the Unencrypted Request Body as per Example from POST Seller-loans/standard/Request body/Examples/Unencrypted Request.

  1. API Authorisation:

    HSBC authorises API requests by extnlCustomerId and tradeAccountNumber value pair.

    1. extnlCustomerId:
      1. If you are a partner of HSBC making API requests on-behalf of your platform's customers, specify the unique logon id of your customer on your platform, e.g. "extnlCustomerId":"PLT-CUSTID-001". (per agreed with HSBC during on-boarding)
      2. If you are a direct client of HSBC, specify the API Profile ID assigned to you during on-boarding, e.g. "extnlCustomerId":"Kdet5h221BWKOD5umjrg1fOH4j8iXdS" // HSBC Profile ID
    2. tradeAccountNumber:
      1. Specify the applicant's HSBC current account number. e.g. "tradeAccountNumber":"SGHSBC123456789123".
    					
		{
			...
			"extnlCustomerId": "PLT-CUSTID-001",
			"tradeAccountNumber": "SGHSBC123456789123",
			...
        }
  2. Paginations:

    Specify display properties for transactions to be Retrieved

    1. Assume that the enquiry page on your platform will be displaying up to 10 transactions (loans), set the "pageSize": "10".
    2. Here, set "pageNumber": "1" so as to receive a response with up to the first 10 transactions matching all filtering criteria.
    3. Filtering of customerReference, loanNumber, status and beneficiaryName are optional.
    					
		{
		  "pageSize": "10",
		  "pageNumber": "1",
		  ...
		  "customerReference": "",
		  "loanNumber": "",
		  "status": "",
		  "beneficiaryName": ""
        }
  3. Full Example: 
    					
		{
          "pageSize": "10",
          "pageNumber": "1",
          "extnlCustomerId": "PLT-CUSTID-001",
          "tradeAccountNumber": "SGHSBC123456789123",
          "customerReference": "",
          "loanNumber": "",
          "status": "",
          "beneficiaryName": ""
        }

Tips: If you are using Sample Java Client provided, copy the above unencrypted request under src/main/resources/stl/ListTradeLoanSummaryRequest.json

Generating API Request

Encrypts the above request and base64 encodes it as per Making an API Request.

  1. Example of encrypted request body and JSON Web Token:
    1. Encrypted Request: LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tC...
    2. JSON Web Token: JWS eyJ2ZXIiOiIxLjAiLCJraWQiOiIy...
  2. Send API Request
    1. Send the request directly via Sample Java Client, run SubmitListTradeLoanSummaryRequest.java under src/main/java/com.runner/stl
    2. Send the request via Postman:
      1. Generate your encrypted request and JSON Web Token via ClientSideTokenEncryption.java under src/main/java/com.runner/
      2. Put the encrypted request string in under Body in Postman
        LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tC...
      3. Specify Header. The JSON Web Token generated should be placed under Authorisation. 
        							
          Authorization:JWS eyJ2ZXIiOiIxLjAiLCJraWQiOiIy...
          requestTime:2023-04-01 00:00:00
          requestId:92aef07bdc4243e99afa9dc2af02c1cf
          Content-Type:application/json
          countryCode: SG
          schemaVersion:1.0
      4. Click Send next to the endpoint URL.
Processing API Response

Upon a successful request, encrypted response in base64 string shall be received

  1. Example of encrypted response:
    1. Encrypted Request: LS0tLS1CRUdJTiBQR1AgTUVTU0FHRS0tLS0tC...
    2. Decodes and decrypts the response as per Processing a response or via Sample Java Client.
  2. Upon successful decryption, you shall be able to obtain the Unencrypted response in JSON structure, as per POST seller-loans/standard/Responses/200/Examples/Unencrypted Response - Success. 
    					
					{
  "code": "EMKT200",
  "message": "Success",
  "repliedTime": "2023-04-01 00:00:43",
  "correlationId": "efbf054e8f9c477493bfb3d2a19781b2",
  "responseData": {
    "pageSize": "10",
    "pageNumber": "1",
    "totalCount": "7",
    "records": [
      {
        "tradeAccountNumber": "SGHSBC12345678912",
        "productType": "Seller Loan",
        "beneficiaryName": "",
        "customerReference": "",
        "loanNumber": "LNSG23040102",
        "paymentCurrency": "",
        "loanAmountInPaymentCurrency": "",
        "loanCurrency": "SGD",
        "status": "Settlement Submitted",
        "loanStartDate": "2023-04-01",
        "loanMaturityDate": "2023-05-29",
        "tenor": "60",
        "outstandingCurrency": "SGD",
        "outstandingAmount": "1000.00",
        "creationDateAndTime": ""
      },
      {
        "tradeAccountNumber": "SGHSBC12345678912",
        "productType": "Seller Loan",
        "beneficiaryName": "",
        "customerReference": "",
        "loanNumber": "LNSG23040101",
        "paymentCurrency": "",
        "loanAmountInPaymentCurrency": "",
        "loanCurrency": "HKD",
        "status": "Submitted",
        "loanStartDate": "2023-04-01",
        "loanMaturityDate": "2023-04-30",
        "tenor": "30",
        "outstandingCurrency": "HKD",
        "outstandingAmount": "1000.00",
        "creationDateAndTime": ""
      },
      {
        "tradeAccountNumber": "SGHSBC12345678912",
        "productType": "Seller Loan",
        "beneficiaryName": "",
        "customerReference": "",
        "loanNumber": "LNSG23031502",
        "paymentCurrency": "",
        "loanAmountInPaymentCurrency": "",
        "loanCurrency": "USD",
        "status": "Extension Submitted",
        "loanStartDate": "2023-03-15",
        "loanMaturityDate": "2023-05-14",
        "tenor": "60",
        "outstandingCurrency": "USD",
        "outstandingAmount": "1000.00",
        "creationDateAndTime": ""
      },
      {
        "tradeAccountNumber": "SGHSBC12345678912",
        "productType": "Seller Loan",
        "beneficiaryName": "",
        "customerReference": "",
        "loanNumber": "LNSG23031501",
        "paymentCurrency": "",
        "loanAmountInPaymentCurrency": "",
        "loanCurrency": "SGD",
        "status": "Disbursed",
        "loanStartDate": "2023-03-15",
        "loanMaturityDate": "2023-04-14",
        "tenor": "30",
        "outstandingCurrency": "SGD",
        "outstandingAmount": "1000.00",
        "creationDateAndTime": ""
      },
      {
        "tradeAccountNumber": "SGHSBC12345678912",
        "productType": "Seller Loan",
        "beneficiaryName": "",
        "customerReference": "",
        "loanNumber": "LNSG23030103",
        "paymentCurrency": "",
        "loanAmountInPaymentCurrency": "",
        "loanCurrency": "HKD",
        "status": "Cancelled",
        "loanStartDate": "2023-03-01",
        "loanMaturityDate": "2023-03-30",
        "tenor": "30",
        "outstandingCurrency": "HKD",
        "outstandingAmount": "0.00",
        "creationDateAndTime": ""
      },
      {
        "tradeAccountNumber": "SGHSBC12345678912",
        "productType": "Seller Loan",
        "beneficiaryName": "",
        "customerReference": "",
        "loanNumber": "LNSG23030102",
        "paymentCurrency": "",
        "loanAmountInPaymentCurrency": "",
        "loanCurrency": "GBP",
        "status": "Settlement Submitted",
        "loanStartDate": "2023-03-01",
        "loanMaturityDate": "2023-04-01",
        "tenor": "31",
        "outstandingCurrency": "GBP",
        "outstandingAmount": "1000.00",
        "creationDateAndTime": ""
      },
      {
        "tradeAccountNumber": "SGHSBC12345678912",
        "productType": "Seller Loan",
        "beneficiaryName": "",
        "customerReference": "",
        "loanNumber": "LNSG23030101",
        "paymentCurrency": "",
        "loanAmountInPaymentCurrency": "",
        "loanCurrency": "JPY",
        "status": "Settled",
        "loanStartDate": "2023-03-01",
        "loanMaturityDate": "2023-03-30",
        "tenor": "30",
        "outstandingCurrency": "JPY",
        "outstandingAmount": "0.00",
        "creationDateAndTime": ""
      }
    ]
  }
}
  3. Records matches filtering criteria in the request shall be listed. (Up to specified pageSize) You may enquire details of a specific loan via following linked operations.
    1. Enquire details of a specific loan via Request Trade Loan Detail

Congratulations for completing all testing scenarios. Refer to Go-Live for next steps.

Version History

Change log and release history:

Version Release Date Status Description
beta March 2023 Live Trade Finance - Seller Loans - Beta Release

Return to top

Next: Endpoints

© HSBC Bank plc 2026