# Acme HSBC Bank Hong Kong Payments (H2H) (https://docs.tryacme.com/guides/hsbc-hk-h2h-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: H2H**
>
> * This page covers batch payments, sent to HSBC as host-to-host (H2H) files. Create them with [Create a Batch Payment](https://docs.tryacme.com/reference/post-batch-payments).
> * For single payments, see [Acme HSBC Bank Hong Kong Payments (API)](https://docs.tryacme.com/guides/hsbc-hk-api-payments).

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

### Common Definitions [#common-definitions]

* ASCII Character Set:
  * Printable ASCII characters, from space ` ` to tilde `~`.
  * This includes `A`-`Z`, `a`-`z`, `0`-`9`, space and the punctuation characters ``!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~``.

* BIC11:
  * 11-character Bank Identifier Code

## General notes [#general-notes]

* A batch holds up to 1,000 payments.
* 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).
* The maximum amount per payment is 999,999,999 minor units (HKD 9,999,999.99).
* `instructionForSenderBank` is not supported for HSBC Hong Kong.
* If `bankChargeBearer` is not provided, Acme sends no charge bearer and HSBC applies its default.
* `paymentSetCode` is a batch level field.
* It is a 3 character code configured on HSBCnet to group payment instructions under an access or entitlement group.
* The value must match a payment set code configured in HSBCnet. Please contact the bank for the code to use.

## ISO 20022 address [#iso-20022-address]

> **Important**
>
> * HSBC Hong Kong payments use the ISO 20022 structured address.
> * `receiver.address` is mandatory for every type except `HK_ACH`, 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 `payments[N].customerReference` as the unique identifier of your payments.
* If `customerReference` is not provided, Acme generates a 13 character unique alphanumeric reference.
* HSBC uses the first 16 characters of `customerReference` as the end-to-end ID of the payment, or the first 18 for `HK_ACH`. This is the reference HSBC checks for duplicates and shows on your statement. Keep it to 16 characters (18 for `HK_ACH`) so it stays unique.

## HK_FPS_PROXY [#hk_fps_proxy]

> **Important**
>
> * Currency must be **HKD** or **CNY**.
> * The maximum amount is 1,000,000.00 per payment.
> * Pay to an FPS proxy. Do not send `receiver.bankAccountNumber` or `receiver.localRoutingIdentifier`.
> * `purposeCode` is mandatory. Use a 4 letter code from [FPS purpose codes](https://docs.tryacme.com/guides/hsbc-hk-api-payments#fps-purpose-codes).
> * `purposeOfPayment` is mandatory. Acme does not send it to HSBC. HSBC receives the purpose from `purposeCode`.

| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| paymentSetCode | ASCII <br /> Example: `E01` | 3 | O |
| payments[N].customerReference | ASCII | 35 | O |
| payments[N].paymentDetails | ASCII | 140 | O |
| payments[N].purposeCode | 4 letters <br /> See [FPS purpose codes](https://docs.tryacme.com/guides/hsbc-hk-api-payments#fps-purpose-codes) | 4 | M |
| payments[N].purposeOfPayment | ASCII | 140 | M |
| payments[N].bankChargeBearer | `SENDER` or `RECEIVER` or `SHARED` | | O |
| payments[N].paymentAdviceEmails[N] | Valid email address <br /> Example: ["[finance@company.com](mailto:finance@company.com)"] | 2048 per email (max 6 emails) | O |
| payments[N].receiver.name | ASCII | 70 | O |
| payments[N].receiver.bank | BIC11 | 11 | M |
| payments[N].receiver.proxyType | `FPS_ID` or `EMAIL` or `MOBILE` | | M |
| payments[N].receiver.proxyValue <br />for FPS_ID | 1 to 9 digits | 9 | M |
| payments[N].receiver.proxyValue <br />for EMAIL | Email address | | M |
| payments[N].receiver.proxyValue <br />for MOBILE | `+` country code, `-`, then the number <br /> Example: `+852-91234567` | | M |
| payments[N].receiver.address.line1 | ASCII | 35 | O |
| payments[N].receiver.address.city | ASCII | 35 | M |
| payments[N].receiver.address.state | ASCII | 35 | O |
| payments[N].receiver.address.postalCode | ASCII | 35 | O |
| payments[N].receiver.address.country | ISO 3166-1 alpha-2 | 2 | M |

Example Request:

```json
{
  "type": "HK_FPS_PROXY",
  "paymentDate": "2026-11-16",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "currency": "HKD",
  "payments": [
    {
      "amount": 150000,
      "customerReference": "INV2026001",
      "paymentDetails": "Payment for invoice 2026001",
      "purposeCode": "SUPP",
      "purposeOfPayment": "Supplier payment",
      "receiver": {
        "name": "Chan Tai Man",
        "bank": "HSBCHKHHXXX",
        "proxyType": "MOBILE",
        "proxyValue": "+852-91234567",
        "address": {
          "city": "Hong Kong",
          "country": "HK"
        }
      }
    }
  ]
}
```

## 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`.
> * `purposeCode` is mandatory. Use a 4 letter code from [FPS purpose codes](https://docs.tryacme.com/guides/hsbc-hk-api-payments#fps-purpose-codes).
> * `purposeOfPayment` is mandatory. Acme does not send it to HSBC. HSBC receives the purpose from `purposeCode`.

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

Example Request:

```json
{
  "type": "HK_FPS_ACCOUNT",
  "paymentDate": "2026-11-16",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "currency": "HKD",
  "payments": [
    {
      "amount": 150000,
      "customerReference": "INV2026002",
      "paymentDetails": "Payment for invoice 2026002",
      "purposeCode": "SALA",
      "purposeOfPayment": "Salary October 2026",
      "receiver": {
        "name": "Chan Tai Man",
        "bank": "HSBCHKHHXXX",
        "bankAccountNumber": "123456789012",
        "localRoutingIdentifier": "004",
        "address": {
          "city": "Hong Kong",
          "country": "HK"
        }
      }
    }
  ]
}
```

## 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 |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| paymentSetCode | ASCII <br /> Example: `E01` | 3 | O |
| payments[N].customerReference | ASCII | 35 | O |
| payments[N].paymentDetails | ASCII | 140 | O |
| payments[N].bankChargeBearer | `SENDER` or `RECEIVER` or `SHARED` | | O |
| payments[N].paymentAdviceEmails[N] | Valid email address <br /> Example: ["[finance@company.com](mailto:finance@company.com)"] | 2048 per email (max 6 emails) | O |
| payments[N].receiver.name | ASCII | 70 | M |
| payments[N].receiver.bank | BIC11 | 11 | M |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | M |
| payments[N].receiver.address.line1 | ASCII | 35 | O |
| payments[N].receiver.address.city | ASCII | 35 | M |
| payments[N].receiver.address.state | ASCII | 35 | O |
| payments[N].receiver.address.postalCode | ASCII | 35 | O |
| payments[N].receiver.address.country | ISO 3166-1 alpha-2 | 2 | M |

Example Request:

```json
{
  "type": "HK_CHATS",
  "paymentDate": "2026-11-16",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "currency": "HKD",
  "payments": [
    {
      "amount": 50000000,
      "customerReference": "INV2026003",
      "paymentDetails": "Payment for invoice 2026003",
      "bankChargeBearer": "SENDER",
      "receiver": {
        "name": "Example Trading Limited",
        "bank": "BKCHHKHHXXX",
        "bankAccountNumber": "012345678901",
        "address": {
          "line1": "1 Garden Road",
          "city": "Hong Kong",
          "country": "HK"
        }
      }
    }
  ]
}
```

## HK_ACH [#hk_ach]

> **Important**
>
> * Currency must be **HKD** or **CNY**.
> * `paymentSetCode` is mandatory for `HK_ACH`.
> * `receiver.name` is limited to 20 characters.
> * Send the receiver bank's 3 digit bank code, or its 6 digit bank and branch code, in `receiver.localRoutingIdentifier`.
> * `receiver.address` is optional.
> * If `address.country` is not provided, Acme takes the country from `receiver.bank`.

| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| paymentSetCode | ASCII <br /> Example: `E01` | 3 | M |
| payments[N].customerReference | ASCII | 18 | O |
| payments[N].paymentDetails | ASCII | 140 | O |
| payments[N].bankChargeBearer | `SENDER` or `RECEIVER` or `SHARED` | | O |
| payments[N].paymentAdviceEmails[N] | Valid email address <br /> Example: ["[finance@company.com](mailto:finance@company.com)"] | 2048 per email (max 6 emails) | O |
| payments[N].receiver.name | ASCII | 20 | M |
| payments[N].receiver.bank | BIC11 | 11 | M |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | M |
| payments[N].receiver.localRoutingIdentifier | 3 digits (bank code) or 6 digits (bank and branch code) <br /> Example: `004` | 6 | M |
| payments[N].receiver.address.line1 | ASCII | 35 | O |
| payments[N].receiver.address.city | ASCII | 35 | O |
| payments[N].receiver.address.state | ASCII | 35 | O |
| payments[N].receiver.address.postalCode | ASCII | 35 | O |
| payments[N].receiver.address.country | ISO 3166-1 alpha-2 | 2 | O |

Example Request:

```json
{
  "type": "HK_ACH",
  "paymentDate": "2026-11-16",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "currency": "HKD",
  "paymentSetCode": "E01",
  "payments": [
    {
      "amount": 2500000,
      "customerReference": "PAY2026004",
      "paymentDetails": "Salary October 2026",
      "receiver": {
        "name": "Chan Tai Man",
        "bank": "HSBCHKHHXXX",
        "bankAccountNumber": "123456789012",
        "localRoutingIdentifier": "004"
      }
    }
  ]
}
```

## 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 |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| paymentSetCode | ASCII <br /> Example: `E01` | 3 | O |
| payments[N].customerReference | ASCII | 35 | O |
| payments[N].paymentDetails | ASCII | 140 | O |
| payments[N].bankChargeBearer | `SENDER` or `RECEIVER` or `SHARED` | | O |
| payments[N].paymentAdviceEmails[N] | Valid email address <br /> Example: ["[finance@company.com](mailto:finance@company.com)"] | 2048 per email (max 6 emails) | O |
| payments[N].receiver.name | ASCII | 70 | M |
| payments[N].receiver.bank | BIC11 | 11 | M |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | M |
| payments[N].receiver.address.line1 | ASCII | 35 | O |
| payments[N].receiver.address.city | ASCII | 35 | M |
| payments[N].receiver.address.state | ASCII | 35 | O |
| payments[N].receiver.address.postalCode | ASCII | 35 | O |
| payments[N].receiver.address.country | ISO 3166-1 alpha-2 | 2 | M |

Example Request:

```json
{
  "type": "TT",
  "paymentDate": "2026-11-16",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "currency": "USD",
  "payments": [
    {
      "amount": 2500000,
      "customerReference": "INV2026005",
      "paymentDetails": "Payment for invoice 2026005",
      "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 usually `null` for HSBC Hong Kong batch payments: HSBC sends no payment reference to use as `bankReference`. `bankReferences` has `StsId`, HSBC's id for the transaction, from HSBC's status file on the payment.

Good to know:

* If an HSBC status file does carry `AcctSvcrRef` (HSBC's own reference for the transaction) or `ClrSysRef` (the clearing system's reference), Acme keeps it, and `bankReference` is set to `AcctSvcrRef`, else `ClrSysRef`.
* Until HSBC's first status file on the payment, `bankReferences` is `{}`.

A completed payment returns:

```json
{
  "bankReference": null,
  "bankReferences": {
    "StsId": "I175000003940001"
  }
}
```