# Acme HSBC Bank Vietnam Payments (H2H) (https://docs.tryacme.com/guides/hsbc-vn-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 Vietnam. 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 HSBC 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: `VN_NAPAS`, `VN_RTGS`, `VN_ACH`, `TT`. Tax payments are sent as `VN_RTGS`.

### 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 ``!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~``.
  * 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](https://www.iso20022.org/standardsrepository/type/BICFIIdentifier)).

## General notes [#general-notes]

* 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](https://docs.tryacme.com/guides/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 address [#iso-20022-address]

> * HSBC Vietnam payments use the ISO 20022 structured address.
> * Acme sends `address.line1` as the street name, and `city`, `state`, `postalCode` and `country` as their own fields.
> * For `VN_NAPAS`, `VN_RTGS` and `VN_ACH`, Acme always sends the receiver's country as `VN`.
> * For `TT`, `receiver.address.country` is mandatory.

## 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.
* 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_NAPAS [#vn_napas]

> **Important**
>
> * Real time domestic transfer through NAPAS 247.
> * Currency must be **VND only**.
> * The maximum amount is VND 499,999,999 per payment.
> * Send the receiver bank's 6 digit NAPAS BIN in `receiver.localRoutingIdentifier`. Do not send `receiver.bank`.
> * `paymentDetails` is limited to 105 characters.
> * If `bankChargeBearer` is not provided, Acme sends no charge bearer and HSBC applies its default.

| 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 | 105 | 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 | 140 | M |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | M |
| payments[N].receiver.localRoutingIdentifier | 6 digits (NAPAS BIN) <br /> Example: `970436` | 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": "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_RTGS [#vn_rtgs]

> **Important**
>
> * High value domestic transfer through the interbank payment system (IBPS).
> * Currency must be **VND only**.
> * Send the receiver bank's BIC in `receiver.bank` and its 8 digit local bank code in `receiver.localRoutingIdentifier`.
> * Acme sends the first 8 characters of `receiver.bank` (BIC8).
> * If `bankChargeBearer` is not provided, Acme sends `SHARED`.
> * For a tax payment, add `taxPayment`. See [Tax payment](#tax-payment).

| 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` <br /> Default to `SHARED` if not provided. | | 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 | 140 | M |
| payments[N].receiver.bank | BIC | 11 | M (see [Tax payment](#tax-payment)) |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | M |
| payments[N].receiver.localRoutingIdentifier | 8 digits (local bank code) <br /> Example: `01203001` | 8 | M (see [Tax payment](#tax-payment)) |
| 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": "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 payment [#tax-payment]

> **Important**
>
> * A tax payment is a `VN_RTGS` payment with `taxPayment`. It is only supported for `VN_RTGS`.
> * Register your debit account and tax code with HSBC for its Electronic Tax Payment Service before you send a tax payment.
> * HSBC checks each tax payment against the tax authority's records. Make the tax item amounts add up to the payment `amount`.
> * Acme treats the payment as a tax payment only when `taxPayment.localTaxType` is provided.
> * Acme builds the tax narrative for HSBC from the `taxPayment` fields. `paymentDetails` is not sent for a tax payment.
> * For a monthly, quarterly or `K` period, Acme takes the year from `paymentDate`.
> * For example, a `Dec` period paid on `2027-01-10` is reported as December 2027.
> * Use a `YYYY` period to name the year yourself.
> * For a tax payment, send both `receiver.bank` and `receiver.localRoutingIdentifier`, or leave both out.
> * If you leave both out, Acme sends `receiver.name` as the receiving bank's name.

| field | pattern / charset | max length | mandatory/optional |
| --- | --- | --- | --- |
| payments[N].taxPayment.localTaxType | `01` or `02` or `03` or `04` | 2 | M |
| payments[N].taxPayment.taxCode | Taxpayer's tax code (MST) | 10 to 14 | M |
| payments[N].taxPayment.collectingAuthorityCode | Tax collecting authority code (CQT) | | M |
| payments[N].taxPayment.stateTreasuryCode | State treasury code (KB) | | M |
| payments[N].taxPayment.onBehalfOfTaxPayerName | Name of the taxpayer, when you pay on their behalf | | O |
| payments[N].taxPayment.taxItems[N].taxPeriod | `Jan` to `Dec`, `Q1` to `Q4`, `K1` to `K9`, or a year `YYYY` (case sensitive) | | M |
| payments[N].taxPayment.taxItems[N].chapterCode | Chapter code (C) | | M |
| payments[N].taxPayment.taxItems[N].subItemCode | Sub-item code (TM) | | M |
| payments[N].taxPayment.taxItems[N].amount | Integer amount in VND, 1 to 999,999,999 | | M |

* `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.

| `taxPeriod` | sent as | meaning |
| --- | --- | --- |
| `Jan` | `00/01/<year>` | monthly |
| `Q1` | `00/Q1/<year>` | quarterly |
| `K3` | `00/K3/<year>` | by period |
| `2026` | `00/CN/2026` | yearly |

Example Request:

```json
{
  "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_ACH [#vn_ach]

> **Important**
>
> * Low value domestic batch transfer.
> * Currency must be **VND only**.
> * `purposeOfPayment` is mandatory. Acme sends it as the end-to-end ID of the payment.
> * Send the receiver bank's BIC in `receiver.bank` and its 8 digit local bank code in `receiver.localRoutingIdentifier`.
> * Acme sends the first 8 characters of `receiver.bank` (BIC8).
> * If `bankChargeBearer` is not provided, Acme sends `SENDER`.

| 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].purposeOfPayment | ASCII | 35 | M |
| payments[N].paymentDetails | ASCII | 140 | O |
| payments[N].bankChargeBearer | `SENDER` or `RECEIVER` or `SHARED` <br /> Default to `SENDER` if not provided. | | 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 | 140 | M |
| payments[N].receiver.bank | BIC | 11 | M |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | M |
| payments[N].receiver.localRoutingIdentifier | 8 digits (local bank code) <br /> Example: `01203001` | 8 | 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": "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"
      }
    }
  ]
}
```

## 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.
> * `receiver.address.country` is mandatory.
> * If `bankChargeBearer` is not provided, Acme sends `SHARED`.

| 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` <br /> Default to `SHARED` if not provided. | | 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 | 140 | M |
| payments[N].receiver.bank | BIC | 11 | M |
| payments[N].receiver.bankAccountNumber | Alphanumeric | 34 | 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 | M |

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

## Bank references [#bank-references]

`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:

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