Acme HSBC Bank Vietnam Payments (H2H)

This describes validations / allowed data formats for Acme payments going through HSBC Bank Vietnam. These will be validated by Acme and further validated by the bank. These rules may be stricter than what the bank requires.

Supported types: VN_NAPAS, VN_RTGS, VN_ACH, TT. Tax payments are sent as VN_RTGS.

Common DefinitionsCopy Anchor Link

• ASCII Character Set:

  • Printable ASCII characters, from space to tilde ~.
  • This includes A-Z, a-z, 0-9, space and the punctuation characters !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~.
  • Vietnamese characters with diacritics, such as ă, ê or ư, are not allowed. Write Nguyen Van An, not Nguyễn Văn An.

• BIC:

  • 8 or 11 character Bank Identifier Code in uppercase, for example BFTVVNVXXXX.
  • Validated with [A-Z]{6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3})? (as specified in ISO20022 BICFIIdentifier).

General notesCopy Anchor Link

• A batch holds up to 1,000 payments.
• amount is in minor units. VND has no minor unit, so 5000000 is VND 5,000,000. See Minor units format.
• The maximum amount per payment is 999,999,999 minor units. For VND, that is VND 999,999,999.
• receiver.address.country must be an uppercase 2 letter ISO 3166 country code (e.g. VN for Vietnam).
• The receiver address lines, city, state, postalCode and country must fit in 3 lines of 35 characters together.
• instructionForSenderBank is not supported for HSBC Vietnam.
• paymentSetCode is a batch level field. It is optional.
• 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 addressCopy Anchor Link

Payment Customer ReferenceCopy Anchor Link

• Use payments[N].customerReference as the unique identifier of your payments.
• If customerReference is not provided, Acme generates a 13 character unique alphanumeric reference.
• For VN_RTGS and TT, HSBC uses the first 16 characters of customerReference as the end-to-end ID of the payment. Keep it to 16 characters so it stays unique.
• For VN_ACH, purposeOfPayment is sent as the end-to-end ID of the payment.

VN_NAPASCopy Anchor Link

Example Request:

{
  "type": "VN_NAPAS",
  "paymentDate": "2026-11-16",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "currency": "VND",
  "payments": [
    {
      "amount": 5000000,
      "customerReference": "INV2026001",
      "paymentDetails": "Payment for invoice 2026001",
      "receiver": {
        "name": "Nguyen Van An",
        "bankAccountNumber": "0123456789",
        "localRoutingIdentifier": "970436"
      }
    }
  ]
}

VN_RTGSCopy Anchor Link

Example Request:

{
  "type": "VN_RTGS",
  "paymentDate": "2026-11-16",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "currency": "VND",
  "payments": [
    {
      "amount": 750000000,
      "customerReference": "INV2026002",
      "paymentDetails": "Payment for invoice 2026002",
      "bankChargeBearer": "SHARED",
      "receiver": {
        "name": "Cong Ty TNHH Example",
        "bank": "BFTVVNVXXXX",
        "bankAccountNumber": "0123456789",
        "localRoutingIdentifier": "01203001"
      }
    }
  ]
}

Tax paymentCopy Anchor Link

• taxItems must have at least one item.

What the tax fields mean (source: HSBC Input Guide for Tax and Customs):

• localTaxType:
  • 01: taxes managed by the General Department of Taxation, such as corporate income tax, personal income tax and VAT.
  • 02: fees and charges of ministries.
  • 03: taxes and fees managed by other departments, such as administrative fines.
  • 04: payments managed by the General Department of Customs.
• taxCode: the taxpayer's tax code (MST), including any branch suffix, for example 0101234567-001.
• collectingAuthorityCode: the code of the tax office that collects the payment (CQT).
• stateTreasuryCode: the code of the state treasury that receives the payment (KB).
• chapterCode and subItemCode: the budget chapter (C) and sub-item (TM) of the tax.
• taxPeriod: Acme sends it to HSBC as follows.

Example Request:

{
  "type": "VN_RTGS",
  "paymentDate": "2026-11-16",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "currency": "VND",
  "payments": [
    {
      "amount": 15000000,
      "customerReference": "TAX2026001",
      "receiver": {
        "name": "Kho bac Nha nuoc Example",
        "bankAccountNumber": "7111123456789"
      },
      "taxPayment": {
        "localTaxType": "01",
        "taxCode": "0101234567",
        "collectingAuthorityCode": "1054321",
        "stateTreasuryCode": "0011",
        "taxItems": [
          {
            "taxPeriod": "Oct",
            "chapterCode": "754",
            "subItemCode": "1701",
            "amount": 15000000
          }
        ]
      }
    }
  ]
}

VN_ACHCopy Anchor Link

Example Request:

{
  "type": "VN_ACH",
  "paymentDate": "2026-11-16",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "currency": "VND",
  "payments": [
    {
      "amount": 12000000,
      "customerReference": "PAY2026003",
      "purposeOfPayment": "SALARY OCT 2026 001",
      "paymentDetails": "Salary October 2026",
      "receiver": {
        "name": "Nguyen Van An",
        "bank": "BFTVVNVXXXX",
        "bankAccountNumber": "0123456789",
        "localRoutingIdentifier": "01203001"
      }
    }
  ]
}

TTCopy Anchor Link

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"
        }
      }
    }
  ]
}

Bank referencesCopy Anchor Link

bankReference is usually null for HSBC Vietnam 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"
  }
}