Acme logoAcme docs
GuidesAPI referenceChangelog
Bank payment rules

Acme Citibank Hong Kong Payments (H2H)

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.
  • Single payments are not supported.

Supported types: HK_FPS_PROXY, HK_FPS_ACCOUNT, HK_CHATS, TT, BKTR.

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

  • 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.

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

  • 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

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).
fieldpattern / charsetmax lengthmandatory/optional
paymentDateYYYY-MM-DDM
payments[N].customerReferenceSWIFT (uppercase only)15O
payments[N].paymentDetailsSWIFT15O
payments[N].instructionForSenderBankSWIFT35O
payments[N].paymentAdviceEmails[N]Valid email address
Example: ["finance@company.com"]		50 per email (max 1 email)O
payments[N].receiver.nameFPS Name (uppercase only)70M
payments[N].receiver.proxyTypeMOBILE or EMAIL or FPS_ID or HKIDM
payments[N].receiver.proxyValue
for MOBILE		+ country code, -, then the number
Example: +852-91234567		34M
payments[N].receiver.proxyValue
for EMAIL		Email address34M
payments[N].receiver.proxyValue
for FPS_ID		Digits7M
payments[N].receiver.proxyValue
for HKID		Hong Kong identity card number20M
payments[N].receiver.address.line1SWIFT35O
payments[N].receiver.address.line2SWIFT35O
payments[N].receiver.address.citySWIFT35O
payments[N].receiver.address.stateSWIFT35O
payments[N].receiver.address.postalCodeSWIFT16O
payments[N].receiver.address.countryHK2O

Example Request:

{
  "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

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).
fieldpattern / charsetmax lengthmandatory/optional
paymentDateYYYY-MM-DDM
payments[N].customerReferenceSWIFT (uppercase only)15O
payments[N].paymentDetailsSWIFT15O
payments[N].instructionForSenderBankSWIFT35O
payments[N].paymentAdviceEmails[N]Valid email address
Example: ["finance@company.com"]		50 per email (max 1 email)O
payments[N].receiver.nameFPS Name (uppercase only)70M
payments[N].receiver.bankAccountNumberAlphanumeric34M
payments[N].receiver.localRoutingIdentifier6 digits: bank code and branch code
Example: 004123		6M
payments[N].receiver.address.line1SWIFT35O
payments[N].receiver.address.line2SWIFT35O
payments[N].receiver.address.citySWIFT35O
payments[N].receiver.address.stateSWIFT35O
payments[N].receiver.address.postalCodeSWIFT16O
payments[N].receiver.address.countryHK2O

Example Request:

{
  "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

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.
  • address.country must be HK.
fieldpattern / charsetmax lengthmandatory/optional
paymentDateYYYY-MM-DDM
payments[N].customerReferenceSWIFT (uppercase only)15O
payments[N].paymentDetailsSWIFT140O
payments[N].bankChargeBearerSENDER or RECEIVER or SHAREDM
payments[N].paymentAdviceEmails[N]Valid email address
Example: ["finance@company.com"]		50 per email (max 1 email)O
payments[N].receiver.nameSWIFT35M
payments[N].receiver.bankBIC11M
payments[N].receiver.bankAccountNumberAlphanumeric34M
payments[N].receiver.address.line1SWIFT35O
payments[N].receiver.address.line2SWIFT35O
payments[N].receiver.address.citySWIFT35Conditional: M if address is provided (ISO 20022)
payments[N].receiver.address.stateSWIFT35O
payments[N].receiver.address.postalCodeSWIFT16O
payments[N].receiver.address.countryHK2Conditional: M if address is provided (ISO 20022)

Example Request:

{
  "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

Important

  • Currency can be any valid ISO 4217 currency code.
  • receiver.address.city and receiver.address.country are always mandatory. See ISO 20022 Migration.
  • If bankChargeBearer is not provided, Acme sends SHARED.
fieldpattern / charsetmax lengthmandatory/optional
paymentDateYYYY-MM-DDM
payments[N].customerReferenceSWIFT (uppercase only)15O
payments[N].paymentDetailsSWIFT140O
payments[N].instructionForSenderBankSWIFT35O
payments[N].bankChargeBearerSENDER or RECEIVER or SHARED
Default to SHARED if not provided.		O
payments[N].paymentAdviceEmails[N]Valid email address
Example: ["finance@company.com"]		50 per email (max 1 email)O
payments[N].receiver.nameSWIFT35M
payments[N].receiver.bankBIC11M
payments[N].receiver.intermediaryBankBIC11O
payments[N].receiver.bankAccountNumberAlphanumeric34M
payments[N].receiver.address.line1SWIFT35O
payments[N].receiver.address.line2SWIFT35O
payments[N].receiver.address.citySWIFT35M (ISO 20022)
payments[N].receiver.address.stateSWIFT35O
payments[N].receiver.address.postalCodeSWIFT16O
payments[N].receiver.address.countryISO 3166-1 alpha-22M (ISO 20022)

Example Request:

{
  "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

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.
fieldpattern / charsetmax lengthmandatory/optional
paymentDateYYYY-MM-DDM
payments[N].customerReferenceSWIFT (uppercase only)15O
payments[N].paymentDetailsSWIFT140O
payments[N].instructionForSenderBankSWIFT35O
payments[N].paymentAdviceEmails[N]Valid email address
Example: ["finance@company.com"]		50 per email (max 1 email)O
payments[N].receiver.nameSWIFT35M
payments[N].receiver.bankAccountNumberAlphanumeric34M
payments[N].receiver.address.line1SWIFT35O
payments[N].receiver.address.line2SWIFT35O
payments[N].receiver.address.citySWIFT35O
payments[N].receiver.address.stateSWIFT35O
payments[N].receiver.address.postalCodeSWIFT16O
payments[N].receiver.address.countryHK2O

Example Request:

{
  "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

Sent asbankReferencebankReferencesAvailable from
A fileAcctSvcrRef, else ClrSysRefAcctSvcrRef, ClrSysRef, StsId, as Citi sends themCiti'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:

{
  "bankReference": "01720322200000001",
  "bankReferences": {
    "AcctSvcrRef": "01720322200000001"
  }
}

Acme Citibank China Payments (H2H)

Previous Page

Acme Citibank Indonesia Payments (H2H)

Next Page

On this page

Common DefinitionsGeneral notesISO 20022 MigrationPayment Customer ReferenceHK_FPS_PROXYHK_FPS_ACCOUNTHK_CHATSTTBKTRBank references