# Acme Citibank Taiwan Payments (H2H) (/guides/citi-tw-payments)
This describes validations / allowed data formats for Acme payments going
through Citibank Taiwan (CITITWTXXXX). These will be validated by Acme and further validated by
the bank. These rules may be stricter than what the bank requires.
### 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
### Citibank restrictions [#citibank-restrictions]
* For SWIFT character set: Citibank may reject fields that start with `/`, `-`, or `:`.
### Receiver address mapping: [#receiver-address-mapping]
* `receiver.address.city` and `receiver.address.country` map to dedicated structured fields (`TwnNm` and `Ctry`) in the bank file.
* For `BKTR`, the bank file always sends `Ctry` as `TW` regardless of what the client sends; Acme only validates that `receiver.address.country` is `TW` when provided.
* `receiver.address.line1` and `receiver.address.line2` each take a dedicated `AdrLine` slot when present.
* `receiver.address.city`, `receiver.address.state`, `receiver.address.postalCode`, and `receiver.address.country` are additionally combined into any remaining `AdrLine` capacity, so they may appear in both structured fields and address lines (for example, `city` = `Taipei` and `country` = `TW` can produce `Taipei`, `TW`, and `Taipei TW`).
* The full address must fit in **3 lines of 35 SWIFT characters**. `line1` and `line2` take priority over the combined remainder; if the address cannot be formatted within those limits, Acme rejects the request.
## BKTR [#bktr]
Book transfer between accounts held at Citibank Taiwan (CITITWTXXXX).
* For TWD, the amount must not have cents / digits after the decimal point (you must send amount ending in `00`).
* `paymentDate` cannot be in the past. Maximum 21 days forward.
* `receiver.address.country` is fixed to `TW`.
| field | pattern / charset | max length | mandatory/optional |
| ---------------------------------------- | ------------------------------------------------------------- | -------------------------- | ------------------ |
| payments\[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments\[N].paymentDetails | SWIFT | 140 | O |
| payments\[N].paymentAdviceEmails\[N] | Valid email address
Example: `["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 | 35 | O |
| payments\[N].receiver.address.country | Fixed value `TW` | 2 | O |
## TT [#tt]
Telegraphic transfer for international payments.
* Payment date cannot be in the past. Maximum 21 days forward.
* For TWD, the amount must not have cents / digits after the decimal point (you must send amount ending in `00`).
* Taiwan Central Bank regulatory reporting enforces `beneficiaryType`, `transactionNature`, `purposeCode`, `subCode`, and `specialApproval`. Acme assembles them into a `/TWNREG/[beneficiaryType][transactionNature][purposeCode][subCode][specialApproval][internetBankingFlag]` string for the bank. Acme sets `internetBankingFlag` to `W`; clients do not send this field.
* Refer to the **Taiwan Central Bank Reporting Code** provided by Citibank for the specification.
| field | pattern / charset | max length | mandatory/optional |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- | ------------------ |
| payments\[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments\[N].paymentDetails | SWIFT | 140 | O |
| payments\[N].paymentAdviceEmails\[N] | Valid email address
Example: `["finance@company.com"]` | 50 per email (max 1 email) | O |
| payments\[N].instructionForSenderBank | SWIFT | 35 | O |
| payments\[N].bankChargeBearer | `SENDER` / `RECEIVER` / `SHARED` | | O |
| payments\[N].beneficiaryType | `1` Government / `2` Public / `3` Private / `4` FX Funds | 1 | M |
| payments\[N].transactionNature | One of `S` `Y` `B` `A` `C` `I` `G` `J` `E` `R` `T` `X` `4` | 1 | M |
| payments\[N].purposeCode | Alphanumeric (`0`-`9`, `A`-`Z`), exactly 3 characters
Example: `194` | 3 | M |
| payments\[N].subCode | One of `A` `B` `C` `D` `E` `F` `G` `I` `R` `S` `T` `X` `Y` `Z`
Required when `purposeCode` is `692`, `693`, or `695`. Optional otherwise. | 1 | Conditional |
| payments\[N].specialApproval | `Y` / `N` | 1 | M |
| payments\[N].receiver.name | SWIFT | 35 | M |
| payments\[N].receiver.bank | BIC (8 or 11 characters, [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362)) | 11 | M |
| payments\[N].receiver.intermediaryBank | BIC (8 or 11 characters) | 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 |
| payments\[N].receiver.address.state | SWIFT | 35 | O |
| payments\[N].receiver.address.postalCode | SWIFT | 35 | O |
| payments\[N].receiver.address.country | [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | 2 | M |
## TW\_ACH [#tw_ach]
Taiwan domestic ACH transfer.
* Currency must be **TWD only**.
* The amount must not have cents / digits after the decimal point (you must send amount ending in `00`).
* Payment date cannot be in the past. Maximum 365 days forward.
* `receiver.name` must be in Han script (Chinese characters).
| field | pattern / charset | max length | mandatory/optional |
| -------------------------------------------- | ---------------------------------------------------------------------- | -------------------------- | ------------------ |
| payments\[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments\[N].paymentDetails | SWIFT | 140 | O |
| payments\[N].paymentAdviceEmails\[N] | Valid email address
Example: `["finance@company.com"]` | 50 per email (max 1 email) | O |
| payments\[N].receiver.name | Han script (Chinese) only | 70 | M |
| payments\[N].receiver.localRoutingIdentifier | Numeric (7 digits exactly) | 7 | 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 | 35 | O |
| payments\[N].receiver.address.country | [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | 2 | O |
## TW\_RTGS [#tw_rtgs]
Taiwan domestic RTGS transfer for high-value payments.
* Currency must be **TWD only**.
* The amount must not have cents / digits after the decimal point (you must send amount ending in `00`).
* Payment date cannot be in the past. Maximum 365 days forward.
* `receiver.name` must be in Han script (Chinese characters).
* If `address` is provided, both `city` and `country` are mandatory.
| field | pattern / charset | max length | mandatory/optional |
| -------------------------------------------- | ---------------------------------------------------------------------- | -------------------------- | ------------------ |
| payments\[N].customerReference | SWIFT (uppercase only) | 15 | O |
| payments\[N].paymentDetails | SWIFT | 140 | O |
| payments\[N].paymentAdviceEmails\[N] | Valid email address
Example: `["finance@company.com"]` | 50 per email (max 1 email) | O |
| payments\[N].receiver.name | Han script (Chinese) only | 70 | M |
| payments\[N].receiver.localRoutingIdentifier | Numeric (7 digits exactly) | 7 | 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 | 35 | O |
| payments\[N].receiver.address.country | [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) | 2 | O |