# Acme Citibank Hong Kong Payments (H2H) (https://docs.tryacme.com/guides/citi-hk-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 Citibank 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**
>
> * Batch payments, sent to Citibank as host-to-host (H2H) files. Create them with [Create a Batch Payment](https://docs.tryacme.com/reference/post-batch-payments).
> * Single payments are not supported.
Supported types: `HK_FPS_PROXY`, `HK_FPS_ACCOUNT`, `HK_CHATS`, `TT`, `BKTR`.
### 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 ` `
* FPS Name Character Set:
* The 26 uppercase Latin letters `A`-`Z`
* The 10 digits `0`-`9`
* Space ` `
* The characters `'` `/` `(` `)` `,` `.` `&` `$` `+` `*` `=` `-`
* BIC:
* 8 or 11 character Bank Identifier Code in uppercase, for example `HSBCHKHHXXX`.
* Citi restrictions:
* For SWIFT character set: do not start a field with any of the following characters: `/`, `-`, `:`
## General notes [#general-notes]
* A batch holds up to 1,000 payments.
* `paymentDate` must not be in the past. It can be at most 20 days ahead.
* `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).
## ISO 20022 Migration [#iso-20022-migration]
> **Citi address requirements**
>
> * Citi is moving to the ISO 20022 (CBPR+) address format. If a receiver address is provided, it must carry a town name and a country.
> * In Hong Kong, this applies to `HK_CHATS` and `TT`. `HK_FPS_PROXY`, `HK_FPS_ACCOUNT` and `BKTR` are not in Citi's scope.
> * Citi rejects an in-scope payment whose address is missing `address.city` or `address.country`. This becomes mandatory in November 2026.
> * Acme already enforces this:
> * `HK_CHATS`: the address is optional. If you provide it, `address.city` and `address.country` are mandatory, and `address.country` must be `HK`.
> * `TT`: `address.city` and `address.country` are always mandatory.
> * Acme sends `postalCode`, `city`, `state` and `country` as structured fields, and `line1` and `line2` as address lines.
## 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.
* The `customerReference` is sent to the bank as the end-to-end ID of the payment.
## HK_FPS_PROXY [#hk_fps_proxy]
> **Important**
>
> * Currency must be **HKD only**.
> * Pay to an FPS proxy. Do not send `receiver.bank` or `receiver.bankAccountNumber`.
> * `receiver.name` must be in **uppercase** and use the FPS Name Character Set.
> * `paymentDetails` is limited to 15 characters.
> * Do not send a purpose code. Acme sends every FPS payment with Citi transaction type `23` (HK Faster Payments).
| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| payments[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments[N].paymentDetails | SWIFT | 15 | O |
| payments[N].instructionForSenderBank | SWIFT | 35 | O |
| payments[N].paymentAdviceEmails[N] | Valid email address
Example: ["[finance@company.com](mailto:finance@company.com)"] | 50 per email (max 1 email) | O |
| payments[N].receiver.name | FPS Name (uppercase only) | 70 | M |
| payments[N].receiver.proxyType | `MOBILE` or `EMAIL` or `FPS_ID` or `HKID` | | M |
| payments[N].receiver.proxyValue
for MOBILE | `+` country code, `-`, then the number
Example: `+852-91234567` | 34 | M |
| payments[N].receiver.proxyValue
for EMAIL | Email address | 34 | M |
| payments[N].receiver.proxyValue
for FPS_ID | Digits | 7 | M |
| payments[N].receiver.proxyValue
for HKID | Hong Kong identity card number | 20 | M |
| payments[N].receiver.address.line1 | SWIFT | 35 | O |
| payments[N].receiver.address.line2 | SWIFT | 35 | O |
| payments[N].receiver.address.city | SWIFT | 35 | O |
| payments[N].receiver.address.state | SWIFT | 35 | O |
| payments[N].receiver.address.postalCode | SWIFT | 16 | O |
| payments[N].receiver.address.country | `HK` | 2 | O |
Example Request:
```json
{
"type": "HK_FPS_PROXY",
"paymentDate": "2026-11-16",
"senderAccountId": "intacc_0H3BQNTQGBW2W",
"currency": "HKD",
"payments": [
{
"amount": 150000,
"customerReference": "INV2026001",
"paymentDetails": "INV2026001",
"receiver": {
"name": "CHAN TAI MAN",
"proxyType": "MOBILE",
"proxyValue": "+852-91234567"
}
}
]
}
```
## HK_FPS_ACCOUNT [#hk_fps_account]
> **Important**
>
> * Currency must be **HKD only**.
> * Pay to a bank account.
> * Send the 6 digit bank and branch code in `receiver.localRoutingIdentifier`.
> * Do not send `receiver.bank`.
> * `receiver.name` must be in **uppercase** and use the FPS Name Character Set.
> * `paymentDetails` is limited to 15 characters.
> * Do not send a purpose code. Acme sends every FPS payment with Citi transaction type `23` (HK Faster Payments).
| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| payments[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments[N].paymentDetails | SWIFT | 15 | O |
| payments[N].instructionForSenderBank | SWIFT | 35 | O |
| payments[N].paymentAdviceEmails[N] | Valid email address
Example: ["[finance@company.com](mailto:finance@company.com)"] | 50 per email (max 1 email) | O |
| payments[N].receiver.name | FPS Name (uppercase only) | 70 | M |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | M |
| payments[N].receiver.localRoutingIdentifier | 6 digits: bank code and branch code
Example: `004123` | 6 | M |
| payments[N].receiver.address.line1 | SWIFT | 35 | O |
| payments[N].receiver.address.line2 | SWIFT | 35 | O |
| payments[N].receiver.address.city | SWIFT | 35 | O |
| payments[N].receiver.address.state | SWIFT | 35 | O |
| payments[N].receiver.address.postalCode | SWIFT | 16 | O |
| payments[N].receiver.address.country | `HK` | 2 | O |
Example Request:
```json
{
"type": "HK_FPS_ACCOUNT",
"paymentDate": "2026-11-16",
"senderAccountId": "intacc_0H3BQNTQGBW2W",
"currency": "HKD",
"payments": [
{
"amount": 150000,
"customerReference": "INV2026002",
"paymentDetails": "INV2026002",
"receiver": {
"name": "CHAN TAI MAN",
"bankAccountNumber": "123456789012",
"localRoutingIdentifier": "004123"
}
}
]
}
```
## HK_CHATS [#hk_chats]
> **Important**
>
> * Currency must be **HKD only**.
> * `bankChargeBearer` is mandatory.
> * If you provide `receiver.address`, `address.city` and `address.country` are mandatory. See [ISO 20022 Migration](#iso-20022-migration).
> * `address.country` must be `HK`.
| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| payments[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments[N].paymentDetails | SWIFT | 140 | O |
| payments[N].bankChargeBearer | `SENDER` or `RECEIVER` or `SHARED` | | M |
| payments[N].paymentAdviceEmails[N] | Valid email address
Example: ["[finance@company.com](mailto:finance@company.com)"] | 50 per email (max 1 email) | O |
| payments[N].receiver.name | SWIFT | 35 | M |
| payments[N].receiver.bank | BIC | 11 | M |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | M |
| payments[N].receiver.address.line1 | SWIFT | 35 | O |
| payments[N].receiver.address.line2 | SWIFT | 35 | O |
| payments[N].receiver.address.city | SWIFT | 35 | Conditional: M if `address` is provided ([ISO 20022](#iso-20022-migration)) |
| payments[N].receiver.address.state | SWIFT | 35 | O |
| payments[N].receiver.address.postalCode | SWIFT | 16 | O |
| payments[N].receiver.address.country | `HK` | 2 | Conditional: M if `address` is provided ([ISO 20022](#iso-20022-migration)) |
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": "HSBCHKHHXXX",
"bankAccountNumber": "123456789012",
"address": {
"line1": "1 Queen's Road Central",
"city": "Hong Kong",
"country": "HK"
}
}
}
]
}
```
## TT [#tt]
> **Important**
>
> * Currency can be any valid ISO 4217 currency code.
> * `receiver.address.city` and `receiver.address.country` are always mandatory. See [ISO 20022 Migration](#iso-20022-migration).
> * If `bankChargeBearer` is not provided, Acme sends `SHARED`.
| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| payments[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments[N].paymentDetails | SWIFT | 140 | O |
| payments[N].instructionForSenderBank | SWIFT | 35 | O |
| payments[N].bankChargeBearer | `SENDER` or `RECEIVER` or `SHARED`
Default to `SHARED` if not provided. | | O |
| payments[N].paymentAdviceEmails[N] | Valid email address
Example: ["[finance@company.com](mailto:finance@company.com)"] | 50 per email (max 1 email) | O |
| payments[N].receiver.name | SWIFT | 35 | M |
| payments[N].receiver.bank | BIC | 11 | M |
| payments[N].receiver.intermediaryBank | BIC | 11 | O |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | M |
| payments[N].receiver.address.line1 | SWIFT | 35 | O |
| payments[N].receiver.address.line2 | SWIFT | 35 | O |
| payments[N].receiver.address.city | SWIFT | 35 | M ([ISO 20022](#iso-20022-migration)) |
| payments[N].receiver.address.state | SWIFT | 35 | O |
| payments[N].receiver.address.postalCode | SWIFT | 16 | O |
| payments[N].receiver.address.country | [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | 2 | M ([ISO 20022](#iso-20022-migration)) |
Example Request:
```json
{
"type": "TT",
"paymentDate": "2026-11-16",
"senderAccountId": "intacc_0H3BQNTQGBW2W",
"currency": "USD",
"payments": [
{
"amount": 2500000,
"customerReference": "INV2026004",
"paymentDetails": "Payment for invoice 2026004",
"bankChargeBearer": "SHARED",
"receiver": {
"name": "Example Supplies Pte Ltd",
"bank": "DBSSSGSGXXX",
"bankAccountNumber": "0123456789",
"address": {
"line1": "1 Example Road",
"city": "Singapore",
"postalCode": "123456",
"country": "SG"
}
}
}
]
}
```
## BKTR [#bktr]
> **Important**
>
> * Book transfer to another Citibank Hong Kong account. Do not send `receiver.bank`.
> * Currency can be any valid ISO 4217 currency code.
> * Do not send `bankChargeBearer`.
| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| paymentDate | `YYYY-MM-DD` | | M |
| payments[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments[N].paymentDetails | SWIFT | 140 | O |
| payments[N].instructionForSenderBank | SWIFT | 35 | O |
| payments[N].paymentAdviceEmails[N] | Valid email address
Example: ["[finance@company.com](mailto:finance@company.com)"] | 50 per email (max 1 email) | O |
| payments[N].receiver.name | SWIFT | 35 | M |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | M |
| payments[N].receiver.address.line1 | SWIFT | 35 | O |
| payments[N].receiver.address.line2 | SWIFT | 35 | O |
| payments[N].receiver.address.city | SWIFT | 35 | O |
| payments[N].receiver.address.state | SWIFT | 35 | O |
| payments[N].receiver.address.postalCode | SWIFT | 16 | O |
| payments[N].receiver.address.country | `HK` | 2 | O |
Example Request:
```json
{
"type": "BKTR",
"paymentDate": "2026-11-16",
"senderAccountId": "intacc_0H3BQNTQGBW2W",
"currency": "HKD",
"payments": [
{
"amount": 150000,
"customerReference": "INV2026005",
"paymentDetails": "Payment for invoice 2026005",
"receiver": {
"name": "Example Trading Limited",
"bankAccountNumber": "1234567890"
}
}
]
}
```
## Bank references [#bank-references]
| Sent as | `bankReference` | `bankReferences` | Available from |
| --- | --- | --- | --- |
| A file | `AcctSvcrRef`, else `ClrSysRef` | `AcctSvcrRef`, `ClrSysRef`, `StsId`, as Citi sends them | Citi's status report on the payment |
On your Citi statement, the line shows a different Citi reference. Find the payment by your `customerReference`.
What the names mean:
* `AcctSvcrRef`: Citi's own reference for the transaction.
* `ClrSysRef`: the clearing system's reference.
* `StsId`: the id of Citi's status entry.
A rejected payment keeps the references from the report that rejected it.
A completed payment returns:
```json
{
"bankReference": "01720322200000001",
"bankReferences": {
"AcctSvcrRef": "01720322200000001"
}
}
```