Acme docs

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.
For single payments, see Acme HSBC Bank Hong Kong Payments (API).

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

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

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).
amount is in minor units. For example, 150000 is HKD 1,500.00. See 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

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

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

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.
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 Example: `E01`	3	O
payments[N].customerReference	ASCII	35	O
payments[N].paymentDetails	ASCII	140	O
payments[N].purposeCode	4 letters See 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 Example: ["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 for FPS_ID	1 to 9 digits	9	M
payments[N].receiver.proxyValue for EMAIL	Email address		M
payments[N].receiver.proxyValue for MOBILE	`+` country code, `-`, then the number 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:

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

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.
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 Example: `E01`	3	O
payments[N].customerReference	ASCII	35	O
payments[N].paymentDetails	ASCII	140	O
payments[N].purposeCode	4 letters See 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 Example: ["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) 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:

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

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 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 Example: ["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:

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

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 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 Example: ["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) 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:

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

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 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 Example: ["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:

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

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:

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

Acme HSBC Bank Hong Kong Payments (H2H)

Common Definitions

General notes

ISO 20022 address

Payment Customer Reference

HK_FPS_PROXY

HK_FPS_ACCOUNT

HK_CHATS

HK_ACH

TT

Bank references

On this page

Acme HSBC Bank Hong Kong Payments (H2H)

Common DefinitionsCopy Anchor Link

General notesCopy Anchor Link

ISO 20022 addressCopy Anchor Link

Payment Customer ReferenceCopy Anchor Link

HK_FPS_PROXYCopy Anchor Link

HK_FPS_ACCOUNTCopy Anchor Link

HK_CHATSCopy Anchor Link

HK_ACHCopy Anchor Link

TTCopy Anchor Link

Bank referencesCopy Anchor Link

On this page

Common Definitions

General notes

ISO 20022 address

Payment Customer Reference

HK_FPS_PROXY

HK_FPS_ACCOUNT

HK_CHATS

HK_ACH

TT

Bank references