Acme HSBC Bank Hong Kong Payments (API)

This describes validations / allowed data formats for Acme payments going through HSBC Bank Hong Kong. These will be validated by Acme and further validated by the bank. These rules may be stricter than what the bank requires.

Supported types: HK_FPS_ACCOUNT, HK_CHATS, TT.

Common DefinitionsCopy Anchor Link

• SWIFT Character Set:

  • The 26 uppercase Latin letters A-Z
  • The 26 lowercase Latin letters a-z
  • The 10 digits 0-9
  • Forward slash /
  • Hyphen -
  • Question mark ?
  • Colon :
  • Left and right parentheses ( )
  • Full stop .
  • Comma ,
  • Single quote '
  • Plus sign +
  • Space

• BIC11:

  • 11-character Bank Identifier Code

General notesCopy Anchor Link

• The receiver.address.country must be an uppercase 2-letter ISO 3166 country code (e.g. HK for Hong Kong).
• The format for BIC (used in receiver.bank) is strictly validated using [A-Z]{6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3})? (as specified in ISO20022 BICFIIdentifier).
• amount is in minor units. For example, 150000 is HKD 1,500.00. See Minor units format.
• instructionForSenderBank is not supported for HSBC Hong Kong.
• If bankChargeBearer is not provided, Acme sends no charge bearer and HSBC applies its default.

ISO 20022 addressCopy Anchor Link

Payment Customer ReferenceCopy Anchor Link

• Use customerReference as the unique identifier of your payments.
• customerReference must use uppercase letters and digits only, up to 16 characters. HSBC shows it as is on your statement.
• If customerReference is not provided, Acme generates a 13 character unique alphanumeric reference.
• The customerReference is sent to the bank as the end-to-end ID of the payment.

HK_FPS_ACCOUNTCopy Anchor Link

Example Request:

{
  "type": "HK_FPS_ACCOUNT",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "currency": "HKD",
  "amount": 150000,
  "customerReference": "INV2026001",
  "paymentDetails": "Payment for invoice 2026001",
  "purposeCode": "SUPP",
  "receiver": {
    "name": "Chan Tai Man",
    "bankAccountNumber": "123456789012",
    "localRoutingIdentifier": "004",
    "address": {
      "line1": "1 Queen's Road Central",
      "city": "Hong Kong",
      "country": "HK"
    }
  }
}

FPS purpose codesCopy Anchor Link

• Source: HSBC ASP Purpose of Payment Formatting Guide, HK Faster Payment System Purpose of Payment List.
• The purpose code applies to FPS payments only: HK_FPS_ACCOUNT here, and HK_FPS_PROXY and HK_FPS_ACCOUNT in batch payments.
• Send exactly 4 characters.
• Acme does not validate the code value against this list.

HK_CHATSCopy Anchor Link

Example Request:

{
  "type": "HK_CHATS",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "currency": "HKD",
  "amount": 50000000,
  "customerReference": "INV2026002",
  "paymentDetails": "Payment for invoice 2026002",
  "bankChargeBearer": "SENDER",
  "receiver": {
    "name": "Example Trading Limited",
    "bank": "BKCHHKHHXXX",
    "bankAccountNumber": "012345678901",
    "address": {
      "line1": "1 Garden Road",
      "city": "Hong Kong",
      "country": "HK"
    }
  }
}

TTCopy Anchor Link

Example Request:

{
  "type": "TT",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "currency": "USD",
  "amount": 2500000,
  "customerReference": "INV2026003",
  "paymentDetails": "Payment for invoice 2026003",
  "bankChargeBearer": "SHARED",
  "receiver": {
    "name": "Example Supplies Pte Ltd",
    "bank": "DBSSSGSGXXX",
    "bankAccountNumber": "0123456789",
    "address": {
      "line1": "1 Example Road",
      "city": "Singapore",
      "postalCode": "123456",
      "country": "SG"
    }
  }
}

Bank referencesCopy Anchor Link

bankReference is null for HSBC Hong Kong payments sent through the API: HSBC sends no payment reference to use as bankReference. bankReferences has referenceId, HSBC's id for the request, from HSBC's answer to the request.

A completed payment returns:

{
  "bankReference": null,
  "bankReferences": {
    "referenceId": "6f0c2a8e-3b1d-4c5e-9a7f-2d4b6c8e0a1b"
  }
}