# Acme HSBC Bank Hong Kong Payments (API) (https://docs.tryacme.com/guides/hsbc-hk-api-payments)

> For AI agents: the documentation index is at [llms.txt](https://docs.tryacme.com/llms.txt), with every page in one file at [llms-full.txt](https://docs.tryacme.com/llms-full.txt). Each page is also available as Markdown by appending `.md` to its URL.

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.

> **Channel: API**
>
> * This page covers single payments through HSBC's API. Create them with [Create a Payment](https://docs.tryacme.com/reference/post-payments).
> * For batch payments, see [Acme HSBC Bank Hong Kong Payments (H2H)](https://docs.tryacme.com/guides/hsbc-hk-h2h-payments).

Supported types: `HK_FPS_ACCOUNT`, `HK_CHATS`, `TT`.

### Common Definitions [#common-definitions]

* 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 <code style="{whiteSpace: 'pre'}"> </code>

* BIC11:
  * 11-character Bank Identifier Code

## General notes [#general-notes]

* 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](https://www.iso20022.org/standardsrepository/type/BICFIIdentifier)).
* `amount` is in minor units. For example, `150000` is HKD 1,500.00. See [Minor units format](https://docs.tryacme.com/guides/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 address [#iso-20022-address]

> **Important**
>
> * HSBC Hong Kong payments use the ISO 20022 structured address.
> * `receiver.address` is mandatory for every type, with `address.city` and `address.country`.
> * Acme sends `address.line1` as the street name, and `city`, `state`, `postalCode` and `country` as their own fields.
> * The address lines, `city`, `state`, `postalCode` and `country` must fit in 3 lines of 35 characters together.

## Payment Customer Reference [#payment-customer-reference]

* 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_ACCOUNT [#hk_fps_account]

> **Important**
>
> * Currency must be **HKD** or **CNY**.
> * The maximum amount is 1,000,000.00 per payment.
> * Send the receiver bank's 3 digit bank code in `receiver.localRoutingIdentifier`.
> * `receiver.bank` is optional.
> * `purposeCode` is mandatory. Use a 4 letter code from [FPS purpose codes](#fps-purpose-codes).

| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| customerReference | Uppercase letters and digits | 16 | O |
| paymentDetails | SWIFT | 140 | O |
| purposeCode | 4 letters <br /> See [FPS purpose codes](#fps-purpose-codes) | 4 | M |
| bankChargeBearer | `SENDER` or `RECEIVER` or `SHARED` | | O |
| paymentAdviceEmails[N] | Valid email address <br /> Example: ["[finance@company.com](mailto:finance@company.com)"] | 2048 per email (max 6 emails) | O |
| receiver.name | SWIFT | 70 | M |
| receiver.bank | BIC11 | 11 | O |
| receiver.bankAccountNumber | Alphanumeric | 34 | M |
| receiver.localRoutingIdentifier | 3 digits (bank code) <br /> Example: `004` | 3 | M |
| receiver.address.line1 | SWIFT | 35 | O |
| receiver.address.city | SWIFT | 35 | M |
| receiver.address.state | SWIFT | 35 | O |
| receiver.address.postalCode | SWIFT | 16 | O |
| receiver.address.country | ISO 3166-1 alpha-2 | 2 | M |

Example Request:

```json
{
  "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 codes [#fps-purpose-codes]

* 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](https://docs.tryacme.com/guides/hsbc-hk-h2h-payments).
* Send exactly 4 characters.
* Acme does not validate the code value against this list.

| code | description |
| --- | --- |
| `BONU` | Bonus |
| `SALA` | Salary |
| `DIVI` | Dividend |
| `COMM` | Commission |
| `PENS` | Pension |
| `ALLW` | Allowance |
| `RENT` | Rent |
| `REFD` | Refund |
| `UTIL` | Utilities |
| `EXPE` | Expenses |
| `REBA` | Rebate |
| `SUPP` | Supplier |
| `TAXS` | Tax |
| `INTC` | Intra-company |
| `TREA` | Treasury |
| `INTE` | Interest |
| `OTHR` | Other |
| `LOAN` | Loan |
| `GOVT` | Government |

## HK_CHATS [#hk_chats]

> **Important**
>
> * Currency must be **HKD**, **CNY**, **USD** or **EUR**.
> * Send the receiver bank's BIC in `receiver.bank`. Do not send `receiver.localRoutingIdentifier`.

| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| customerReference | Uppercase letters and digits | 16 | O |
| paymentDetails | SWIFT | 140 | O |
| bankChargeBearer | `SENDER` or `RECEIVER` or `SHARED` | | O |
| paymentAdviceEmails[N] | Valid email address <br /> Example: ["[finance@company.com](mailto:finance@company.com)"] | 2048 per email (max 6 emails) | O |
| receiver.name | SWIFT | 70 | M |
| receiver.bank | BIC11 | 11 | M |
| receiver.bankAccountNumber | Alphanumeric | 34 | M |
| receiver.address.line1 | SWIFT | 35 | O |
| receiver.address.city | SWIFT | 35 | M |
| receiver.address.state | SWIFT | 35 | O |
| receiver.address.postalCode | SWIFT | 16 | O |
| receiver.address.country | ISO 3166-1 alpha-2 | 2 | M |

Example Request:

```json
{
  "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"
    }
  }
}
```

## TT [#tt]

> **Important**
>
> * Currency must be one of: AED, AUD, BHD, BND, CAD, CHF, DKK, EGP, EUR, GBP, HKD, HUF, IDR, INR, JPY, KHR, KRW, KWD, LKR, MUR, MYR, NOK, NPR, NZD, PHP, PLN, QAR, SAR, SEK, SGD, THB, TWD, USD, VND, ZAR.
> * Send the receiver bank's BIC in `receiver.bank`. Do not send `receiver.localRoutingIdentifier`.

| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| customerReference | Uppercase letters and digits | 16 | O |
| paymentDetails | SWIFT | 140 | O |
| bankChargeBearer | `SENDER` or `RECEIVER` or `SHARED` | | O |
| paymentAdviceEmails[N] | Valid email address <br /> Example: ["[finance@company.com](mailto:finance@company.com)"] | 2048 per email (max 6 emails) | O |
| receiver.name | SWIFT | 70 | M |
| receiver.bank | BIC11 | 11 | M |
| receiver.bankAccountNumber | Alphanumeric | 34 | M |
| receiver.address.line1 | SWIFT | 35 | O |
| receiver.address.city | SWIFT | 35 | M |
| receiver.address.state | SWIFT | 35 | O |
| receiver.address.postalCode | SWIFT | 16 | O |
| receiver.address.country | ISO 3166-1 alpha-2 | 2 | M |

Example Request:

```json
{
  "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 references [#bank-references]

`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:

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